Escribir un complemento con Azure personalizado

Escribir un complemento que funcione con Azure es similar a escribir cualquier otro complemento de Dataverse. Sin embargo, además de invocar cualquier método de servicio web deseado, el complemento debe incluir código para iniciar la publicación del contexto de ejecución de la transacción actual en Azure Service Bus.

Consideraciones de diseño del complemento

Para un complemento que se ejecuta de forma sincrónica, el diseño recomendado es que el complemento envíe un mensaje a Azure para recuperar información de una aplicación de escucha u otro servicio externo. El uso de un contrato REST o bidireccional en el punto de conexión de Azure Service Bus permite devolver una cadena de datos al complemento.

No se recomienda que un complemento sincrónico use Azure Service Bus para actualizar los datos con un servicio externo. Pueden surgir problemas si el servicio externo deja de estar disponible o si hay muchos datos que actualizar. Los complementos sincrónicos deben ejecutarse rápidamente y no retrasar a todos los usuarios conectados de una organización mientras se realiza una operación larga. Además, si se produce una retrotracción de la operación actual de base que invocó al complemento, los cambios en los datos realizados por el complemento se desharán. Esta reversión podría dejar Dataverse y un servicio externo en un estado no sincronizado.

Es posible que los complementos registrados sincrónicos publiquen el contexto de ejecución de la transacción actual en Azure Service Bus.

Escribir el código del complemento

En el complemento de ejemplo siguiente, se ha agregado código para obtener el proveedor de servicios de Azure e iniciar la publicación del contexto de ejecución en Service Bus llamando a Execute(EntityReference, IExecutionContext). Se ha agregado código de seguimiento para facilitar la depuración de complementos porque el complemento se debe ejecutar en el espacio asilado.

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;
            }
        }
    }
}

En el código de complemento, puede actualizar los datos grabables en contexto antes de iniciar la publicación. Por ejemplo, puede agregar un par clave-valor a las variables compartidas en el contexto.

Registro de complementos

Hay algunas restricciones al registrar un complemento personalizado compatible con Azure. El complemento debe registrarse para ejecutarse en el espacio aislado. El registro del espacio aislado limita el complemento para llamar a los métodos de IOrganizationService, los métodos de soluciones de Azure para acceder a una red mediante un cliente web. No se permite ningún otro acceso externo, como el acceso a un sistema de archivos local.

Para que un complemento registrado se ejecute en modo asincrónico, no se garantiza el orden de ejecución del complemento en comparación con otros complementos asincrónicos. Además, los complementos asincrónicos siempre se ejecutan después de la operación principal de Dataverse.

Gestión de una publicación de bus de servicio con errores

El comportamiento esperado de una publicación de bus de servicio con errores depende de si complemento se ha registrado para su ejecución sincrónica o asincrónica. Para complementos asincrónicos, el trabajo del sistema que publica realmente el contexto de la ejecución en el bus de servicio reintentará la publicación. Para un complemento sincronizado registrado, se devuelve una excepción. Más información sobre administración y notificación de errores en tiempo de ejecución

Para que un complemento registrado se ejecute de forma asincrónica, el RemoteExecutionContext contenido en el cuerpo del mensaje que se envía a través de Service Bus incluye una OperationId propiedad y una OperationCreatedOn propiedad. Estas propiedades contienen los mismos datos que las columnas AsyncOperationId y CreatedOn del registro de Trabajo del Sistema relacionado (AsyncOperation). Estas propiedades adicionales facilitan la secuenciación y la detección de duplicados si se debe intentar de nuevo la publicación en Azure Service Bus.

Consulte también

Integración de Azure
Uso de datos de Microsoft Dataverse en la solución de Azure
Ejemplo: Complemento personalizado habilitado para Azure
Escribir un complemento
Canalización de ejecución de eventos
Registro e implementación de complementos