Microsoft Dynamics CRM - Plugins
Um plug-in é uma lógica de negócios personalizada que se integra ao Microsoft Dynamics CRM para modificar ou estender o comportamento padrão da plataforma. Os plug-ins atuam como manipuladores de eventos e são registrados para execução em um evento específico no CRM. Os plug-ins são escritos em C # ou VB e podem ser executados no modo síncrono ou assíncrono.
Alguns cenários onde você escreveria um plugin são -
Você deseja executar alguma lógica de negócios, como atualizar certos campos de um registro ou atualizar registros relacionados, etc., ao criar ou atualizar um registro CRM.
Você deseja chamar um serviço da Web externo em determinados eventos, como salvar ou atualizar um registro.
Você deseja calcular dinamicamente os valores do campo quando qualquer registro é aberto.
Você deseja automatizar processos como o envio de e-mails para seus clientes em determinados eventos no CRM.
Estrutura do Evento
A Estrutura de Processamento de Eventos no CRM processa as solicitações de plug-in síncrono e assíncrono, passando-o para o pipeline de execução do evento. Sempre que um evento aciona uma lógica de plug-in, uma mensagem é enviada ao CRM Organization Web Service, onde pode ser lida ou modificada por outros plug-ins ou por qualquer operação central da plataforma.
Estágios do Plugin Pipeline
Todo o pipeline do plug-in é dividido em vários estágios nos quais você pode registrar sua lógica de negócios personalizada. O estágio do pipeline especificado indica em qual estágio do ciclo de execução do plug-in o código do plug-in é executado. De todos os estágios de pipeline especificados na tabela a seguir, você pode registrar seus plug-ins personalizados apenas em pré e pós-eventos. Você não pode registrar plug-ins em Platform Core Main Operations.
| Evento | Nome artístico | Descrição |
|---|---|---|
| Pré-Evento | Pré-validação | Estágio no pipeline para plug-ins que devem ser executados antes da operação principal do sistema. Plug-ins registrados neste estágio podem ser executados fora da transação do banco de dados. |
| Pré-Evento | Pré-operação | Estágio no pipeline para plug-ins que devem ser executados antes da operação do sistema principal. Plugins registrados nesta etapa são executados dentro da transação do banco de dados. |
| Operação principal da plataforma | MainOperation | Intransação, a operação principal do sistema, como criar, atualizar, excluir e assim por diante. Nenhum plug-in personalizado pode ser registrado neste estágio. Apenas para uso interno. |
| Pós-Evento | Pós operação | Estágio no pipeline para plug-ins que devem ser executados após a operação principal. Os plug-ins registrados neste estágio são executados dentro da transação do banco de dados. |
Sempre que o aplicativo CRM invoca um evento (como salvar ou atualizar um registro), a seguinte sequência de ações ocorre:
O evento aciona uma chamada de serviço da Web e a execução é passada pelos estágios do pipeline de eventos (pré-evento, operações principais da plataforma, pós-evento).
As informações são empacotadas internamente como uma mensagem OrganizationRequest e, finalmente, enviadas aos métodos de serviço da Web de CRM interno e às operações principais da plataforma.
A mensagem OrganizationRequest é recebida primeiro pelos plug-ins pré-evento, que podem modificar as informações antes de passá-las para as operações principais da plataforma. Após as operações principais da plataforma, a mensagem é empacotada como OrganizationResponse e passada para os plug-ins pós-operação. Os plug-ins de pós-operação podem, opcionalmente, modificar essas informações antes de passá-las para o plug-in assíncrono.
Os plug-ins recebem essas informações na forma de um objeto de contexto que é passado para o método Execute, após o qual o processamento posterior acontece.
Após a conclusão de todo o processamento do plugin, a execução é passada de volta para o aplicativo que disparou o evento.
Mensagens de Plugin
As mensagens são os eventos nos quais o plugin (ou lógica de negócios) está registrado. Por exemplo, você pode registrar um plugin na entidade Criar mensagem de contato. Isso acionaria a lógica de negócios sempre que um novo registro de contato fosse criado.
Para entidades personalizadas, a seguir estão as mensagens com suporte com base no fato de a entidade ser de propriedade do usuário ou da organização.
| Nome da Mensagem | Tipo de propriedade |
|---|---|
| Atribuir | Apenas entidades de propriedade do usuário |
| Crio | Entidades de propriedade do usuário e da organização |
| Excluir | Entidades de propriedade do usuário e da organização |
| Garantir acesso | Apenas entidades de propriedade do usuário |
| ModifyAccess | Apenas entidades de propriedade do usuário |
| Recuperar | Entidades de propriedade do usuário e da organização |
| RetrieveMultiple | Entidades de propriedade do usuário e da organização |
| RetrievePrincipalAccess | Apenas entidades de propriedade do usuário |
| RetrieveSharedPrincipalsAndAccess | Apenas entidades de propriedade do usuário |
| RevokeAccess | Apenas entidades de propriedade do usuário |
| SetState | Entidades de propriedade do usuário e da organização |
| SetStateDynamicEntity | Entidades de propriedade do usuário e da organização |
| Atualizar | Entidades de propriedade do usuário e da organização |
Para entidades prontas para uso padrão, há mais de 100 mensagens com suporte. Algumas dessas mensagens são aplicáveis para todas as entidades, enquanto algumas delas são específicas para certas entidades. Você pode encontrar a lista completa de mensagens suportadas em um arquivo excel dentro do SDK:SDK\Message-entity support for plug-ins.xlsx
Plugin de escrita
Nesta seção, aprenderemos o básico para escrever um plugin. Estaremos criando um plugin de amostra que cria uma atividade Tarefa para acompanhar o cliente sempre que um novo cliente é adicionado ao sistema, ou seja, sempre que um novo Contactrecord é criado no CRM.
Primeiro de tudo, você precisaria incluir as referências a Microsoft.Xrm.Sdknamespace. O CRM SDK contém todos os assemblies SDK necessários. Supondo que você já tenha baixado e instalado o SDK no Capítulo 2, abra o Visual Studio. Crie um novo projeto do tipo Biblioteca de classes. Você pode nomear o projeto como SamplePlugins e clicar em OK.
Adicione a referência de Microsoft.Xrm.Sdkmontagem ao seu projeto. A assembleia está presente emSDK/Bin.
Agora, crie uma classe chamada PostCreateContact.cs e estender a aula de IPlugin. Até agora, seu código será parecido com o seguinte.
Você também precisará adicionar referência a System.Runtime.Serialization. Depois de adicionar as referências necessárias, copie o código a seguir dentro doPostCreateContact classe.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Xrm.Sdk;
namespace SamplePlugins {
public class PostCreateContact:IPlugin {
/// A plug-in that creates a follow-up task activity when a new account is created.
/// Register this plug-in on the Create message, account entity,
/// and asynchronous mode.
public void Execute(IServiceProviderserviceProvider) {
// 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"]isEntity) {
// Obtain the target entity from the input parameters.
Entity entity = (Entity)context.InputParameters["Target"];
try {
// 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;
followup["scheduledend"] = DateTime.Now.AddDays(2);
followup["category"] = context.PrimaryEntityName;
// Refer to the contact in the task activity.
if(context.OutputParameters.Contains("id")) {
Guid regardingobjectid = new Guid(context.OutputParameter
s["id"].ToString());
string regardingobjectidType = "contact";
followup["regardingobjectid"] =
new EntityReference(rega rdingobjectidType,regardingobjectid);
}
// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory =
(IOrganizationSer viceFactory)serviceProvider.GetService
(typeof(IOrganizationServiceFactory));
IOrganizationService service =
serviceFactory.CreateOrganizationService(context.UserId);
// Create the followup activity
service.Create(followup);
} catch(Exception ex) {
throw new InvalidPluginExecutionException(ex.Message);
}
}
}
}
}A seguir está uma explicação passo a passo do que este código faz -
Step 1- Implementa o método Execute tomando o objeto IServiceProvider como seu parâmetro. O provedor de serviços contém referências a muitos objetos úteis que você usará no plugin.
Step 2 - Obtém o objeto IPluginExecutionContext usando o método GetService de IServiceProvider.
Step 3- Obtém o objeto da entidade de destino da coleção InputParameters do objeto de contexto. Este objeto de classe Entity se refere ao registro da entidade Contact no qual nosso plugin seria registrado.
Step 4- Em seguida, ele cria um objeto da entidade Tarefa e define o assunto, a descrição, as datas, a categoria e o objeto relacionado. O aboutobjectid indica para qual registro de contato este registro de atividade está sendo criado. Você pode ver que o código obtém o id do registro de contato pai usando context.OutputParameters e o associa ao registro de entidade Task que você criou.
Step 5 - Cria o objeto de IOrganizationServiceFactory usando o objeto IServiceProvider.
Step 6 - Cria o objeto de IOrganizationService usando o objeto IOrganizationServiceFactory.
Step 7- Finalmente, usando o método Create deste objeto de serviço. Ele cria a atividade de acompanhamento que é salva no CRM.
Assinando o Conjunto de Plug-ins
Esta seção é aplicável apenas se você estiver registrando o assembly do plugin pela primeira vez. Você precisa entrar no assembly com uma chave para poder implantar o plugin. Clique com o botão direito na solução e clique em Propriedades.
Selecione a guia Assinatura das opções à esquerda e marque a opção 'Assinar a montagem'. Em seguida, selecione Novo em Escolha uma opção de arquivo de chave de nome forte.
Digite o nome do arquivo de chave como sampleplugins (pode ser qualquer outro nome que você desejar). Desmarque a opção Proteger meu arquivo de chave com uma senha e clique em OK. Clique em Salvar.
Finalmente, construa a solução. Clique com o botão direito → Construir. Construir a solução irá gerar o assembly DLL, que usaremos no próximo capítulo para registrar este plugin.
Tratamento de exceções no plug-in
Na maioria das vezes, a lógica do plug-in precisará lidar com exceções de tempo de execução. Para plug-ins síncronos, você pode retornar umInvalidPluginExecutionExceptionexceção, que mostrará uma caixa de diálogo de erro ao usuário. A caixa de diálogo de erro conterá a mensagem de erro personalizada que você passa para o objeto Message do objeto de exceção.
Se você olhar nosso código, estamos lançando a exceção InvalidPluginExecutionException em nosso bloco catch.
throw new InvalidPluginExecutionException(ex.Message);Conclusão
Os plug-ins são definitivamente cruciais para qualquer implementação de CRM customizada. Neste capítulo, nos concentramos em compreender o modelo de estrutura de evento, estágios de pipeline, mensagens e escrever um plug-in de amostra. No próximo capítulo, vamos registrar esse plugin no CRM e vê-lo funcionando de ponta a ponta.