Manipular exceções em plug-ins

A maneira como o Dataverse gerencia exceções de plug-in depende do tipo de inscrição da etapa do plug-in.

• Exceções para etapas síncronas de plug-in cancelam e revertem a operação. Você pode controlar a mensagem retornada ao usuário.
• Exceções em etapas assíncronas de plug-in são registradas e adicionadas à tabela System Job, também conhecida como AsyncOperation Table.

Cancelar a operação atual

Em um plug-in síncrono, você pode rejeitar a solicitação de mensagem. Se a operação não seguir as regras impostas pelo plug-in, gere uma exceção InvalidPluginExecutionException e inclua os motivos na mensagem.

Idealmente, cancele as operações por meio de plug-ins síncronos registrados no estágio PreValidation. Esse estágio geralmente ocorre fora da transação de banco de dados principal. Cancele a operação antes de chegar à transação para evitar reverter a operação. Reverter a operação requer recursos significativos e afeta o desempenho do sistema. As operações nos estágios PreOperation e PostOperation sempre ocorrem dentro da transação de banco de dados.

Às vezes, os estágios de PreValidation ocorrem dentro de uma transação quando outra operação os inicia. Por exemplo, se você criar um registro de tarefa no estágio PostOperation da criação de uma conta, a criação da tarefa passará pelo pipeline de execução de eventos e ocorrerá dentro do estágio PreValidation , mas faz parte da transação que cria o registro da tabela da conta. Verifique o valor da IExecutionContextpropriedade .IsInTransaction para ver se uma operação está dentro de uma transação.

Como os aplicativos controlados por modelo lidam com exceções de plug-in síncronas

Quando você lança uma exceção InvalidPluginExecutionException dentro de um plug-in síncrono, uma caixa de diálogo de erro com sua mensagem é exibida para o usuário. Se você não fornecer uma mensagem, uma caixa de diálogo de erro genérica será mostrada ao usuário. Se você lançar qualquer outro tipo de exceção, o usuário verá uma caixa de diálogo de erro com uma mensagem genérica. A mensagem de exceção e o rastreamento da pilha são gravados na tabela PluginTraceLog.

Note

Na Interface Unificada, a caixa de diálogo de erro não dá suporte ao conteúdo codificado em HTML na mensagem. Use somente texto.

Erros inesperados

Se ocorrer uma exceção no código do plug-in para uma etapa síncrona, a operação de pipeline que está sendo processada na transação de banco de dados será cancelada e revertida, independentemente de você gerar uma InvalidPluginExecutionException ou não. InvalidPluginExecutionException é a única exceção que fornece a capacidade de controlar qual mensagem de exceção é exibida ao usuário. Esse comportamento se aplica a aplicativos controlados por modelos usados por soluções Dynamics 365.

Para ver quais tipos de dados relacionados a erros seu plug-in pode retornar à plataforma, consulte os construtores disponíveis InvalidPluginExecutionException.

Dica

Recomendamos que você pegue qualquer erro e gere uma exceção InvalidPluginExecutionException para poder controlar o que é exibido para o usuário. Esse erro pode ser simplesmente "An unexpected error occurred", mas você também pode adicionar algumas informações que ajudarão o administrador a solucionar o problema. Dessa forma, você tem algum controle. Se você permitir que outros tipos de exceções se propaguem, o erro será apresentado como um erro IsvUnExpected com a mensagem An unexpected error occurred from ISV code., o que não é muito útil.

Como as exceções de plug-ins assíncronos são tratadas

A mensagem de exceção para plug-ins assíncronos registrados é gravada em uma tabela Trabalho do Sistema, também conhecida como Tabela AsyncOperation, que pode ser visualizada na área Trabalhos do Sistema do aplicativo da Web. Nenhuma caixa de diálogo é exibida para o usuário. Os plug-ins assíncronos não participam da transação de banco de dados que os enfileira, portanto, não podem cancelar a transação.

Tentar novamente um plug-in assíncrono

Com uma etapa de plug-in assíncrona, você pode tentar novamente quando um plug-in falhar. A causa da falha pode ser devido a um erro de rede ou algum outro erro retriável chamando um recurso externo.

Para tentar novamente o plug-in, use o construtor InvalidPluginExecutionException(OperationStatus, Int32, String) usando o valor do membro OperationStatus EnumRetry .

Quando o plug-in gera esse tipo de exceção, o serviço assíncrono tenta executar o plug-in quatro vezes. Se a execução do plug-in não for bem-sucedida em quatro tentativas, a chamada falhará.