Depurar um plug-in
Publicado: janeiro de 2017
Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
As etapas a seguir descrevem como depurar um plug-in em execução no Microsoft Dynamics 365 local. Para depurar um plug-in que é executado na área restrita em Microsoft Dynamics 365 (online), você deve usar o rastreamento como descrito posteriormente neste tópico.
Neste tópico
Depurar um plug-in no modo seguro
Registro e rastreamento
Depurar um plug-in
Implantar e registrar o conjunto de plug-in.
Se houver outra cópia do conjunto no mesmo local e você não conseguir substituir essa cópia, pois está bloqueada pelo Microsoft Dynamics 365, você deverá reiniciar o processo de serviço que estava executando o plug-in. Consulte a tabela abaixo para o processo de serviço correto.Para obter mais informações: Registrar e implantar plug-ins
Configurar o depurador.
Anexe o depurador ao processo no servidor Microsoft Dynamics 365 que executará o plug-in. Consulte a tabela a seguir para identificar o processo.
Configuração do registro de plug-in
Processo de Serviço
on-line
w3wp.exe
off-line
Microsoft.Crm.Application.Hoster.exe
plug-ins registrados assíncronos (ou conjuntos de fluxo de trabalho personalizados)
CrmAsyncService.exe
área restrita (modo de isolamento)
Microsoft.Crm.Sandbox.WorkerProcess.exe
Se houver vários processos executando o mesmo arquivo executável, por exemplo vários processos de w3wp.exe, anexe o depurador em todas as instâncias do processo executável em execução. Em seguida, defina um ou mais pontos de interrupção no código de plug-in.
Teste o plug-in.
Execute o aplicativo Microsoft Dynamics 365 ou outro aplicativo personalizado que usa o SDK e execute todas as medidas necessárias para executar o plug-in. Por exemplo, se um plug-in for registrado em um evento de criação de contas, crie uma nova conta.
Depure o código de plug-in.
Faça as alterações necessárias no seu código para que ele seja executado conforme desejado. Se o código for modificado, compile o código em um conjunto e repita as etapas 1 a 4 nesse procedimento, conforme necessário. No entanto, se você modificar os números da versão principal ou secundária do conjunto de plug-in, você deve cancelar o registro da versão anterior do conjunto e registrar a nova versão.Para obter mais informações: Registrar e implantar plug-ins
Registrar o plug-in na base de dados.
Depois que o ciclo editar/compilar/implantar/testar/depurar do plug-in for concluído, cancele o registro do conjunto do plug-in (no disco) e, em seguida, registre novamente o plug-in na base de dados Microsoft Dynamics 365.Para obter mais informações: Registrar e implantar plug-ins
Dica
É possível depurar um plug-in implantado da base de dados. O arquivo de símbolo do conjunto de plug-in compilado (.pdb) deve ser copiado para a <raiz-crm>\Server\bin\assembly pasta do servidor e Serviços de Informações da Internet (IIS) deve então ser reiniciado. Após a depuração ser concluída, você deve remover o arquivo de símbolo e redefinir o IIS para evitar o processo que estava executando o plug-in de consumir memória adicional.
Para obter mais informações sobre depurar um plug-in usando a ferramenta Criador de perfil de Plug-in, consulte Analisar desempenho do plug-in.
Depurar um plug-in no modo seguro
É importante executar essas etapas antes da primeira execução de um plug-in no modo seguro. Se o plug-in já tiver sido executado, altere o código do conjunto, fazendo com que o hash do conjunto seja alterado no servidor ou reinicie o serviço de Processamento em área restrita Microsoft Dynamics 365 no servidor de área restrita.
Configure o servidor
O processo hospedeiro da área restrita monitora o processo de trabalho na área restrita que está executando o plug-in. O processo hospedeiro verifica se o plug-in deixa de responder, se está excedendo limites de memória e muito mais. Se o processo de trabalho não responder em 30 segundos, ele será desligado. Para depurar um plug-in de área restrita, é necessário desabilitar esse recurso desligamento. Para desabilitar o recurso de desligamento, defina a seguinte chave de registro para 1 (DWORD):
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM\SandboxDebugPlugins
Depurar o Plug-in
Siga estas etapas para depurar um plug-in em modo seguro.
Registre o plug-in na área restrita (modo de isolamento) e implante-o na base de dados do servidor Microsoft Dynamics 365.
Copie o arquivo de símbolo (.pdb) do conjunto de plug-in compilado para a pasta server\bin\assembly no servidor que executa o processo de trabalho na área restrita chamado Microsoft.Crm.Sandbox.WorkerProcess.exe. Este é servidor que hospeda a função do Serviço de processamento em área restrita.
Siga as instruções das etapas 2 a 4 apresentadas no início deste tópico.
Para obter mais informações sobre depurar um plug-in usando a ferramenta Criador de perfil de Plug-in, consulte Analisar desempenho do plug-in.
Registro e rastreamento
Um método alternativo para solucionar problemas com uma atividade de fluxo de trabalho personalizado ou de plug-in (código personalizado), comparado à depuração no Microsoft Visual Studio, é usar o rastreamento. O rastreando ajuda os desenvolvedores, registrando as informações personalizadas de tempo de execução, como uma ajuda no diagnóstico da causa de falhas do código. O rastreamento é muito útil para solucionar problemas no código personalizado registrado do Microsoft Dynamics 365 (online), pois ele é o único método de solução de problemas com suporte para esse cenário. O rastreamento tem suporte para o código personalizado registrado de área restrita (confiança parcial) e de confiança total, e durante a execução síncrona ou assíncrona. O rastreamento não tem suporte para código personalizado executado no Microsoft Dynamics 365 para Outlook ou em outro cliente móvel.
A gravação das informações de rastreamento em tempo de execução para o Microsoft Dynamics 365 é fornecida por um serviço chamado ITracingService. As informações fornecidas para esse serviço pelo código personalizado podem ser registradas em três locais diferentes, conforme identificado aqui.
Registro de rastreamento
Os registros de rastreamento do tipo PluginTraceLog podem ser encontrados no aplicativo Web, navegando até Configurações e escolhendo o bloco Log de Rastreamento de Plug-in. O bloco é visível apenas se você tem acesso aos registros de entidade do registro de rastreamento em seu direito de acesso atribuído. A gravação desses registros é controlada pelas configurações de rastreamento mencionadas na próxima seção. Para obter informações sobre os privilégios necessários para a entidade PluginTraceLog, consulte Privilégios por entidade.
Observação
O registro de rastreamento utiliza o espaço de armazenamento da organização, especialmente quando são gerados muitos rastreamentos e exceções. Você só deve ativar o registro de rastreamento para depurar e solucionar problemas, e desativá-lo após a conclusão da investigação.
Caixa de diálogo de Erro
Uma atividade síncrona de plug-in registrado ou de fluxo de trabalho personalizado que retorna uma exceção para a plataforma resulta em uma caixa de diálogo de erro no aplicativo Web apresentado para o usuário conectado. O usuário pode selecionar o botão Baixar Arquivo de Log na caixa de diálogo para exibir o log que contém a saída de exceção e de rastreamento.
Trabalho do sistema
Para atividades assíncronas de plug-in registrado ou de fluxo de trabalho personalizado que retornem uma exceção, as informações de rastreamento são exibidas na área Detalhes do formulário Trabalho do Sistema no aplicativo da Web.
Habilitar o registro de rastreamento
Para habilitar o registro de rastreamento em uma organização que ofereça suporte a esse recurso, no aplicativo da Web, navegue até Configurações > Administração > Configurações do Sistema. Na guia Personalização, localize o menu suspenso Habilitar registro no log de rastreamento do plug-in e selecione uma das opções disponíveis.
Opção |
Descrição |
|---|---|
Desligado |
A gravação no log de rastreamento está desabilitada. Nenhum registro PluginTraceLog será criado. Entretanto, o código personalizado ainda pode chamar o método Trace, apesar de nenhum log ter sido gravado. |
Exceções |
As informações de rastreamento são gravadas no log se uma exceção é transmitida para a plataforma do código personalizado. |
Tudo |
As informações de rastreamento são gravadas no log quando o código é concluído ou se uma exceção é transmitida para a plataforma do código personalizado. |
Se a configuração do registro de rastreamento estiver definida como Exceção e o código personalizado retornar uma exceção para a plataforma, um registro de log de rastreamento será criado e as informações de rastreamento também serão gravadas em outro local. Para o código personalizado que é executa sincronamente, a informações são apresentadas ao usuário uma caixa de diálogo de erro; caso contrário, para o código assíncrono, as informações são gravadas no trabalho do sistema relacionado.
Por padrão, as funções Administrador do Sistema e Personalizador do Sistema têm os privilégios necessários para alterar a configuração do registro de rastreamento, que é armazenado em um registro da entidade TraceSettings. As configurações de rastreamento têm um escopo da organização.
Gravar no serviço de rastreamento
Antes de gravar no serviço do rastreamento, primeiro extraia o objeto de serviço de rastreamento do contexto de execução passado. Depois, basta adicionar chamadas do Trace para o código personalizado, onde for apropriado, transmitindo todas as informações de diagnóstico relevantes nessa chamada de método.
//Extract the tracing service for use in debugging sandboxed plug-ins.
ITracingService tracingService =
(ITracingService)serviceProvider.GetService(typeof(ITracingService));
// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
// For this sample, execute the plug-in code only while the client is online.
tracingService.Trace("AdvancedPlugin: Verifying the client is not offline.");
if (context.IsExecutingOffline || context.IsOfflinePlayback)
return;
// The InputParameters collection contains all the data passed
// in the message request.
if (context.InputParameters.Contains("Target") &&
context.InputParameters["Target"] is Entity)
{
// Obtain the target entity from the Input Parameters.
tracingService.Trace
("AdvancedPlugin: Getting the target entity from Input Parameters.");
Entity entity = (Entity)context.InputParameters["Target"];
// Obtain the image entity from the Pre Entity Images.
tracingService.Trace
("AdvancedPlugin: Getting image entity from PreEntityImages.");
Entity image = (Entity)context.PreEntityImages["Target"];
Em seguida, crie e implante o plug-in ou a atividade personalizada de fluxo de trabalho. Durante a execução do código personalizado, as informações fornecidas nas chamadas de método Trace são gravadas em um registro de entidade de registro de rastreamento pelo ITracingService, se tiver suporte na sua organização e estiver habilitado, e podem ser disponibilizadas para o usuário em um diálogo da Web ou em um trabalho do sistema, conforme descrito na seção anterior. Informações de rastreamento gravadas no registro de rastreamento são definidas nas configurações de rastreamento. Para obter mais informações, consulte Habilitar o registro de rastreamento.
Observação
Se o código personalizado for executado em uma transação do banco de dados, e ocorrer uma exceção que cause uma reversão da transação, todas as alterações dos dados da entidade pelo seu código serão desfeitas. Entretanto, os registros PluginTraceLog permanecerão após a conclusão da reversão.
Sobre o serviço de rastreamento
O ITracingService processa as informações fornecidas em lotes através do método Trace. As informações são gravadas em um novo registro PluginTraceLog após a conclusão com êxito da execução do código personalizado ou após uma exceção ser gerada.
A vida útil dos registros PluginTraceLog é finita. Um trabalho em segundo plano de exclusão em massa é executado uma vez por dia para excluir registros com mais 24 horas desde a criação. Esse trabalho pode ser desabilitado quando necessário.
Confira Também
Desenvolvimento de plug-in
Analisar desempenho do plug-in
Registrar e implantar plug-ins
Pipeline de execução do evento
Gravar um plug-in
Isolamento, estatísticas e confianças de plug-in
Mensagens e métodos da entidade PluginTraceLog
Microsoft Dynamics 365
© 2017 Microsoft. Todos os direitos reservados. Direitos autorais