Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
A estrutura de eventos do Microsoft Dataverse permite detectar quando os eventos ocorrem no servidor e executar código personalizado em resposta. Use a estrutura de eventos para estender o comportamento padrão da plataforma registrando plug-ins, fluxos de trabalho, integrações do Azure e webhooks.
Todos os recursos para estender o comportamento padrão da plataforma dependem da estrutura de eventos. Quando você configura um fluxo de trabalho para responder a um evento usando o designer de fluxo de trabalho sem escrever código, a estrutura de eventos fornece esse evento.
Como desenvolvedor, use a ferramenta de Registro de Plug-ins para configurar plug-ins, integrações do Azure, provedores de dados de tabelas virtuais e webhooks para responder a eventos que a estrutura de eventos fornece. Quando ocorrem eventos e você registra uma extensão para responder a eles, a estrutura passa informações contextuais sobre os dados envolvidos na operação para a extensão. Dependendo de como você configura o registro para o evento, a extensão pode modificar os dados passados para ele, iniciar algum processo automatizado a ser aplicado imediatamente ou definir que uma ação seja adicionada a uma fila para ser executada posteriormente.
Para aproveitar a estrutura de eventos para suas extensões personalizadas, você deve entender:
- Quais eventos estão disponíveis
- Como o evento é processado
- Que tipo de dados estão disponíveis para sua extensão personalizada quando o evento ocorre
- Quais são as restrições de tempo e recursos que se aplicam?
- Como monitorar o desempenho
Eventos disponíveis
Conforme descrito em Usar mensagens com o SDK para .NET, a plataforma Dataverse baseia operações de dados em mensagens e cada mensagem tem um nome. A plataforma inclui Create, Retrieve, RetrieveMultiple, Update, , DeleteAssociatee Disassociate mensagens que abrangem as operações de dados básicas que ocorrem com tabelas. A plataforma também inclui mensagens especializadas para operações mais complexas e ações personalizadas adicionam novas mensagens.
Quando você usa a ferramenta de Registro de Plug-in para associar uma extensão a uma mensagem específica, registre-a como uma etapa. A captura de tela a seguir é a caixa de diálogo Registrar Nova Etapa usada ao registrar um plug-in.
Uma etapa fornece as informações sobre a qual mensagem as extensões devem responder, bem como várias outras opções de configuração. Use o campo Mensagem para escolher a mensagem à qual sua extensão responde.
Em geral, você pode esperar encontrar uma mensagem para a maioria das classes de solicitação nos namespaces Microsoft.Crm.Sdk.Messages ou Microsoft.Xrm.Sdk.Messages. Você também encontra mensagens para todas as ações personalizadas criadas na organização. A plataforma não disponibiliza nenhuma operação que envolva definições de tabela.
O sistema armazena dados sobre mensagens nas tabelas SdkMessage e SdkMessageFilter . A ferramenta de registro de plug-in filtra essas informações para mostrar apenas mensagens válidas.
Para verificar se uma combinação de mensagens e tabelas dá suporte à execução de plug-ins usando uma consulta de banco de dados, use a seguinte consulta de API Web:
[Organization URI]/api/data/v9.2/sdkmessages?$select=name
&$filter=isprivate eq false
and (name ne 'SetStateDynamicEntity'
and name ne 'RemoveRelated'
and name ne 'SetRelated' and
name ne 'Execute')
and sdkmessageid_sdkmessagefilter/any(s:s/iscustomprocessingstepallowed eq true
and s/isvisible eq true)
&$expand=sdkmessageid_sdkmessagefilter($select=primaryobjecttypecode;
$filter=iscustomprocessingstepallowed eq true and isvisible eq true)
&$orderby=name
Dica
Você pode exportar esses dados para uma planilha do Excel usando esta consulta e as instruções fornecidas nesta postagem no blog: Localizar mensagens e tabelas qualificadas para plug-ins usando o Dataverse.
Você também pode usar o FetchXML a seguir para recuperar essas informações. O FetchXML Builder é uma ferramenta útil para executar esse tipo de consulta.
<fetch>
<entity name='sdkmessage'>
<attribute name='name' />
<link-entity name='sdkmessagefilter'
alias='filter'
to='sdkmessageid'
from='sdkmessageid'
link-type='inner'>
<filter type='and'>
<condition attribute='iscustomprocessingstepallowed'
operator='eq'
value='1' />
<condition attribute='isvisible'
operator='eq'
value='1' />
</filter>
<attribute name='primaryobjecttypecode' />
</link-entity>
<filter>
<condition attribute='isprivate'
operator='eq'
value='0' />
<condition attribute='name'
operator='not-in'>
<value>SetStateDynamicEntity</value>
<value>RemoveRelated</value>
<value>SetRelated</value>
<value>Execute</value>
</condition>
</filter>
<order attribute='name' />
</entity>
</fetch>
Cuidado
A Execute mensagem está disponível, mas você não deve registrar extensões para ela, pois todas as operações a chamam.
Observação
Em determinados casos, a plataforma pode chamar plug-ins e fluxos de trabalho que você registra para o evento de Atualização duas vezes. Para obter mais informações, consulte Comportamento de operações de atualização especializadas.
Pipeline de execução de eventos
Ao registrar uma etapa usando a ferramenta Registro de Plug-in, você também deve escolher o Estágio de Execução do Pipeline de Eventos. Cada mensagem é processada em uma série de quatro estágios, conforme descrito na tabela a seguir:
| Nome | Descrição |
|---|---|
| Pré-validação | Para a operação inicial, esse estágio ocorrerá antes da operação do sistema principal. Isso oferece uma oportunidade de incluir a lógica para cancelar a operação antes da transação de banco de dados. As operações subsequentes disparadas por extensões registradas em outros estágios também passarão por esse estágio, mas serão incluídas na transação das extensões de chamada. Esse estágio ocorre antes que as verificações de segurança sejam realizadas para verificar se o usuário chamador ou conectado tem a permissão correta para executar a operação pretendida. |
| PreOperation | Ocorre antes da operação principal do sistema e dentro da transação de banco de dados. Se você quiser alterar os valores de uma entidade incluída na mensagem, faça isso aqui. Evite cancelar uma operação aqui. O cancelamento disparará uma reversão da transação e terá um impacto significativo no desempenho. |
| OperaçãoPrincipal | Para uso interno apenas, exceto para API personalizada e provedores de dados de tabela virtual personalizados. Mais informações: Criar e usar APIs personalizadas Provedores de dados de tabela virtual personalizados |
| PostOperation | Ocorre após a operação principal do sistema e dentro da transação de banco de dados. Use esse estágio para modificar as propriedades da mensagem antes que ela seja retornada ao chamador. Evite aplicar alterações a uma entidade incluída na mensagem porque isso disparará um novo evento update. No estágio PostOperation, você pode registrar etapas para usar o modo de execução assíncrono. Essas etapas serão executadas fora da transação de banco de dados usando o serviço assíncrono. Você deve usar o modo assíncrono ao registrar seu plug-in se o plug-in for projetado para executar uma operação de atualização e estiver registrado na mensagem Criar da entidade Usuário (SystemUser). Mais informações: serviço assíncrono. |
O estágio escolhido depende da finalidade da extensão. Você não precisa aplicar toda a lógica de negócios em uma única etapa. Você pode aplicar várias etapas para que sua lógica sobre a possibilidade de permitir que uma operação continue pode estar no estágio PreValidation e sua lógica para fazer modificações nas propriedades da mensagem pode ocorrer no estágio PostOperation .
Importante
Uma exceção gerada pelo código em qualquer estágio síncrono dentro da transação de banco de dados faz com que toda a transação seja revertida. Verifique se o código lida com possíveis casos de exceção. Se você quiser cancelar a operação, detecte essa condição no estágio PreValidation e gere uma InvalidPluginExecutionException contendo uma mensagem apropriada que descreva por que a operação foi cancelada.
Você pode registrar várias extensões para a mesma mensagem e estágio. Dentro do registro da etapa, o valor da Ordem de Execução determina a ordem na qual o sistema processa várias extensões para um determinado estágio.
O sistema armazena informações sobre as etapas registradas na tabela SdkMessageProcessingStep.
Etapas de plug-in assíncronas
Ao se registrar no estágio PostOperation , você pode registrar a etapa a ser executada no Modo de Execução Assíncrona. Esses plug-ins são executados após a conclusão da operação de registro.
Esse comportamento geralmente é necessário ao trabalhar com registros associados ao registro atual, mas criados em um processo diferente. Por exemplo, um UserSettings relacionado a um SystemUser registro específico não é criado até que a linha SystemUser seja criada.
Mais informações: serviço assíncrono
Contexto do evento
Se a extensão for um plug-in, ela receberá um parâmetro que implementa a IPluginExecutionContext interface. Essa classe fornece informações sobre as Stage para as quais o plug-in se registra. Ele também fornece informações sobre o ParentContext, que fornece detalhes sobre toda e qualquer operação em outro plug-in que acionou a operação atual.
Se sua extensão for um ponto de extremidade do Barramento de Serviço do Azure, um tópico dos Hubs de Eventos do Azure ou um webhook, os dados postados no ponto de extremidade registrado serão fornecidos na forma de um RemoteExecutionContext. Esta classe implementa tanto IPluginExecutionContext quanto IExecutionContext.
Para obter mais informações sobre o contexto de execução, consulte Noções básicas sobre o contexto de execução.