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 fora do formulário e há dados não salvos no formulário.
• A opção Guardar Automaticamente está ativada 30 segundos após a alteração dos dados e a existência de dados não guardados 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 do formulário.

Suporte a manipulador de eventos assíncrono

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

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

Se a promessa for rejeitada ou atingir 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 quiser impedir que o evento save aconteça se houver um erro de script/promessa rejeitada ou o tempo limite do manipulador.

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 liquidadas, 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 envolver 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 envolva todas as promessas necessárias. Esta prática é para 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 Serviço, você precisa validar se o Ativo do Cliente selecionado tem a mesma conta listada na Ordem de Serviço. Buscar a conta na Ordem de Serviço 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 ambas 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"));
   });
 }

Ativar Async OnSave usando a configuração do aplicativo

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

1. Aceda a https://make.powerapps.com.

2. Certifique-se de selecionar o ambiente correto.

3. Selecione Aplicações no painel de navegação esquerdo.

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

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

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

7. Ative o manipulador Async onSave.

8. Selecione Guardar.

   

Async OnSave tempos limite

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

Há cenários em que pausar o OnSave manipulador por mais de 10 segundos é necessário. 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. Continua à espera que a promessa do manipulador seja cumprida.

Esse padrão deve ser usado com cautela, pois pode afetar o desempenho do salvamento de formulário.

Artigos relacionados

Evento Grid OnSave
Eventos (referência da API do cliente)
Eventos em formulários e grelhas em aplicações condicionadas por modelo