Tutorial: Gravar e registrar um plug-in

Este tutorial orienta você a escrever um plug-in e registrá-lo com Microsoft Dataverse. Primeiro, você deve ler o artigo Gravar um plug-in para se familiarizar com a gravação de um plug-in.

Você pode encontrar os arquivos completos da solução de plug-in para este tutorial aqui: Exemplo: Criar um plug-in básico.

Objetivo

Crie um plug-in assíncrono registrado na mensagem "Criar" da tabela de conta. O plug-in cria uma tarefa que lembra o criador da conta de fazer o acompanhamento uma semana depois.

Pré-requisitos

• Uma conta de Usuário do Sistema com a função Administrador ou Personalizador de Sistema no ambiente de Microsoft Dataverse de destino.
• Um aplicativo baseado em modelo que inclui a conta e as tabelas de tarefas.
  • Se você não tiver um aplicativo controlado por modelos que inclua essas tabelas, consulte Criar seu primeiro aplicativo controlado por modelos do zero para obter etapas para fazer um em apenas alguns minutos.
• Visual Studio 2019 (ou versão posterior).
• Conhecimento da linguagem de programação do Visual C#.
• Ferramenta de registro de plug-in instalada no computador de desenvolvimento. Consulte as ferramentas de desenvolvimento do Dataverse.

Criar um projeto de plug-in

Este artigo demonstra como usar Visual Studio para gravar o plug-in e compilar o assembly. No entanto, você pode usar seu editor favorito para codificar e usar o MSBuild para criar o assembly. Em ambos os casos, você deve usar a ferramenta Registro de Plug-in para registrar o plug-in com o Dataverse.

Como alternativa, você pode usar a CLI do Power Platform para criar rapidamente um novo projeto com código básico de plug-in usando o comando pac plugin init. Você ainda usaria a ferramenta de Registro de Plug-in para registrar o plug-in no Dataverse.

Outra alternativa é usar a extensão ferramentas do Power Platform, conforme descrito aqui: criar e registrar um pacote de plug-in usando Visual Studio. Nesse caso, a extensão pode criar e registrar o plug-in para que a Ferramenta de Registro de Plug-in não seja necessária.

Criar um projeto de Visual Studio para o plug-in

1. Em Visual Studio, abra um novo projeto da Biblioteca de Classes (.NET Framework) visando uma versão de estrutura com suporte.

   

   O nome usado para o projeto também é o nome do conjunto. Este tutorial usa o nome BasicPlugin.

2. Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Gerenciar Pacotes NuGet... no menu de contexto.

   

3. Selecione Procurar, pesquise por Microsoft.CrmSdk.CoreAssemblies e instale a versão mais recente.

   

4. Você deve selecionar Eu Aceito na caixa de diálogo Aceitação da Licença .

   Note

   Adicionar o pacote NuGet Microsoft.CrmSdk.CoreAssemblies incluirá esses assemblies na pasta de compilação do seu assembly, mas você não fará upload desses assemblies junto com o assembly que contém sua lógica. Esses assemblies já estão presentes no ambiente de execução em sandbox.

   Verifique se somente os assemblies referenciados diretamente pelo seu projeto ou por meio de cadeias de dependência do NuGet estão localizados na pasta de compilação. Você não pode incluir outras montagens ao registrar a montagem na sua lógica. Não é possível presumir que os assemblies, além daqueles incluídos no pacote NuGet Microsoft.CrmSdk.CoreAssemblies, estarão presentes no servidor e serão compatíveis com o seu código.

5. Em Gerenciador de Soluções, clique com o botão direito do mouse no Class1.cs arquivo e escolha Renomear no menu de contexto.

   

6. Renomeie o Class1.cs arquivo para FollowupPlugin.cs.

7. Quando solicitado, permita que Visual Studio renomeie a classe para corresponder ao nome do arquivo.

   

Editar o arquivo de classe para definir um plug-in

1. Adicione as instruções a seguir using à parte superior do FollowupPlugin.cs arquivo.

   using System.ServiceModel;  
   using Microsoft.Xrm.Sdk;
   

2. Implemente a IPlugin interface editando a classe.

   Note

   Se você digitar após : IPlugin o nome da classe, Visual Studio sugerirá automaticamente a implementação de um stub para o Método Execute.

   public class FollowupPlugin : IPlugin
   {
       public void Execute(IServiceProvider serviceProvider)
       {
           throw new NotImplementedException();
       }
   }
   

3. Substitua o conteúdo do Execute método pelo código a seguir.

// Obtain the tracing service
ITracingService tracingService =
(ITracingService)serviceProvider.GetService(typeof(ITracingService));

// Obtain the execution context from the service provider.  
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

// 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.  
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the IOrganizationService instance which you will need for  
    // web service calls.  
    IOrganizationServiceFactory serviceFactory =
        (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
    IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

    try
    {
        // Plug-in business logic goes here.  
    }

    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw new InvalidPluginExecutionException("An error occurred in FollowUpPlugin.", ex);
    }

    catch (Exception ex)
    {
        tracingService.Trace("FollowUpPlugin: {0}", ex.ToString());
        throw;
    }
}

Observações sobre o código

• O ITracingService habilita a gravação no log de rastreamento. Você pode ver um exemplo no bloco catch final. Mais informações: Usar o rastreamento
• O IPluginExecutionContext fornece acesso ao contexto do evento que executou o plug-in. Mais informações: entenda o contexto de execução.
• O código verifica se o contexto InputParameters inclui os parâmetros esperados para o CreateRequest para o qual este plug-in deve ser registrado. Se a propriedade Target estiver presente, o Entity fornecido na solicitação fica disponível.
• A IOrganizationServiceFactory interface fornece acesso a uma variável de serviço que implementa a IOrganizationService interface, que fornece os métodos que você usará para interagir com o serviço para criar a tarefa.

Adicionar lógica de negócios

O plug-in cria uma tarefa que lembra o criador da conta de fazer acompanhamento uma semana depois.

Adicione o código a seguir ao bloco try. Substitua o comentário // Plug-in business logic goes here pelo código a seguir.

// Create a task activity to follow up with the account customer in 7 days. 
Entity followup = new Entity("task");

followup["subject"] = "Send e-mail to the new customer.";
followup["description"] =
    "Follow up with the customer. Check if there are any new issues that need resolution.";
followup["scheduledstart"] = DateTime.Now.AddDays(7);
followup["scheduledend"] = DateTime.Now.AddDays(7);
followup["category"] = context.PrimaryEntityName;

// Refer to the account in the task activity.
if (context.OutputParameters.Contains("id"))
{
    Guid regardingobjectid = new Guid(context.OutputParameters["id"].ToString());
    string regardingobjectidType = "account";

    followup["regardingobjectid"] =
    new EntityReference(regardingobjectidType, regardingobjectid);
}

// Create the task in Microsoft Dynamics CRM.
tracingService.Trace("FollowupPlugin: Creating the task activity.");
service.Create(followup);

Observações sobre o código

• Esse código usa o estilo de vinculação tardia para criar uma tarefa e associá-la à conta que está sendo criada. Mais informações: criar tabelas usando o SDK para .NET
• Classes de associação antecipada podem ser usadas, mas seu uso requer a geração das classes para as tabelas e a inclusão do arquivo que define essas classes no projeto de assembly. O uso de classes associadas antecipadamente é principalmente uma preferência pessoal, portanto, essas etapas são deixadas de fora deste tutorial para fins de brevidade. Mais informações: Programação de limite tardio e limite inicial usando o SDK para .NET
• O Id da conta que está sendo criada é encontrado no contexto OutputParameters e definido como a coluna de pesquisa regardingobjectid da tarefa.

Compilar plug-in

Em Visual Studio, pressione F6 para compilar o assembly. Verifique se ele é compilado sem erros.

Assine o plug-in

1. Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto BasicPlugin e, no menu de contexto, selecione Propriedades.

   

2. Nas propriedades do projeto, selecione a guia Assinatura e marque a caixa de seleção Assinar o assembly.

   

3. Na lista suspensa Escolher um arquivo de chave de nome forte: selecione <Novo...>.

4. Na caixa de diálogo Criar Chave de Nome Forte, insira um nome do arquivo de chave e desmarque a caixa de seleção Proteger meu arquivo de chave com uma senha.

5. Selecione OK para fechar a caixa de diálogo Criar Chave de Nome Forte .

6. Na guia Compilação de propriedades do projeto, verifique se a Configuração está definida como Depurar.

7. Pressione F6 para criar o plug-in novamente.

8. Usando o Windows Explorer, localize o plug-in interno em: \bin\Debug\BasicPlugin.dll.

Registrar o plug-in

Para registrar um plug-in, você precisará da ferramenta de Registro de Plug-in.

Conectar-se usando a ferramenta de Registro de Plug-in

1. Abra a ferramenta de Registro de Plug-in executando o comando PAC CLI pac tool prt.

2. Selecione +Criar nova conexão para se conectar ao seu ambiente do Dataverse.

3. Verifique se Office 365 está marcada.

4. Se você estiver se conectando usando uma conta da Microsoft diferente de uma que você está usando no momento, selecione Mostrar Avançado e insira suas credenciais. Caso contrário, deixe Entrar como o usuário atual selecionado.

   Note

   Se sua conta de usuário emprega MFA (autenticação multifator), verifique se a caixa de seleção Mostrar Avançado não está marcada.

5. Se sua conta da Microsoft fornecer acesso a vários ambientes, selecione Exibir lista de organizações disponíveis.

   

6. Selecione Logon.

7. Se você selecionou Exibir lista de organizações disponíveis, selecione a organização à qual deseja se conectar e selecione Logon.

8. Depois de conectado, você verá todos os plug-ins registrados existentes, atividades de fluxo de trabalho personalizadas e provedores de dados.

   

Registre seu componente

1. Na lista suspensa Registro, selecione Nova Montagem.

   

2. Na caixa de diálogo Registrar novo assembly, selecione o botão de reticências (…) e localize o assembly que você criou na etapa anterior.

   

3. Para Microsoft 365 usuários, verifique se o modo de isolamento está definido como área restrita e se o local para armazenar o assembly é Banco de Dados.

   Note

   Outras opções para o modo de isolamento e a localização se aplicam a implantações de Dynamics 365 locais. Quanto ao local, você pode especificar o banco de dados do servidor D365, o armazenamento local do servidor (disco) ou o Global Assembly Cache do servidor. Para obter mais informações, consulte armazenamento de plug-ins.

4. Clique em Registrar Plug-ins Selecionados.

5. Você verá uma caixa de diálogo de confirmação de Plug-ins registrados.

   

6. Selecione OK para fechar a caixa de diálogo e fechar a caixa de diálogo Registrar nova montagem.

7. Agora você deve ver a montagem (Assembly) BasicPlugin, que você pode expandir para ver o plugin (Plugin) BasicPlugin.FollowUpPlugin.

   

Registrar uma nova etapa

1. Clique com o botão direito do mouse no (Plug-in) BasicPlugin.FollowUpPlugin e selecione Registrar Nova Etapa.

   

2. Na caixa de diálogo Registrar Nova Etapa , defina os campos a seguir.

   Setting	Value
   Mensagem	Create
   Entidade primária	conta
   Estágio de execução do pipeline de eventos	Pós-Operação
   Modo de Execução	Assíncronos

   

3. Selecione Registrar Nova Etapa para concluir o registro e fechar a caixa de diálogo Registrar Nova Etapa .

4. Agora você pode ver a etapa registrada.

   

Testar o plug-in

1. Abra um aplicativo controlado por modelos e crie uma tabela de conta.

2. Em pouco tempo, abra a conta e você pode verificar a criação da tarefa.

   

E se a tarefa não foi criada?

Como estamos trabalhando com um plug-in assíncrono, a operação para criar a tarefa ocorre após a criação da conta. Normalmente, a criação da tarefa ocorre imediatamente, mas, caso isso não aconteça, você ainda poderá visualizar a tarefa do sistema na fila, aguardando ser aplicada. Este registro da etapa usou a opção Excluir AsyncOperation se StatusCode = bem-sucedido, que é uma prática recomendada. Isso significa que, assim que o trabalho do sistema for concluído com êxito, você não poderá visualizar os dados do trabalho do sistema, a menos que registre novamente o plug-in com a opção Excluir AsyncOperation se StatusCode = Êxito desmarcada.

No entanto, se ocorreu um erro, você poderá visualizar o trabalho do sistema para consultar a mensagem de erro.

Exibir trabalhos do sistema

Use o Dynamics 365 --aplicativo personalizado para exibir trabalhos do sistema.

1. Em seu aplicativo controlado por modelos, navegue até o aplicativo.

   

2. No aplicativo Dynamics 365 --custom, navegue até Configurações>Sistema>Trabalhos do Sistema.

   

3. Ao exibir trabalhos do sistema, você pode filtrar por Tabela (Entidade). Selecione Conta.

   

4. Se o trabalho falhar, você deverá ver um registro com o nome BasicPlugin.FollowupPlugin: Create of account.

   

5. Se você abrir o trabalho do sistema, poderá expandir a seção Detalhes para exibir as informações registradas no rastreamento e os detalhes sobre o erro.

   

Tarefas do Sistema de Consulta

Você pode usar a consulta de API Web a seguir para retornar trabalhos de sistema com falha para plug-ins assíncronos.

GET <your org uri>/api/data/v9.0/asyncoperations?$filter=operationtype eq 1 and statuscode eq 31&$select=name,message

Mais informações: consultar dados usando a API Web

Ou use o seguinte FetchXml:

<fetch top='50' >
  <entity name='asyncoperation' >
    <attribute name='message' />
    <attribute name='name' />
    <filter type='and' >
      <condition attribute='operationtype' operator='eq' value='1' />
      <condition attribute='statuscode' operator='eq' value='31' />
    </filter>
  </entity>
</fetch>

Mais informações: Usar FetchXML com FetchExpression

Exibir logs de rastreamento

O código de exemplo escreveu uma mensagem no log de rastreamento. Estas próximas etapas descrevem como exibir os logs.

Por padrão, os logs de rastreamento do plug-in não são habilitados.

Use as etapas a seguir para habilitá-las em um aplicativo controlado por modelos.

1. Abra o Dynamics 365 – aplicativo personalizado.

   

2. Navegue até Configurações>Sistema>Administração.

   

3. Em Administração, selecione Configurações do Sistema.

4. Na caixa de diálogo Configurações do Sistema, na guia Personalização, defina Habilitar registro em log no log de rastreamento do plug-in como Todos.

   

   Note

   Você deve desativar o registro em log depois de terminar de testar o plug-in, ou, pelo menos, defini-lo como Exceção em vez de Todos.

5. Selecione OK para fechar a caixa de diálogo Configurações do Sistema .

6. Repita as etapas para testar o plug-in criando uma nova conta.

7. No Dynamics 365 -- aplicativo personalizado, navegue até Configurações>Personalização>Log de Rastreamento de Plug-In.

8. Você deverá ver que um novo registro de log de rastreamento de plug-in foi criado.

   

9. Se você abrir o registro, talvez espere que ele inclua as informações que você configurou no rastreamento, mas isso não acontece. Isso apenas verifica se o rastreamento ocorreu.

10. Para ver os detalhes, é mais fácil consultar esses dados na API da Web em seu navegador, usando a consulta a seguir com o tipo de entidade plugintracelog EntityType e a propriedade typename para filtrar os resultados com base na propriedade messageblock e no nome da classe do plug-in.

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

11. Você pode esperar ver essas informações formatadas em JSON retornadas com a consulta da API Web.

    {
        "@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"
        }]
    }
    

Próximas Etapas 

Neste tutorial, você criou um plug-in simples e o registrou. Tutorial Completo: Depurar um plug-in para saber como depurar esse plug-in.

Consulte também

Tutorial: Atualizar um plug-in
Escrever um plug-in
Registrar um plug-in
Depurar plug-ins.