Exercício: escrever seu primeiro plug-in

Concluído

Neste cenário, uma organização precisa garantir que os dados de número de telefone sejam inseridos em um formato consistente. Para alcançar esse objetivo, você criará um plug-in para ser executado em condições create/update que remova todos os caracteres não numéricos de um número de telefone antes de salvar no Dataverse. Em seguida, você criará outro plug-in que será executado em condições Contact retrieve/retrievemultiple para reformatar o número de telefone para incluir parênteses e traços, se os dados existirem. 

Exercício 1: Criar/atualizar um plug-in

Neste exercício, você criará um plug-in que será executado em condições create e update. Esse plug-in removerá todos os caracteres não numéricos de um número de telefone.

Cada exercício consiste em um cenário e objetivos de aprendizado. O cenário descreve a finalidade dos exercícios, enquanto os objetivos são listados e têm marcadores.

Observação

Se você não tiver as ferramentas do SDK do Dynamics 365, consulte Baixar ferramentas do NuGet para baixar.

Tarefa 1: Criar um plug-in

1. Inicie o Visual Studio 2022.

2. Selecione Arquivo > Novo > Projeto.

3. Selecione Biblioteca de Classes (.NET Framework) e Avançar.

   

4. Insira D365PackageProject para Nome do Projeto, selecione um local para salvar o projeto, selecione .NET Framework 4.6.2 para Estrutura e, depois, Criar.

   

5. Clique com o botão direito do mouse no projeto e selecione Gerenciar Pacotes NuGet.

   

6. Selecione a guia Procurar, procure e selecione microsoft.crmsdk.coreassemblies e, depois, Instalar.

   

7. Leia os termos de licença e selecione Aceitar se concordar.

8. Feche o Gerenciador de pacotes NuGet.

9. Clique com o botão direito do mouse em Class1.cs e em Excluir.

10. Clique com o botão direito do mouse no projeto e selecione Adicionar > Classe.

11. Nomeie a nova classe PreOperationFormatPhoneCreateUpdate e selecione Adicionar.

    

12. Adicione as instruções using à nova classe da seguinte maneira:

     using Microsoft.Xrm.Sdk;
    
     using System.Text.RegularExpressions;
    

13. Torne a classe pública e implemente interface IPlugin.

    

14. Implemente o membro de interface.

    

    Sua classe agora deve ser semelhante à imagem a seguir.

    

Tarefa 2: Formatar um número de telefone

1. Obtenha o contexto de execução do provedor do serviço. Substitua a exceção no método Execute pelo trecho a seguir.

    IPluginExecutionContext context =
    (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
   

2. Verifique o parâmetro de entrada para Target. Adicione o trecho a seguir ao método Execute.

    if (!context.InputParameters.ContainsKey("Target"))
   
    throw new InvalidPluginExecutionException("No target found");
   

3. Adicione o trecho a seguir ao método Execute. Este trecho obterá a entidade de destino do parâmetro de entrada e verificará se seus atributos contêm telephone1 (Telefone Comercial para Contatos, Telefone para Contas).

    var entity = context.InputParameters["Target"] as Entity;
   
    if (!entity.Attributes.Contains("telephone1"))
   
    return;
   

4. Adicione o trecho a seguir à função Execute. Este trecho removerá todos os caracteres não numéricos do número de telefone fornecido pelo usuário.

    string phoneNumber = (string)entity["telephone1"];
   
    var formattedNumber = Regex.Replace(phoneNumber, @"[^\d]", "");
   

5. Defina telephone1 como o número de telefone formatado. Adicione o trecho a seguir ao método Execute.

    entity["telephone1"] = formattedNumber;
   

   O método Execute deverá ser semelhante à imagem a seguir.

   

6. Clique com o botão direito do mouse no projeto e selecione Propriedades.

   

7. Selecione a guia Assinatura, marque a caixa Assinar o assembly e selecione Novo Arquivo de Chave.

   

8. Insira contoso.snk no campo Nome do arquivo de chave, desmarque a caixa de seleção Proteger meu arquivo de chave com uma senha e selecione OK.

   

9. Feche a guia Propriedades.

10. Crie o projeto e verifique se a criação teve êxito.

Tarefa 3: Registrar um plug-in e as etapas

Observação

Se você não tiver as ferramentas do SDK do Dynamics 365, consulte Baixar ferramentas do NuGet para baixar.

1. Inicie o aplicativo da Plug-in Registration Tool.

2. Selecione Criar Nova Conexão.

   

3. Selecione Office 365, marque a caixa de seleção Mostrar Avançado, forneça suas credenciais e selecione Logon.

   

4. Selecione Registrar e, depois, Registrar Novo Assembly.

   

5. Selecione Procurar.

   

6. Navegue até a pasta Bin >Debug da biblioteca de classes criada, selecione D365PackageProject.dll e Abrir.

   

7. Selecione Registrar Plug-ins Selecionados.

   

8. Selecione OK.

9. Expanda o assembly recém-registrado.

   

10. Clique com o botão direito do mouse no plug-in e selecione Registrar Nova Etapa.

    

11. Selecione Create para Mensagem e contact para Entidade Principal.

    

12. Selecione PreOperation para Etapa de Execução do Pipeline de Eventos e, em seguida, selecione Registrar Nova Etapa.

    

13. Selecione Fechar.

14. Clique com o botão direito do mouse no plug-in e selecione Registrar Nova Etapa novamente.

    

15. Selecione Update para Mensagem, selecione contact para Entidade Principal e, em seguida, selecione a pesquisa Atributos.

    

16. Desmarque a caixa de seleção Selecionar Tudo, marque a caixa de seleção Telefone Comercial e selecione OK.

    

17. Selecione PreOperation para Etapa de Execução do Pipeline de Eventos e, em seguida, selecione Registrar Nova Etapa.

Tarefa 4: Testar o plug-in

1. Vá para seu Maker Portal e verifique se selecionou o ambiente correto.

2. Selecione Aplicativos e inicie o aplicativo Fundraiser.

   

3. Selecione Painel e abra um dos contatos.

   

4. Selecione + Novo.

   

5. Insira Teste em Nome, Contato em Sobrenome, (123)-555-0100 em Telefone Comercial e selecione Salvar.

   

   O registro deve ser salvo, e agora o Telefone Comercial deve mostrar apenas os valores numéricos.

   

6. Altere o Telefone Comercial para 001-123-555-0100 e aguarde alguns segundos.

   O registro deve ser atualizado, e agora o Telefone Comercial deve mostrar apenas os valores numéricos.

   

Exercício 2: Criar/recuperar vários plug-ins

Neste exercício, você criará um plug-in que será executado em condições retrieve e retrieve multiple. Esse plug-in adicionará parênteses e traços aos números de telefone.

Cada exercício consiste em um cenário e objetivos de aprendizado. O cenário descreve a finalidade dos exercícios, enquanto os objetivos são listados e têm marcadores.

Tarefa 1: Criar um plug-in

1. Inicie o Visual Studio.

2. Abra o projeto que você criou no Exercício 1.

3. Clique com o botão direito do mouse no projeto e selecione Adicionar > Classe.

   

4. No campo Nome, insira PostOperationFormatPhoneOnRetrieveMultiple para a classe e selecione Adicionar.

5. Adicione as instruções using à nova classe da seguinte maneira:

    using Microsoft.Xrm.Sdk;
   

6. Torne a classe pública e implemente interface IPlugin.

7. Implemente o membro de interface. Sua classe agora deve ser semelhante à imagem a seguir.

   

Tarefa 2: Formatar número de telefone para retrieve

1. Obtenha o contexto de execução do provedor do serviço. Substitua a exceção no método Execute pelo trecho a seguir.

    IPluginExecutionContext context =
    (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
   

2. Verifique se o nome da mensagem é Retrieve ou RetrieveMultiple. Adicione o trecho a seguir ao método Execute.

    if (context.MessageName.Equals("Retrieve"))	
    {
   
    }	
    else if(context.MessageName.Equals("RetrieveMultiple"))	
    {
   
    }
   

3. Verifique se os parâmetros de saída contêm uma entidade comercial e se é um tipo de entidade. Cole o trecho a seguir dentro da condição if retrieve.

    if (!context.OutputParameters.Contains("BusinessEntity") && context.OutputParameters["BusinessEntity"] is Entity)
    throw new InvalidPluginExecutionException("No business entity found");
   

4. Obtenha a entidade e verifique se ela contém o campo telephone1. Adicione o trecho a seguir dentro da condição if retrieve.

    var entity = (Entity)context.OutputParameters["BusinessEntity"];
   
    if (!entity.Attributes.Contains("telephone1"))	
        return;
   

5. Adicione o trecho a seguir à condição if retrieve. Este trecho tentará analisar telephone1 como long e retornará se a análise não tiver êxito.

    if (!long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
   
    return;
   

6. Formate o número do telefone adicionando parênteses e traços. Adicione o trecho a seguir dentro da condição if retrieve.

    var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
    entity["telephone1"] = formattedNumber;
   

A parte recuperada do método Execute agora deve ser semelhante à imagem a seguir.

Tarefa 3: Formatar número de telefone para retrieve multiple

1. Adicione o trecho a seguir dentro da condição retrieve multiple. Este trecho verificará se os parâmetros de saída contêm BusinessEntityCollection e se é do tipo EntityCollection.

    if(!context.OutputParameters.Contains("BusinessEntityCollection") && context.OutputParameters ["BusinessEntityCollection"] is EntityCollection)
        throw new InvalidPluginExecutionException("No business entity collection found");
   

2. Obtenha a coleção de entidades dos parâmetros de saída. Adicione o trecho a seguir dentro da condição retrieve multiple.

    var entityCollection = (EntityCollection)context.OutputParameters["BusinessEntityCollection"];
   

3. Itere por meio de cada entidade da coleção de entidades.

    foreach (var entity in entityCollection.Entities)	
    {
   
    }
   

4. Adicione o trecho a seguir dentro da condição foreach. Este trecho fará a mesma coisa que a condição retrieve está fazendo.

    if (entity.Attributes.Contains("telephone1") && entity["telephone1"] != null)
    {
       if (long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
       {
           var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
           entity["telephone1"] = formattedNumber;
       }
    }
   

   A parte retrieve multiple do método Execute agora deve ser semelhante à imagem a seguir.

   

5. Recompile o projeto e verifique se a compilação foi bem-sucedida.

Tarefa 4: Atualizar o assembly do plug-in e registrar etapas

1. Inicie a Plug-in Registration Tool e selecione Criar Nova Conexão.

   

2. Selecione Office 365 e Mostrar Avançado, forneça suas credenciais e selecione Logon.

3. Selecione o assembly registrado no Exercício 1 e, em seguida, selecione Atualizar.

   

4. Selecione Procurar.

5. Navegue até a pasta debug do seu projeto, selecione D365PackageProject.dll e, em seguida, selecione Abrir.

   

6. Selecione os plug-ins e, depois, Atualizar Plug-ins Selecionados.

   

7. Selecione OK.

8. Clique com o botão direito do mouse no novo plug-in e selecione Registrar Nova Etapa.

9. Selecione Retrieve para Mensagem, contact para Entidade Principal e PostOperation para Etapa de Execução do Pipeline de Eventos. Certifique-se de selecionar Síncrono para Modo de Execução e, em seguida, selecione Registrar Nova Etapa.

   

10. Clique com o botão direito do mouse no plug-in e selecione Registrar Nova Etapa novamente.

11. Selecione RetrieveMultiple para Mensagem, contact para Entidade Principal e PostOperation para Etapa de Execução do Pipeline de Eventos. Certifique-se de selecionar Síncrono para Modo de Execução e, em seguida, selecione Registrar Nova Etapa.

Tarefa 5: Testar o plug-in

1. Acesse o Maker Portal e verifique se você está no ambiente correto.

2. Selecione Aplicativos. Em seguida, selecione o aplicativo Fundraiser e selecione Editar. Você adicionará a tabela Contato ao aplicativo.

   

3. Selecione + Nova página.

4. Selecione Tabela do Dataverse e, depois, Avançar.

5. Selecionar Tabela existente. Em seguida, selecione a tabela Contato e Adicionar.

   

6. Selecione Reproduzir.

   

7. Selecione Salvar e continuar.

8. Selecione Reproduzir novamente.

9. Selecione Contatos.

10. Os registros existentes que não foram salvos com o novo formato não serão alterados. Selecione + Novo.

    

11. Forneça as informações a seguir e selecione Salvar. O registro deve ser salvo, e o plug-in deve aplicar o novo formato.

12. Selecione Contatos novamente. O registro que você criou deve ter o novo formato.

    

13. Selecione um dos contatos existentes para abri-lo.

    

14. Edite o Telefone Comercial da seguinte forma:

    

15. Selecione Salvar. O novo formato deve ser aplicado. Selecione Contatos mais uma vez.

    

O telefone editado deverá ter o novo formato.