Schreiben eines benutzerdefinierten Azure-Plug-Ins

Das Schreiben eines Plug-Ins, das mit Azure funktioniert, ähnelt dem Schreiben anderer Dataverse-Plug-Ins. Zusätzlich zum Aufrufen von gewünschten Webdienstmethoden muss das Plug-In jedoch Code enthalten, um die Veröffentlichung des Ausführungskontexts der aktuellen Transaktion an den Azure Service Bus zu initiieren.

Überlegungen zum Plug-In-Entwurf

Bei einem Plug-In, das synchron ausgeführt wird, dient das empfohlene Design dem Plug-In, um eine Nachricht an Azure zu senden, um Informationen aus einer Listeneranwendung oder einem anderen externen Dienst abzurufen. Die Verwendung eines bidirektionalen oder REST-Vertrags auf dem Azure Service Bus-Endpunkt ermöglicht das Zurückgeben einer Datenzeichenfolge an das Plug-In.

Es wird nicht empfohlen, dass ein synchrones Plug-In den Azure Service Bus zum Aktualisieren von Daten mit einem externen Dienst verwendet. Probleme können auftreten, wenn der externe Dienst nicht verfügbar ist oder wenn viele Daten aktualisiert werden müssen. Synchrone Plug-ins sollten schnell ausgeführt werden und die angemeldeten Benutzer einer Organisation nicht aufhalten, während ein längerer Prozess durchgeführt wird. Wenn außerdem ein Rollback des aktuellen Kernvorgangs, der das Plug-In aufgerufen hat, erfolgt, werden alle vom Plug-In vorgenommenen Datenänderungen rückgängig gemacht. Dieses Rollback könnte Dataverse und einen externen Dienst in einem nicht synchronisierten Zustand belassen.

Es ist möglich, den Ausführungskontext der aktuellen Transaktion über synchron registrierte Plug-ins an den Azure Service Bus zu übermitteln.

Schreiben des Plug-In-Codes

Im folgenden Beispiel-Plug-In wurde Code hinzugefügt, um den Azure-Dienstanbieter abzurufen und das Bereitstellen des Ausführungskontexts in den ServiceBus durch Aufrufen Execute(EntityReference, IExecutionContext)zu initiieren. Der Trace-Code wurde hinzugefügt, um das Debugging des Plug-ins zu erleichtern, da das Plug-in in der Sandbox ausgeführt werden muss.

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

Im Plug-In-Code können Sie die schreibbaren Daten im Kontext aktualisieren, bevor Sie den Beitrag initiieren. Im Kontext können Sie beispielsweise den freigegebenen Variablen ein sogenanntes Schlüssel-Wert-Paar hinzufügen.

Plug-In-Registrierung

Es gibt einige Einschränkungen, wenn Sie ein benutzerdefiniertes Azure-fähiges Plug-In registrieren. Das Plug-In muss für die Ausführung im Sandkasten registriert werden. Die Sandkastenregistrierung beschränkt das Plug-In darauf, Methoden IOrganizationService aufzurufen, Azure-Lösungsmethoden zu verwenden oder mithilfe eines Webclients auf ein Netzwerk zuzugreifen. Kein anderer externer Zugriff, z. B. Zugriff auf ein lokales Dateisystem, ist zulässig.

Für ein Plug-In, das zur Ausführung im asynchronen Modus registriert ist, ist die Reihenfolge der Ausführung im Vergleich zu anderen asynchronen Plug-Ins nicht garantiert. Darüber hinaus werden asynchrone Plug-Ins immer nach dem Dataverse-Kernvorgang ausgeführt.

Behandeln eines fehlgeschlagenen Service Bus-Posts

Das erwartete Verhalten bei einem fehlgeschlagenen Service Bus-Post hängt davon ab, ob das Plug-in für synchrone oder asynchrone Ausführung registriert wurde. Für asynchrone Plug-Ins wiederholt der Systemauftrag, der den Ausführungskontext tatsächlich an den Servicebus sendet, den Sendevorgang. Für ein synchron registriertes Plug-In wird eine Ausnahme zurückgegeben. Weitere Informationen zur Verwaltung und Benachrichtigung über Laufzeitfehler

Für ein Plug-In, das registriert ist, um asynchron ausgeführt zu werden, enthält die im Textkörper der über den Service Bus gesendeten Nachricht enthaltene RemoteExecutionContext-Eigenschaft sowohl eine OperationId-Eigenschaft als auch eine OperationCreatedOn-Eigenschaft. Diese Eigenschaften enthalten dieselben Daten wie die AsyncOperationId- und CreatedOn-Spalten des zugehörigen Systemauftragsdatensatzes (AsyncOperation). Diese zusätzlichen Eigenschaften erleichtern die Sequenzierung und Duplikaterkennung, wenn die Azure Service Bus Nachricht erneut gesendet werden muss.

Siehe auch

Azure-Integration
Arbeiten mit Microsoft Dataverse-Daten in Ihrer Azure-Lösung
Beispiel: Benutzerdefiniertes Azure-fähiges Plug-In
Schreiben eines Plug-Ins
Pipeline für die Ereignisausführung
Registrieren und Bereitstellen von Plug-Ins