Escrever um plug-in personalizado compatível com Azure

Escrever um plug-in que funcione com o Azure é semelhante a escrever qualquer outro plug-in do Dataverse. No entanto, além de invocar todos os métodos de serviço Web desejados, o plug-in deve incluir código para iniciar a postagem do contexto de execução da transação atual no Barramento de Serviço do Azure.

Considerações sobre o design do plug-in

Para um plug-in que é executado de forma síncrona, o design recomendado é que o plug-in envie uma mensagem para Azure para recuperar informações de um aplicativo ouvinte ou outro serviço externo. O uso de um contrato bidirecional ou REST no ponto de extremidade do Barramento de Serviço do Azure permite que uma cadeia de dados seja retornada ao plug-in.

Não é recomendável que um plug-in síncrono use o Barramento de Serviço do Azure para atualizar dados com um serviço externo. Problemas poderão surgir se o serviço externo ficar indisponível ou se houver muitos dados a serem atualizados. Plug-ins síncronos devem executar rapidamente e não atrasar todos os usuários conectados de uma organização durante a execução de uma operação demorada. Além disso, se ocorrer uma reversão da operação de núcleo atual que invocou o plug-in, todas as alterações de dados feitas pelo plug-in serão desfeitas. Essa reversão pode deixar o Dataverse e um serviço externo em um estado não sincronizado.

É possível que plug-ins registrados síncronos postem o contexto de execução da transação atual no Barramento de Serviço do Azure.

Gravar o código do plug-in

No plug-in de exemplo a seguir, o código foi adicionado para obter o provedor de serviços Azure e iniciar a postagem do contexto de execução no Barramento de Serviço chamando Execute(EntityReference, IExecutionContext). O código de rastreamento foi adicionado para facilitar a depuração do plug-in porque o plug-in deve ser executado na área restrita.

using System;
using System.Diagnostics;
using System.Threading;
using System.Runtime.Serialization;

using System.ServiceModel;
using System.ServiceModel.Channels;
using System.ServiceModel.Description;

using Microsoft.Xrm.Sdk;

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A custom plug-in that can post the execution context of the current message to the Windows
    /// Azure Service Bus. The plug-in also demonstrates tracing which assist with
    /// debugging for plug-ins that are registered in the sandbox.
    /// </summary>
    /// <remarks>This sample requires that a service endpoint be created first, and its ID passed
    /// to the plug-in constructor through the unsecure configuration parameter when the plug-in
    /// step is registered.</remarks>
    public sealed class SandboxPlugin : IPlugin
    {
        private Guid serviceEndpointId; 

        /// <summary>
        /// Constructor.
        /// </summary>
        public SandboxPlugin(string config)
        {
            if (String.IsNullOrEmpty(config) || !Guid.TryParse(config, out serviceEndpointId))
            {
                throw new InvalidPluginExecutionException("Service endpoint ID should be passed as config.");
            }
        }

        public void Execute(IServiceProvider serviceProvider)
        {
            // Retrieve the execution context.
            IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            // Extract the tracing service.
            ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
            if (tracingService == null)
                throw new InvalidPluginExecutionException("Failed to retrieve the tracing service.");

            IServiceEndpointNotificationService cloudService = (IServiceEndpointNotificationService)serviceProvider.GetService(typeof(IServiceEndpointNotificationService));
            if (cloudService == null)
                throw new InvalidPluginExecutionException("Failed to retrieve the service bus service.");

            try
            {
                tracingService.Trace("Posting the execution context.");
                string response = cloudService.Execute(new EntityReference("serviceendpoint", serviceEndpointId), context);
                if (!String.IsNullOrEmpty(response))
                {
                    tracingService.Trace("Response = {0}", response);
                }
                tracingService.Trace("Done.");
            }
            catch (Exception e)
            {
                tracingService.Trace("Exception: {0}", e.ToString());
                throw;
            }
        }
    }
}

No código do plug-in, você pode atualizar os dados graváveis no contexto antes de iniciar a postagem. Por exemplo, você pode adicionar um par chave/valor às variáveis compartilhadas no contexto.

Registro do plug-in

Há algumas restrições ao registrar um plug-in personalizado compatível com o Azure. O plug-in deve ser registrado para ser executado no sandbox. O registro no sandbox limita o plug-in à chamada de métodos IOrganizationService, métodos de solução do Azure ou ao acesso a uma rede usando um cliente web.

Para um plug-in registrado para ser executado no modo assíncrono, a ordem de execução do plug-in em comparação com outros plug-ins assíncronos não é garantida. Além disso, plug-ins assíncronos sempre são executados após a operação de núcleo do Dataverse.

Tratar uma falha de postagem no Barramento de Serviço

O comportamento esperado de um post no Barramento de Serviço com falha depende de se o plug-in foi registrado para execução síncrona ou assíncrona. Para plug-ins assíncronos, o trabalho do sistema que realmente posta o contexto de execução no barramento de serviço tentará novamente a postagem. Para um plug-in síncrono registrado, uma exceção é retornada. Mais informações gerenciamento e notificação de erros em tempo de execução

Para um plug-in registrado para ser executado de forma assíncrona, o RemoteExecutionContext contido no corpo da mensagem enviada pela Barramento de Serviço inclui uma propriedade OperationId e uma propriedade OperationCreatedOn. Essas propriedades contêm os mesmos dados que as colunas AsyncOperationId e CreatedOn do registro relacionado do Trabalho do Sistema (AsyncOperation). Essas propriedades adicionais facilitam o sequenciamento e a detecção de duplicidade se o envio ao Barramento de Serviço do Azure precisar ser repetido.

Consulte também

Integração do Azure
Trabalhe com dados do Microsoft Dataverse na sua solução do Azure
Exemplo: Plug-in personalizado com reconhecimento do Azure
Desenvolver um plug-in
Pipeline de execução de eventos
Registrar e implantar plug-ins