Exercício: escrever seu primeiro plug-in
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
Inicie o Visual Studio 2022.
Selecione Arquivo > Novo > Projeto.
Selecione Biblioteca de Classes (.NET Framework) e Avançar.
Insira D365PackageProject para Nome do Projeto, selecione um local para salvar o projeto, selecione .NET Framework 4.6.2 para Estrutura e, depois, Criar.
Clique com o botão direito do mouse no projeto e selecione Gerenciar Pacotes NuGet.
Selecione a guia Procurar, procure e selecione microsoft.crmsdk.coreassemblies e, depois, Instalar.
Leia os termos de licença e selecione Aceitar se concordar.
Feche o Gerenciador de pacotes NuGet.
Clique com o botão direito do mouse em Class1.cs e em Excluir.
Clique com o botão direito do mouse no projeto e selecione Adicionar > Classe.
Nomeie a nova classe PreOperationFormatPhoneCreateUpdate e selecione Adicionar.
Adicione as instruções using à nova classe da seguinte maneira:
using Microsoft.Xrm.Sdk; using System.Text.RegularExpressions;
Torne a classe pública e implemente interface IPlugin.
Implemente o membro de interface.
Sua classe agora deve ser semelhante à imagem a seguir.
Tarefa 2: Formatar um número de telefone
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));
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");
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;
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]", "");
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.
Clique com o botão direito do mouse no projeto e selecione Propriedades.
Selecione a guia Assinatura e Novo Arquivo de Chave.
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.
Feche a guia Propriedades.
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.
Inicie o aplicativo da Plug-in Registration Tool.
Selecione Criar Nova Conexão.
Selecione Microsoft 365, marque a caixa de seleção Mostrar Avançado, forneça suas credenciais e selecione Logon.
Selecione Registrar e, depois, Registrar Novo Assembly.
Selecione Procurar.
Navegue até a pasta Bin >Debug da biblioteca de classes criada, selecione D365PackageProject.dll e Abrir.
Selecione Registrar Plug-ins Selecionados.
Selecione OK.
Expanda o assembly recém-registrado.
Clique com o botão direito do mouse no plug-in e selecione Registrar Nova Etapa.
Selecione Create para Mensagem e contact para Entidade Principal.
Selecione PreOperation para Etapa de Execução do Pipeline de Eventos e, em seguida, selecione Registrar Nova Etapa.
Selecione Fechar.
Clique com o botão direito do mouse no plug-in e selecione Registrar Nova Etapa novamente.
Selecione Update para Mensagem, selecione contact para Entidade Principal e, em seguida, selecione a pesquisa Atributos.
Desmarque a caixa de seleção Selecionar Tudo, marque a caixa de seleção Telefone Comercial e selecione OK.
Selecione PreOperation para Etapa de Execução do Pipeline de Eventos e, em seguida, selecione Registrar Nova Etapa.
Tarefa 4: Testar o plug-in
Vá para seu Maker Portal e verifique se selecionou o ambiente correto.
Selecione Aplicativos e inicie o aplicativo Fundraiser.
Selecione Painel e abra um dos contatos.
Selecione + Novo.
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.
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
Inicie o Visual Studio.
Abra o projeto que você criou no Exercício 1.
Clique com o botão direito do mouse no projeto e selecione Adicionar > Classe.
No campo Nome, insira PostOperationFormatPhoneOnRetrieveMultiple para a classe e selecione Adicionar.
Adicione as instruções using à nova classe da seguinte maneira:
using Microsoft.Xrm.Sdk;
Torne a classe pública e implemente interface IPlugin.
Implemente o membro de interface. Sua classe agora deve ser semelhante à imagem a seguir.
Tarefa 2: Formatar número de telefone para retrieve
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));
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")) { }
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");
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;
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;
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 retrieve do método Execute deve ser parecida com a imagem a seguir.
Tarefa 3: Formatar número de telefone para retrieve multiple
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");
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"];
Itere por meio de cada entidade da coleção de entidades.
foreach (var entity in entityCollection.Entities) { }
Adicione o trecho a seguir dentro da condição
foreach
. Este trecho fará a mesma coisa que a condiçãoretrieve
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.
Recompile o projeto e verifique se a compilação foi bem-sucedida.
Tarefa 4: Atualizar o assembly do plug-in e registrar etapas
Inicie a Plug-in Registration Tool e selecione Criar Nova Conexão.
Selecione Microsoft 365, insira suas credenciais e clique em Logon.
Selecione o assembly registrado no Exercício 1 e, em seguida, selecione Atualizar.
Selecione Procurar.
Navegue até a pasta debug do seu projeto, selecione D365PackageProject.dll e, em seguida, selecione Abrir.
Selecione os plug-ins e, depois, Atualizar Plug-ins Selecionados.
Selecione OK.
Clique com o botão direito do mouse no novo plug-in e selecione Registrar Nova Etapa.
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.
Clique com o botão direito do mouse no plug-in e selecione Registrar Nova Etapa novamente.
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
Acesse o Maker Portal e verifique se você está no ambiente correto.
Selecione Aplicativos. Em seguida, selecione o aplicativo Fundraiser e selecione Editar. Você adicionará a tabela Contato ao aplicativo.
Selecione + Nova página.
Selecione Tabela do Dataverse e, depois, Avançar.
Selecionar Tabela existente. Em seguida, selecione a tabela Contato e Adicionar.
Selecione Reproduzir.
Selecione Salvar e continuar.
Selecione Reproduzir novamente.
Selecione Contatos.
Os registros existentes que não foram salvos com o novo formato não serão alterados. Selecione + Novo.
Forneça as informações a seguir e selecione Salvar. O registro deve ser salvo, e o plug-in deve aplicar o novo formato.
Selecione Contatos novamente. O registro que você criou deve ter o novo formato.
Selecione um dos contatos existentes para abri-lo.
Edite o Telefone Comercial da seguinte forma:
Selecione Salvar. O novo formato deve ser aplicado. Selecione Contatos mais uma vez.
O telefone editado deverá ter o novo formato.