Depuração de plug-ins

O processo de desenvolvimento, registro e depuração de um plug-in é:

  1. Criar um projeto de biblioteca de classes do .NET Framework no Visual Studio
  2. Adicionar o Microsoft.CrmSdk.CoreAssemblies pacote NuGet ao projeto
  3. Implemente a interface IPlugin nas classes que você registra como etapas.
  4. Adicionar seu código ao Execute método exigido pela interface
    1. Obter referências aos serviços necessários
    2. Adicionar sua lógica de negócios
  5. Assinar e compilar o assembly
  6. Teste a montagem
    1. Registre a montagem em um ambiente de teste
    2. Adicionar o assembly registrado e suas etapas a uma solução não gerenciada
    3. Teste o comportamento da montagem
    4. Verificar se os logs de rastreamento esperados estão gravados
    5. Depurar o assembly conforme necessário

O conteúdo deste artigo aborda as etapas anteriores em negrito e dá suporte aos seguintes tutoriais:

Teste sua montagem

A maneira mais simples de testar sua montagem talvez seja executar a operação manualmente por meio do aplicativo web. Mas você também pode iniciar eventos que fazem com que os plug-ins sejam executados de várias maneiras, como criar uma tabela a partir de um fluxo de trabalho ou usar os serviços Web.

As informações de contexto de execução podem ser diferentes dependendo de como você executa a ação. Ao escrever seu plug-in, certifique-se de seguir as práticas de programação defensiva e não suponha que todos os valores esperados estejam sempre presentes.

Talvez você queira escrever um programa que automatize a execução das operações que fazem com que o plug-in seja acionado e inclua muitas variações possíveis.

Se você quiser usar uma estrutura de automação de teste, descobrirá que a comunidade criou algumas ferramentas para testes automatizados. Para obter mais informações, consulte Ferramentas de teste para desenvolvimento no lado do servidor.

Usar rastreamento

Conforme descrito no serviço de Rastreamento, você pode gravar mensagens na Tabela PluginTraceLog dentro do código do plug-in usando o ITracingServicemétodo .Trace

Antes de usar esse serviço, você deve habilitar o rastreamento em seu ambiente de Microsoft Dataverse. O processo é descrito em Exibir logs de rastreamento.

Note

O registro em log de rastreamento ocupa o espaço de armazenamento da organização, especialmente quando gera muitos rastreamentos e exceções. Ative apenas o log de rastreamento para depuração e solução de problemas e desative-o quando terminar.

Durante a depuração, você pode consultar facilmente os logs de rastreamento para uma determinada classe de plug-in usando a API Web em seu navegador. Se o assembly se chamar BasicPlugin.FollowUpPlugin, você poderá usar esta consulta na barra de endereços do navegador:

GET <your org uri>/api/data/v9.0/plugintracelogs?$select=messageblock&$filter=startswith(typename,'BasicPlugin.FollowUpPlugin')

Os resultados JSON são retornados para o navegador da seguinte maneira:

{
    "@odata.context": "<your org uri>/api/data/v9.0/$metadata#plugintracelogs(messageblock)",
    "value": [{
        "messageblock": "FollowupPlugin: Creating the task activity.",
        "plugintracelogid": "f0c221d1-7f84-4f89-acdb-bbf8f7ce9f6c"
    }]
}

Dica

Isso funcionará melhor se você instalar uma extensão de navegador que formate o JSON retornado. Ou talvez você queira usar um cliente de API, como Postman ou Insomnia, ou talvez queira usar o VS Code com o PowerShell.

Talvez você prefira usar o Visualizador de Rastreamento do Plug-in XrmToolbox. Essa ferramenta de comunidade não é compatível com Microsoft. Se você tiver dúvidas sobre essa ferramenta, entre em contato com o editor.

Você também pode encontrar mensagens de rastreamento no arquivo de log que você pode baixar quando um plug-in síncrono ou um assembly de fluxo de trabalho personalizado gera um erro, resultando em uma caixa de diálogo de erro exibida ao usuário. O usuário pode selecionar o botão Baixar Arquivo de Log para exibir o log que contém detalhes da exceção e da saída do rastreamento.

Para plug-ins registrados de forma assíncrona e assemblies de fluxo de trabalho que retornam uma exceção, as informações de rastreamento são mostradas na área de detalhes do formulário Trabalho do Sistema no aplicativo Web.

Note

Se o código personalizado for executado em uma transação de banco de dados e ocorrer uma exceção que cause uma reversão de transação, todas as alterações de dados de tabela pelo código serão desfeitas. No entanto, os registros da tabela PluginTraceLog permanecem mesmo após a conclusão da reversão.

Usar o profiler de plug-in

O Plug-in Profiler é uma solução que pode ser instalada no seu ambiente e permite capturar o contexto de execução de um plug-in. Use esses dados para reproduzir o evento em Visual Studio durante a depuração.

Para obter instruções sobre como instalar e usar o criador de perfil de plug-in, consulte Tutorial: Depurar um plug-in. Consulte Instalar o profiler do plug-in e Depurar seu plug-in.

Exibir dados do perfil do plug-in

Depois de instalar o profiler de plug-in e capturar alguns perfis, você poderá exibir o contexto do evento e os dados de reprodução usados durante a depuração. Exibir esses dados pode ajudá-lo a entender os dados de contexto de execução que o plug-in pode usar.

Use a ferramenta de Registro de Plug-in para exibir esses dados. Selecione o comando Exibir Perfil do Plug-in . Esse comando abre a caixa de diálogo Perfil do Plug-in.

Abrir perfil do plug-in.

Selecione o ícone de download. Na caixa de diálogo Selecionar Perfil do CRM, especifique o item de registro a ser utilizado.

Selecione o perfil no CRM.

Selecione Exibição na caixa de diálogo Perfil do Plug-in .

Essa ação baixa e abre um arquivo XML com as informações do perfil. O Context elemento representa o contexto de execução passado para o plug-in.

dados de perfil de exemplo.

Mais informações

Ferramentas de teste para desenvolvimento do lado do servidor

  • Last updated on