Compartilhar via

Gravar um plug-in 

  • Artigo

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.

Importante

Para melhor desempenho, Microsoft Dynamics 365 armazena em cache instâncias de plug-in. O método Execute do plug-in deve ser gravado para ser sem monitoração de estado porque o construtor não é chamado para cada invocação do plug-in. Além disso, vários threads do sistema podem executar o plug-in ao mesmo tempo. Todas as informações de estado por invocação são armazenadas no contexto, portanto não se deve usar variáveis globais ou tentar armazenar os dados nas variáveis de membro para uso na próxima invocação de plug-in, a menos que esse parâmetro tenha sido obtido a partir do parâmetro de configuração para o construtor. As alterações feitas em um registro de plug-ins reinicializarão o plug-in.

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);
System_CAPS_security 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.

System_CAPS_security 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