Evento Form OnSave (referência da API do cliente) em aplicativos controlados por modelo

O OnSave evento ocorre quando:

• O usuário seleciona o botão Salvar ou Atualizar na barra de comandos, mesmo quando não há dados alterados a serem salvos.
• O código executa o método formContext.data.entity.save , mesmo quando não há dados alterados a serem salvos.
• O usuário navega para longe do formulário e há dados não salvos no formulário.
• A opção Salvamento Automático está habilitada, 30 segundos após a alteração dos dados e há dados não salvos no formulário.
• O código executa o método formContext.data.save e há dados não salvos no formulário.
• O código executa o método formContext.data.refresh passando um valor verdadeiro como o primeiro parâmetro e há dados não salvos no formulário.

Para determinar qual botão foi clicado para executar o salvamento, use o método getSaveMode .

Você pode cancelar a ação de salvamento usando o método preventDefault dentro do objeto de argumentos de evento. O método preventDefault é acessível usando o método getEventArgs que faz parte do contexto de execução. O contexto de execução é passado automaticamente para o manipulador de eventos de formulário.

Suporte ao manipulador de eventos assíncrono

O evento OnSave tem a capacidade de esperar que as promessas retornadas pelos manipuladores de eventos sejam resolvidas antes de salvar, permitindo que o OnSave evento seja assíncrono ("assíncrono").

O OnSave evento se torna assíncrono quando o OnSave manipulador de eventos retorna uma promessa. O salvamento do registro ocorre quando cada promessa retornada por um manipulador é resolvida. Para quaisquer promessas retornadas, há um limite de 10 segundos para cada promessa, depois disso, a plataforma considera que as promessas serão cronometrada. Esse tempo limite é aplicado por promessa. Por exemplo, se tivermos cinco promessas retornadas, o tempo total de espera será de 50 segundos.

Se a promessa for rejeitada ou o tempo limite, a operação de salvamento continuará a se comportar de forma semelhante aos erros de script atuais. Use o método preventDefault dentro do objeto de argumentos de evento nesse manipulador específico se você quiser impedir que o evento de salvamento ocorra se houver um erro de script/promessa rejeitada ou o manipulador atingir o tempo limite.

Você também pode cancelar a operação de salvamento independentemente do erro no manipulador ou não usar o método preventDefault dentro do objeto de argumentos de evento. Se esse método for chamado, o evento Async OnSave aguardará que todas as promessas sejam resolvidas, mas o salvamento não ocorrerá. Chamar esse método significa que a lógica dentro .then() de > .catch() será executada.

O OnSave evento aguarda uma promessa retornada por manipulador. Se várias promessas forem necessárias, é recomendável encapsular todas as promessas no Promise.all() método e retornar a única promessa resultante. Para vários manipuladores que retornam uma promessa, recomendamos que você crie um manipulador que chame todos os eventos e retorne uma única promessa que encapsula todas as promessas necessárias. Essa prática é minimizar os tempos de espera causados pelo tempo limite.

Cenário de exemplo sobre quando usar manipuladores onSave assíncronos

Considere a criação de uma Tarefa de Serviço de Ordem de Trabalho, você precisa validar que o Ativo do Cliente selecionado tem a mesma conta listada na Ordem de Trabalho. Buscar a conta na Ordem de Trabalho e no Ativo do Cliente são processos assíncronos e precisam ser concluídos antes que a validação possa ocorrer.

Nesse cenário, como há vários processos assíncronos e ambas as chamadas retornam uma única promessa encapsulando ambos no Promise.all() método.

Por exemplo:

 function myHandler() {
    return Promise.all([getWorkOrderPromise, getCustomerAssetPromise]).then((values) => {
        var workOrder = values[0];
        var customerAsset = values[1];
        // Perform validation
        if (isValid(workOrder, customerAsset)) {
            return Promise.resolve();
        }
        return Promise.reject(new Error("Validation failed for the work order and customer asset"));
   });
 }

Habilitar o OnSave assíncrono usando a configuração do aplicativo

Para usar manipuladores de onSave assíncronos, você precisa habilitá-lo por meio de uma configuração de aplicativo:

1. Ir para https://make.powerapps.com.

2. Selecione o ambiente correto.

3. Selecione Aplicativos no painel de navegação esquerdo.

4. Selecione o aplicativo e selecione ... (reticências). Selecione Editar.

5. Selecione Configurações na barra de comandos .

6. Quando a caixa de diálogo for aberta, selecione Recursos.

7. Ative o manipulador Async onSave.

8. Clique em Salvar.

   

Tempos limite do OnSave assíncrono

Quando você usa um manipulador assíncrono OnSave , o formulário aguarda que a promessa retornada pelo manipulador seja atendida. Para garantir que a salvação do formulário seja concluída em tempo hábil, o manipulador gerará uma exceção de tempo limite após 10 segundos para que você saiba como ajustar o manipulador assíncrono OnSave para melhor desempenho.

Há cenários em que é necessário pausar o OnSave manipulador por mais de 10 segundos. Um exemplo é abrir uma caixa de diálogo e aguardar a entrada do usuário antes de continuar a salvar. Para garantir que a operação assíncrona aguarde a promessa ser resolvida, use o método disableAsyncTimeout .

Por exemplo:

async function myHandler(context) {  
     context.getEventArgs().disableAsyncTimeout();
     // The 10000ms time out will not be disabled if the above line does not come before all async awaits
     await Xrm.Navigation.openConfirmDialog({ text: "Are you sure you want to save?" });
 }

Quando disableAsyncTimeout é chamado, o tempo limite para esse manipulador não é aplicado. Ele continua aguardando que a promessa desse manipulador seja cumprida.

Esse padrão deve ser usado com cuidado, pois pode afetar o desempenho do formulário salvo.

Artigos relacionados

Evento onSave de grade
Eventos (referência à API do cliente)
Eventos em formulários e grades em aplicativos baseados em modelos