Gravar um plug-in 

Publicado: novembro de 2016

Aplicável a: Dynamics CRM 2015

Os plug-ins são classes personalizadas que implementam a interface de IPlugin. Você pode gravar um plug-in em qualquer idioma compatível com CLR .NET Framework 4.5.2 como Microsoft Visual C# e Microsoft Visual Basic .NET. Para poder compilar o código de plug-in, adicione as referências de assembly Microsoft.Xrm.Sdk.dll e Microsoft.Crm.Sdk.Proxy.dll ao seu projeto. Essas assemblies podem ser encontradas na pasta SDK\Bin do SDK.Baixe o pacote do SDK do Microsoft Dynamics CRM.

Neste tópico

Design do plug-in

Gravando um plug-in básico

Gravar um construtor de plug-in

Suporte à execução offline

Web Access para plug-in isolados (em modo seguro)

Usar tipos de associação precoce

Assemblies de Plug-in

Design do plug-in

O design de plug-in deve levar em consideração o recurso salvamento automático do aplicativo Web apresentado em Atualização do Microsoft Dynamics CRM 2015 e Microsoft Dynamics CRM Online 2015. O salvamento automático é habilitado por padrão, mas pode ser desabilitado em um nível da organização. Quando o salvamento automático está habilitado, não existe um botão Salvar. O aplicativo Web salvará os dados no formulário automaticamente 30 segundos após a última alteração não salva. Você pode aplicar scripts de formulário para desabilitar os comportamentos de salvamento automático em um nível de formulário. Dependendo de como você registrou seu plug-in, o salvamento automático poderá fazer com que seu plug-in seja chamado com mais frequência para alterações de campo individuais em vez de uma invocação de plug-in para todas as alterações. Você deve considerar que qualquer usuário pode salvar qualquer registro a qualquer momento, independentemente disso ser feito usando Ctrl+S, pressionando um botão Salvar ou automaticamente devido ao recurso de salvamento automático.

É uma prática recomendável registrar seu plug-in ou fluxo de trabalho em entidades e especificar os campos mais importantes. Evite registrar um plug-in ou fluxo de trabalho para alterações em todos os campos da entidade. Se você tiver um plug-in ou fluxo de trabalho existente que foi implementado antes da disponibilidade do recurso de salvamento automático, teste novamente esse código para verificar sua operação correta. Para obter mais informações, consulte TechNet: Gerenciar o salvamento automático.

Gravando um plug-in básico

O exemplo a seguir mostra alguns dos códigos comuns encontrados em um plug-in. Para este exemplo, o código omite toda a lógica de negócios personalizada que deveria executar a tarefa desejada do plug-in. Entretanto, o código mostra a classe de plug-in que implementa a interface de IPlugin e o método de Execute necessário.

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

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        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"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

            // Obtain the organization service reference 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 MyPlug-in.", ex);
            }

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

O parâmetro IServiceProvider do método de Execute é um contêiner de vários objetos úteis de serviço que podem ser acessados em um plug-in. O provedor de serviços contém referências da instância para o contexto de execução, IOrganizationServiceFactory, ITracingService e muito mais. O código de exemplo demonstra como obter referências para o contexto de execução, IOrganizationService e ITracingService no parâmetro do provedor de serviços. Para obter mais informações sobre o serviço de rastreamento, consulte Depurar um plug-in.

O contexto de execução contém uma grande variedade de informações sobre o evento que causou a execução do plug-in e os dados contidos na mensagem que atualmente está sendo processada pelo pipeline. Para obter mais informações sobre o contexto de dados, consulte Compreender o contexto de dados passado para um plug-in.

A plataforma fornece as URLs de serviço Web e as credenciais de rede corretas quando você obtém a referência de serviço Web da organização junto ao provedor de serviços. Instanciar seu próprio proxy de serviço Web não é suportado, pois isso cria problemas de deadlock e autenticação. Após estabelecer a referência de serviço da organização, você poderá usá-la para fazer ligações de método para o serviço Web da organização. Você pode recuperar ou alterar os dados corporativos em uma única organização do Microsoft Dynamics 365 emitindo uma ou mais solicitações de mensagem para o serviço Web. Para obter mais informações sobre solicitações de mensagem, consulte Usar mensagens (classes de solicitação e resposta) com o método Execute.

Um plug-in típico deve acessar as informações no contexto, executar as operações de negócios obrigatórias e manipular exceções. Para obter mais informações sobre as exceções de manipulação, consulte Lidar com exceção nos plug-ins. Um exemplo mais completo de plug-in está disponível no tópico Amostra: Criar um plug-in básico.

Gravar um construtor de plug-in

A plataforma de Microsoft Dynamics 365 suporta um construtor de plug-in opcional que aceita um ou dois parâmetros de cadeia de caracteres. Se você gravar um construtor como esse, poderá passar todas as cadeias de caracteres de informações para o plug-in no tempo de execução.

O exemplo a seguir mostra o formato do construtor. Neste exemplo, a classe de plug-in é chamada SamplePlugin.

public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)

O primeiro parâmetro de cadeia de caracteres do construtor contém informações públicas (não seguras). A segunda cadeia de caracteres contém informações não públicas (seguras). Nesta discussão, segura refere-se a um valor criptografado, enquanto insegura refere-se a um valor não criptografado. Ao usar Microsoft Dynamics CRM para Microsoft Office Outlook com Acesso Offline, a cadeia de caracteres segura não é transmitida para um plug-in executado enquanto Dynamics CRM para Outlook está offline.

As informações transmitidas para o construtor de plug-in nessas cadeias de caracteres são especificadas quando o plug-in é registrado com Microsoft Dynamics 365. Ao usar a ferramenta de registro de plug-in para registrar um plug-in, você pode inserir informações seguras e inseguras nos campos Configuração segura e Instalação não segura fornecidos no formulário Registrar nova etapa. Ao registrar um plug-in programaticamente usando o SDK do Microsoft Dynamics CRM, SdkMessageProcessingStep.Configuration contém o valor não seguro e SdkMessageProcessingStep.SecureConfigId refere-se a um registro SdkMessageProcessingStepSecureConfig que contém o valor seguro.

Suporte à execução offline

Você pode registrar plug-ins para execução no modo online, modo offline ou ambos. O modo offline é suportado apenas em Microsoft Dynamics CRM para Microsoft Office Outlook com Acesso Offline. Seu código de plug-in pode verificar se está sendo executado no modo offline verificando a propriedade IsExecutingOffline.

Ao criar um plug-in que será registrado para execução online e offline, lembre-se de que o plug-in pode ser executado duas vezes. A primeira vez ocorre quando Microsoft Dynamics CRM para Microsoft Office Outlook com Acesso Offline está offline. O plug-in é executado novamente quando Dynamics CRM para Outlook fica online e a sincronização entre Dynamics CRM para Outlook e o servidor de Microsoft Dynamics 365 ocorre. Você pode verificar a propriedade IsOfflinePlayback para determinar se o plug-in está sendo executado devido à sincronização.

Web Access para plug-in isolados (em modo seguro)

Se você pretende registrar seu plug-in na área restrita, ainda poderá acessar endereços Web no código de plug-in. Você pode usar qualquer classe de .NET Framework no código de plug-in que oferece acesso à Web dentro das restrições de acesso à Web descritas Isolamento, estatísticas e confianças de plug-in. Por exemplo, o código de plug-in a seguir baixa uma página da Web.

// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);

Segurança Observação

Para que os plug-ins em modo seguro possam acessar serviços Web externos, o servidor onde a função de serviço de processamento em área restrita está instalada deve ser exposto à Internet, e a conta na qual o serviço de área restrita é executado deve ter acesso à Internet. Apenas conexões de saída em portas 80 e 443 são necessárias. Acesso à conexão de entrada não é necessária. Use o painel de controle do Windows Firewall para habilitar as conexões de saída para o aplicativo Microsoft.Crm.Sandbox.WorkerProcess localizado no servidor na pasta %PROGRAMFILES%\Microsoft Dynamics CRM\Server\bin.

Usar tipos de associação precoce

Para usar os tipos de associação precoce Microsoft Dynamics 365 no código de plug-in basta incluir o arquivo de tipos gerado usando o programa CrmSvcUtil, no projeto de plug-in Microsoft Visual Studio.

A conversão de uma entidade de associação tardia para uma entidade de associação precoce é manipulada da seguinte maneira:

Account acct = entity.ToEntity<Account>();

Na linha de código anterior, a variável de acct é um tipo de associação precoce. Todos os valores de Entity atribuídos a IPluginExecutionContext devem ser tipos de associação tardia. Se um tipo de associação precoce é atribuído ao contexto, uma SerializationException ocorrerá. Para obter mais informações, consulte Compreender o contexto de dados passado para um plug-in. Certifique-se de não misturar seus tipos e use um tipo de associação precoce quando um tipo de associação tardia for chamado conforme exibido no código a seguir.

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

No exemplo acima, não armazene uma instância de associação precoce no contexto de plug-in onde uma instância de associação tardia deve existir. Isso serve para evitar que a plataforma converta entre tipos de associação precoce e tardia antes de chamar um plug-in e ao retornar do plug-in para a plataforma.

Assemblies de Plug-in

Pode haver um ou mais tipos de plug-in em uma assembly. Depois que a assembly de plug-in é registrada e implantada, os plug-ins podem executar sua operação desejada em resposta a um evento de tempo de execução de Microsoft Dynamics 365.

Segurança Observação
Em Microsoft Dynamics 365, as assemblies de plug-in devem ser legíveis por todos para funcionar corretamente. Portanto, é uma prática recomendável de segurança desenvolver o código de plug-in que não contém as informações de logon do sistema, informações confidenciais ou os segredos da empresa.

Cada assembly de plug-in deve ser conectada, usando a guia Assinar da folha de propriedades do projeto em Microsoft Visual Studio ou pela ferramenta de nome forte, antes de ser registrada e implantada em Microsoft Dynamics 365. Para obter mais informações sobre a ferramenta de nome forte, execute o programa sn.exe, sem os argumentos, em uma janela de Microsoft Visual Studio Prompt de comando.

Se a assembly contiver um plug-in que pode ser executado quando Dynamics CRM para Outlook está offline, haverá segurança adicional que a plataforma de Microsoft Dynamics 365 impõe nas assemblies. Para obter mais informações, consulte Passo a passo: Configurar a segurança do conjunto de um plug-in offline.

Confira Também

Desenvolvimento de plug-in
Compreender o contexto de dados passado para um plug-in
Redigir um plug-in com reconhecimento de Azure personalizado
Registrar e implantar plug-ins
Lidar com exceção nos plug-ins
Amostra: Criar um plug-in básico
Exemplo: Acesso da Web a partir de um plug-in de área restrita
Executar a ferramenta de geração de código
Blog: Usando plug-ins para modificar exibições

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais