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.
Depois que um plug-in é gravado e compilado, ele deve ser registrado com a estrutura event para ser executado quando uma entidade específica (linha de tabela) e uma mensagem (operação) são processadas por Microsoft Dataverse. Registrar um plug-in com o Dataverse requer o uso de uma ferramenta – a PRT (ferramenta de registro de plug-in) ou a extensão ferramentas do Power Platform para Visual Studio.
O PRT cria registros de objeto do Dataverse e dá suporte à edição desses registros. Este artigo descreve como registrar uma assemblagem de plug-in e uma etapa de processamento de mensagens, adicionar uma assemblagem a uma solução e realizar outras operações comuns relacionadas a plug-ins usando a ferramenta de Registro de Plug-ins.
A extensão Visual Studio fornece um ambiente de desenvolvimento mais rico em recursos e abrange todo o processo de desenvolvimento, incluindo codificação, implantação e depuração e criação de perfil. Para obter informações sobre como usar a extensão ferramentas do Power Platform para Visual Studio, consulte o quickstart.
Sobre a ferramenta de Registro de Plug-in
A ferramenta de registro de plug-in (PRT) suporta o registro de assemblies de plug-in, etapas de processamento de mensagens e outros tipos de objetos com o Dataverse. PRT é uma das várias ferramentas do Dataverse disponíveis para download do NuGet.org. Siga as instruções nas ferramentas de desenvolvimento do Dataverse para baixar PRT e, opcionalmente, outras ferramentas de desenvolvimento.
Depois de baixar o PRT, siga o Connect usando as instruções da ferramenta de Registro de Plug-in para conectar a ferramenta ao ambiente do Dataverse de destino em que o plug-in deve ser registrado.
Registro de assemblagem
Registrar um assembly (conjunto de componentes) inclui carregar o assembly no banco de dados do Dataverse, o que é feito pela ferramenta para você. Veja as instruções encontradas em Registrar seu assembly no Tutorial: Escrever e registrar um plug-in
Observação
Você encontrará opções relacionadas ao modo de isolamento e à localização da montagem. Essas opções se aplicam a implantações locais. O Dataverse não está disponível para implantações locais, portanto, sempre aceite as opções padrão de Sandbox e Banco de Dados.
Quando um assembly é carregado, ele é armazenado na tabela PluginAssembly. A maioria das propriedades é definida usando o reflexo do assembly importado. Os bytes codificados em base64 do assembly são armazenados na Content coluna. Ao exibir as Propriedades do assembly no PRT, você só pode editar o valor Descrição. Todas as classes compiladas no assembly que implementam a interface IPlugin ou derivam CodeActivity são registradas automaticamente.
Exibir assemblies registrados
Você pode acessar informações sobre assemblies de plug-in registrados e passos no Power Apps e na visualização de assembly PRT. Para acessar informações de plug-in no Power Apps, escolha Solutions no painel de navegação esquerdo e escolha uma solução disponível na lista. Em seguida, escolha plug-in assemblies ou passos de plug-in no painel Objetos esquerdo.
Observação
Cada assembly registrado é adicionado à Solução Padrão, que não deve ser confundida com a Solução Padrão dos Serviços de Dados Comuns. Para obter mais informações sobre soluções, consulte Introdução às soluções
Adicionar seu assembly a uma solução
Conforme descrito em Exibir assemblies registrados, o registro de montagem criado foi adicionado à Solução Padrão do sistema. Você deve adicionar seu assembly a uma solução não gerenciada, assim você pode distribuí-lo para outras organizações. O PRT não permite que você especifique uma solução ao cadastrar um assembly ou etapas.
Para saber mais sobre soluções e como criar uma, consulte a visão geral de soluções e crie uma solução. Depois de criar uma solução, você pode adicionar seu assembly de plug-in a ela no Power Apps escolhendo primeiro a solução na lista de soluções, e depois escolha Add existing>More>Developer>Plug-in assembly.
Observação
Quaisquer registros de etapa existentes ou subsequentes (consulte a próxima seção) não são adicionados à solução não administrada que inclui os conjuntos de plug-in. Você deve adicionar cada etapa registrada à solução separadamente. Mais informações: Adicionar etapa à solução
Registro de passos
Registrar uma etapa de processamento de mensagens informa o Dataverse em quais condições seu plug-in deve ser executado e como executá-lo. Por condições, estamos nos referindo à tabela e à operação de mensagens processadas pelo Dataverse. Outras opções de configuração, como execução síncrona ou assíncrona, antes ou depois da operação principal, e mais podem ser especificadas durante o registro da etapa. Essas opções de configuração de runtime são detalhadas na próxima seção.
Quando um assembly é carregado ou atualizado, todas as classes que implementam IPlugin são disponibilizadas no PRT. Use as instruções em Registrar uma nova etapa no Tutorial: Gravar e registrar um plug-in para criar um registro de etapa.
Campos de informações de configuração geral
| Campo | descrição |
|---|---|
| Mensagem | A mensagem que, quando processada pelo Dataverse, resulta na execução do plug-in.
Se uma entidade primária não for especificada para mensagens principais como |
| Entidade Principal | A entidade (tabela) que, quando processada pelo Dataverse, resulta na execução do plug-in.
As mensagens têm um |
| Entidade Secundária | Esse campo permanece para compatibilidade com versões anteriores para mensagens preteridas que aceitavam uma matriz de EntityReference como parâmetro Target. Normalmente, esse campo não é mais usado. |
| Atributos de Filtragem | Para a Update, OnExternalUpdated ou outra mensagem, quando você define a entidade primária, o filtro de atributos (colunas) limita a execução do plug-in aos casos em que as colunas especificadas estão incluídas na atualização. Inclua somente colunas com valores alterados em operações de atualização. Se uma solicitação contiver um atributo de filtragem, o plug-in será disparado independentemente de o valor do atributo ser alterado ou não.Definir esse campo é uma prática recomendada para o desempenho. Não inclua a chave primária da entidade nos atributos de filtragem. A chave primária é sempre incluída em operações de atualização, portanto, isso nega todos os outros atributos filtrados. |
| Manipulador de Eventos | Esse valor de campo é preenchido no PRT com base no nome do assembly e na classe de plug-in. |
| Nome da etapa | O nome da etapa de processamento de mensagens. Um valor é pré-preenchido com base na configuração da etapa, mas esse valor pode ser substituído. |
| Executar no contexto do usuário | Fornece opções para aplicar a personificação para o passo. O valor padrão é Chamar Usuário. Se o usuário de chamada não tiver privilégios para executar operações na etapa, talvez seja necessário definir esse valor de campo para um usuário que tenha esses privilégios. Mais informações: Definir a impersonação de usuário para uma etapa |
| Ordem de Execução | Várias etapas podem ser registradas para o mesmo estágio e mensagem. O número neste campo determina a ordem na qual as etapas são aplicadas dentro de um estágio do mais baixo para o mais alto. Você deve definir esse campo para controlar a ordem na qual os plug-ins são executados no mesmo estágio. Não é recomendável simplesmente aceitar o valor padrão. A ordem de execução real de plug-ins com o mesmo valor da Ordem de Execução (para o mesmo estágio, tabela e mensagem) não é garantida e pode ser aleatória. |
| Description | Uma descrição para a etapa. Esse valor é pré-preenchido, mas pode ser substituído. |
Estágio de execução do Pipeline de Eventos
Escolha o estágio no pipeline de eventos que melhor se adapte ao propósito do seu plug-in. Os prefixos "Pre" e "Post" referem-se a ações anteriores ou posteriores ao funcionamento principal do Dataverse (núcleo). A operação principal é o estágio em que a combinação de mensagem e entidade é processada.
| Opção | 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. |
| 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. |
Mais informações: Pipeline de execução de eventos
Modo de Execução
Há dois modos de execução: assíncrono e síncrono.
| Opção | descrição |
|---|---|
| Assíncrono | O contexto de execução e a definição da lógica de negócios a ser aplicada são movidos para a fila de trabalho do sistema, que será executada em algum momento após a conclusão da operação principal. |
| Síncrono | Os plug-ins são executados imediatamente de acordo com o estágio de execução e a ordem de execução. Toda a operação aguarda até que seja concluída. |
Plug-ins assíncronos podem ser cadastrados apenas para o estágio PostOperation. Para obter mais informações sobre como funcionam os trabalhos do sistema, consulte o serviço assíncrono
Cenários especiais de registro de etapas
Existem certos cenários em que um registro e combinação de tabela de etapas não são óbvios. Isso é o resultado de como o sistema é projetado internamente onde há uma relação especial entre tabelas ou operações. As informações fornecidas aqui identificam esses casos e fornecem orientações para o registro de etapas.
- Há certos casos em que os plug-ins registrados para o evento Update podem ser chamados duas vezes. Mais informações: Comportamento de operações de atualização especializadas
- Registre uma etapa de plug-in na conta ou contato quando quiser lidar com alterações de dados em registros customeraddress, leadaddress, publisheraddress ou competitoraddress .
Implantação
| Opção | descrição |
|---|---|
| Servidor | O plug-in é executado no servidor do Dataverse. |
| Offline | O plug-in é executado no Dynamics 365 para Outlook cliente quando o usuário está no modo offline. |
Definir dados de configuração
Os campos Configuração Não Segura e Configuração Segura no PRT permitem que você especifique os dados de configuração a serem passados para o plug-in para uma etapa específica.
Observação
Dados de configuração segura não são incluídos no registro da etapa quando você exporta uma solução.
Você pode escrever seu plug-in para aceitar valores de cadeia de caracteres no construtor para usar esses dados para controlar como o plug-in deve funcionar para a etapa. Mais informações: fornecer dados de configuração para o plug-in
Definir imagens de entidade
No plug-in, talvez você queira fazer referência aos valores de propriedade da tabela primária que não foram incluídos em uma operação. Por exemplo, em uma Update operação, talvez você queira saber qual era um valor antes de ser alterado, mas o contexto de execução não fornece essas informações, inclui apenas o valor alterado.
Se a etapa de plug-in estiver registrada nos estágios PreValidation ou PreOperation do pipeline de execução, você poderá usar a instância IOrganizationService para recuperar o valor atual da propriedade, o que não é uma boa prática para o desempenho. Uma prática melhor é definir uma imagem de pré-entidade ao registrar a etapa de plug-in. A imagem de pré-entidade captura um 'instantâneo' da tabela com os campos nos quais você está interessado, pois eles existiam antes da operação que você pode usar para comparar com os valores alterados.
Importante
O comportamento padrão ao criar uma imagem de entidade é selecionar todas as colunas. Não use esse comportamento padrão. Retornar todas as colunas afeta negativamente o desempenho. Inclua somente as colunas exigidas pela lógica do plug-in.
Mensagens que suportam imagens de entidade
No Dataverse, somente as seguintes mensagens dão suporte a imagens de entidade:
| Message | Propriedade da Classe Request | descrição |
|---|---|---|
Assign |
Target |
A tabela atribuída. |
Create |
Target |
A tabela criada. |
Delete |
Target |
A tabela excluída. |
DeliverIncoming |
EmailId |
O ID de e-mail entregado. |
DeliverPromote |
EmailId |
O ID de e-mail enviado. |
Merge |
Target ou SubordinateId |
A tabela pai, na qual os dados da tabela filha estão sendo mesclados, ou a tabela filha que está sendo mesclada na tabela pai. |
Route |
Target |
O item que está sendo roteado. |
Send |
FaxId, EmailId ou TemplateId |
O item que está sendo enviado. |
SetState |
EntityMoniker |
A tabela para a qual o estado está definido. |
Update |
Target |
A tabela atualizada. |
Tipos de imagens de entidade
Há dois tipos de imagens de entidade: Pré-Imagem e Imagem de Postagem. Quando você configurá-las, essas imagens estarão disponíveis no contexto de execução, respectivamente, como propriedades PreEntityImages e PostEntityImages. Como os nomes sugerem, esses instantâneos representam a aparência da tabela antes da operação principal e após a operação principal. Ao configurar uma imagem de entidade, você definirá um valor-chave de alias para tabela, que será o valor que você usará para acessar uma imagem de entidade específica da propriedade PreEntityImages ou PostEntityImages.
Disponibilidade de imagens
Quando você configura uma imagem de entidade, é importante reconhecer que o tipo de imagens de entidade disponíveis depende do estágio da etapa registrada e do tipo de operação. Por exemplo:
- Você não pode ter uma Pré-Imagem para a
Createmensagem porque a tabela ainda não existe. - Você não pode ter uma Imagem de Postagem para a
Deletemensagem porque a tabela não existirá mais. - Você só pode ter um Post Image para etapas registradas no estágio PostOperation do pipeline de execução, porque não é possível saber quais propriedades a tabela terá até que a transação seja concluída.
- Para uma
Updateoperação registrada no estágio PostOperation, você pode ter tanto uma Pré-imagem quanto uma Pós-imagem.
Adicionar uma imagem de entidade
Use a extensão Power Platform Tools para Visual Studio para adicionar uma imagem de entidade a uma etapa de plug-in.
Como alternativa, você pode usar a Ferramenta de Registro de Plug-in para adicionar uma imagem de entidade a uma etapa seguindo as instruções no Tutorial: Atualizar um plug-in na seção Adicionar uma imagem.
Adicionar uma etapa a uma solução
Conforme mencionado em Adicionar seu assembly a uma solução, os Assemblies de Plug-in são componentes de solução que podem ser adicionados a uma solução não gerenciada. As Etapas de Processamento de Mensagens do Sdk também são componentes da solução e também devem ser adicionadas a uma solução não gerenciada para serem distribuídas.
O procedimento para adicionar uma etapa a uma solução é semelhante ao de adicionar um assembly. Você usará o comando Adicionar Existente para movê-lo para a solução não gerenciada desejada. A única diferença é que, se você tentar adicionar uma etapa, mas ainda não tiver adicionado o assembly que contém a classe usada na etapa, será solicitado que você adicione componentes necessários ausentes.
Se você encontrar isso, geralmente deverá selecionar OK para importar o assembly com a solução não gerenciada. A única vez que você não selecionaria isso é se sua solução foi projetada para ser instalada em um ambiente em que outra solução que contém o assembly já está instalada.
Da mesma forma, você deve observar que a remoção do assembly da solução não removerá nenhuma etapa que dependa dele.
Definir a representação do usuário para uma etapa
Com a ferramenta de Registro de Plug-in em execução e conectada ao ambiente de destino do Dataverse, você pode continuar a definir ou alterar um registro de etapa de plug-in. Nesta seção, discutiremos a alteração do usuário em nome de quem o plug-in executará suas operações. Ou seja, o usuário efetivo que está executando as operações de dados iniciadas pelo plug-in. Por padrão, o usuário chamador (o usuário que invocou uma operação no Dataverse) é o proprietário dessas operações. No entanto, um usuário diferente pode ser especificado no registro da etapa. Você precisa ter a função de segurança Administrador do Sistema ou Personalizador de Sistema ou qualquer função que contenha o privilégio prvSetImpersonatingUserIdOnSdkMessageProcessingStep para executar essa operação.
Para definir o contexto de usuário de uma etapa de plug-in:
- Expanda o nó de montagem do plug-in de destino na visão de montagem até encontrar o nó de registro desejado (Etapa).
- Escolha o nó da etapa e escolha Atualizar no menu de contexto ou na barra de ferramentas.
- Escolha um usuário na lista suspensa de usuários disponíveis ao lado do rótulo Executar no Contexto do Usuário .
- Escolha a Etapa de Atualização.
Mais informações: fazer-se passar por um usuário
Atualizar um componente assembly
Ao alterar e recompilar um assembly que você registrou anteriormente, será necessário atualizá-lo. Consulte a seção Atualizar o registro do assembly do plug-in em Tutorial: Atualizar um plug-in para ver os passos.
Controle de versão do assembly
Se você estiver fazendo alterações em um assembly de plug-in que faz parte de uma solução gerenciada que foi implantada, você precisará considerar o impacto que suas alterações podem ter ao atualizar essa solução gerenciada. A versão do assembly controlará o comportamento.
Os assemblies de plug-in podem ser versionados usando um formato de controle de versão semântico major.minor.build.revision definido no arquivo Assembly.info do projeto Microsoft Visual Studio. Dependendo de qual parte do número de versão do assembly for alterada em uma solução mais recente, o comportamento a seguir se aplica quando uma solução existente é atualizada por meio da importação.
O número de versão do assembly de build ou revisão é alterado
Isso é considerado uma atualização no local. A versão mais antiga do assembly é removida quando a solução que contém o assembly atualizado é importada. Todas as etapas pré-existentes da solução mais antiga são alteradas automaticamente para se referir à versão mais recente do assembly.
O número da versão maior ou menor do assembly é alterado
Quando uma solução atualizada que contém o assembly revisado é importada, o assembly é considerado um assembly diferente da versão anterior desse assembly na solução existente. As etapas de registro de plug-in na solução existente continuarão a se referir à versão anterior do conjunto. Se você quiser que as etapas de registro de plug-in existentes para o assembly anterior apontem para o assembly revisado, você precisará usar a ferramenta Registro de Plug-in para alterar manualmente a configuração da etapa para se referir ao tipo de assembly revisado. Isso deve ser feito antes de exportar o conjunto atualizado para uma solução para ser importada posteriormente.
Cancelar o registro ou desabilitar plug-ins e componentes
Você pode cancelar o registro ou desabilitar plug-ins e seus componentes usando a PRT (ferramenta de registro de plug-in).
Importante
Não é mais possível cancelar o registro ou desabilitar os plug-ins de sistema da Microsoft ou os plug-ins e configurações de sistema prontos para uso. Anteriormente, você era capaz de cancelar o registro ou desabilitar alguns dos Microsoft.* e outros plug-ins de sistema prontos para uso. Alteramos esse comportamento para não permitir mais isso. A alteração na funcionalidade foi feita porque cancelar o registro ou desabilitar esses plug-ins ou etapas pode fazer com que os recursos do produto não funcionem conforme o esperado. Se você precisar cancelar o registro ou desabilitar esse plug-in ou etapa, registre uma solicitação de suporte Microsoft.
Desabilitar ou habilitar uma etapa de plug-in
Com a ferramenta de Registro de Plug-in em execução e conectada ao ambiente do Dataverse de destino, você pode continuar a desabilitar ou habilitar uma etapa de plug-in. Desabilitar uma etapa efetivamente impede o plug-in de ser executado quando o Dataverse processa a entidade e a combinação de mensagens especificada no registro da etapa.
Importante
Desabilitar um plug-in pode afetar negativamente a funcionalidade de seu aplicativo, uma solução ou o sistema Dataverse. Certifique-se de entender as implicações antes de continuar.
Para desabilitar ou habilitar uma etapa de plug-in registrada:
- Expanda o nó de montagem do plug-in de destino na visualização da montagem até ver o nó desejado de registro de etapas.
- Escolha a etapa e escolha Habilitar ou Desabilitar no menu de contexto ou na barra de ferramentas.
Você também pode desabilitar ou habilitar etapas na interface do usuário herdada do Dataverse Gerenciador de Soluções usando as opções de comando Activate e Deactivate.
Em Power Apps, desabilite ou habilite as etapas de plug-in usando as opções "Desativar" e "Ativar" da etapa escolhida. Você pode acessar as opções de etapa primeiro navegando até Soluções, escolhendo uma solução e, em seguida, no painel Objetos à esquerda, escolha as etapas de plug-in.
Cancelar o registro de componentes
O PRT fornece comandos para cancelar o registro de assemblies, tipos, etapas e imagens. Consulte as instruções de assembly, plug-in e etapa de cancelamento de registro no Tutorial: Atualizar um plug-in para o procedimento.
Essas são operações de exclusão nas tabelas PluginAssembly, PluginType, SdkMessageProcessingStep e SdkMessageProcessingStepImage .
Você também pode excluir assemblies plug-in e etapas de processamento de mensagens do SDK no Gerenciador de Soluções para obter o mesmo resultado. Na figura abaixo, uma solução personalizada chamada Common Data Service Default Solution é mostrada.
Observação
Não é possível excluir (cancelar o registro) de assemblies de plug-in enquanto as Etapas de Processamento de Mensagens do Sdk existentes dependem deles. As imagens de entidade não estão disponíveis para serem excluídas separadamente, mas serão excluídas quando todas as etapas que as usam forem excluídas.
Próximas Etapas
Consulte também
Criar plug-ins para estender processos de negócios
Escrever um plug-in
Tutorial: Escrever e registrar um plug-in
Tutorial: Depurar um plug-in
Tutorial: Atualizar um plug-in