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 todos los métodos de servicio web que desee, el complemento debe incluir código para iniciar la publicación del contexto de la ejecución de la transacción actual en Azure Service Bus.

Consideraciones de diseño de complementos

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 bidireccional o REST en el extremo final de Azure Service Bus permite que se devuelva una cadena de datos al pluggin.

No se recomienda que un complemento sincrónico utilice Azure Service Bus para actualizar datos con un servicio externo. Pueden surgir problemas si el servicio externo no está disponible o si hay muchos datos para actualizar. Los complementos sincrónicos deben ejecutarse rápido y no mantener a todos los usuarios que han iniciado sesión en una organización mientras se realiza una operación muy 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 a Dataverse y a 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.

Escritura del código de complementos

En el siguiente complemento de muestra, se agregó código para obtener el proveedor de servicios de Azure e iniciar la publicación del contexto de ejecución en Service Bus mediante una llamada 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.

Nota

El serviceEndpointId que se ha pasado al constructor en este código es el único que obtiene de la creación de un extremo de servicio como el que se describe en Tutorial: Configurar Azure (SAS) para integración con Dataverse

Puede consultar los extremos de servicio disponibles para su entorno mediante una solicitud GET a una API web con su explorador con una consulta como esta: [organization Uri]/api/data/v9.0/serviceendpoints?$select=name,description,serviceendpointid.

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 de clave/valor a las variables compartidas en contexto.

Registro de complementos

Existen algunas restricciones al registrar un complemento personalizado compatible con Azure. El complemento se debe registrar para ejecutarse en el espacio asilado. El registro de sandbox limita el complemento a llamar a métodos, métodos de solución de Azure o acceder a una red mediante un cliente web. IOrganizationService No se permite ningún otro acceso externo, como el acceso a un sistema de archivos local.

Para un complemento registrado para ejecutarse 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. 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 registrado sincrónico, se devuelve una excepción. Más información Administración y notificación de errores en tiempo de ejecución

Importante

Solo para complementos registrados asincrónicos, cuando se reintenta realizar el trabajo asincrónico que publica en el Azure Service Bus después de un error de publicación, se vuelve a ejecutar la lógica completa de complementos. Por este motivo, no puede agregar ninguna otra lógica al complemento personalizado basado en Azure, aparte de modificar el contexto y realizar publicaciones en el bus de servicio.

Para un complemento registrado para ejecutarse asincrónicamente, el RemoteExecutionContext contenido en el cuerpo del mensaje que se enviará sobre el bus de servicio incluye una propiedad de OperationId y una propiedad de OperationCreatedOn. Estas propiedades contienen los mismos datos que las columnas AsyncOperationId y CreatedOn del registro relacionado del trabajo del sistema (AsyncOperation). Estas propiedades adicionales facilitan la secuenciación y la detección de duplicados si la publicación de Azure Service Bus debe ser reintentada.

Consulte también

Integración de Azure
Trabaje con datos en su solución de Azure Microsoft Dataverse
Ejemplo: complemento personalizado con Azure
Escribir un complemento
Canalización de ejecución del evento
Registrar e implementar complementos

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).