Schreiben eines benutzerdefinierten Azure-Plug-Ins

Das Schreiben eines Plug-Ins, das mit Azure funktioniert ähnelt dem Schreiben eines beliebigen anderen Dataverse-Plug-Ins. Das Plug-in muss jedoch zusätzlich zum Aufrufen der gewünschten Webservice-Methoden Code enthalten, um das Posten des Ausführungskontexts der aktuellen Transaktion an den Azure Service Bus zu initiieren.

Plug-In-Entwurfsüberlegungen

Für ein Plug-In, das synchron ausgeführt wird, sollte der Entwurf so aussehen, dass das Plug-In eine Nachricht an Azure sendet, um Informationen von einer Listener-Anwendung oder einem anderen externen Dienst abzurufen. Die Verwendung eines bidirektionalen oder REST-Vertrags auf dem Azure Service Bus-Endpunkt ermöglicht die Rückgabe einer Datenzeichenfolge an das Plug-In.

Es wird nicht empfohlen, dass ein synchrones Plug-In den Azure Service Bus verwendet, um Daten mit einem externen Dienst zu aktualisieren. 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 nicht alle angemeldeten Benutzer einer Organisation aufhalten, während ein langatmiger Vorgang ausgeführt wird. Wenn zudem ein Rollback des aktuellen Kernvorgangs, der das Plug-In aufgerufen hat, auftritt, werden alle vorgenommenen Datenänderungen rückgängig gemacht. Dies könnte dazu führen, dass Dynamics 365 und ein externer Dienst in einem unsynchronisierten Zustand sind.

Beachten Sie, dass es für synchron registrierte Plug-Ins möglich ist, den Ausführungskontext der aktuellen Transaktion an den Azure Service Bus zu senden.

Schreiben des Plug-In-Codes

Im folgenden Beispiel wurde Plug-In-Code hinzugefügt, um den Azure-Dienstanbieter zu erhalten und das Posten des Ausführungskontexts an den Service Bus durch den Aufruf von Execute(EntityReference, IExecutionContext) zu initiieren. Ablaufverfolgungscode wurde hinzugefügt, um das Debuggen von Plug-Ins zu erleichtern, da das Plug-In im Sandkasten ausgeführt werden muss.

Hinweis

Die serviceEndpointId, die an den Konstruktor in diesem Code übergeben wurde, ist diejenige, die Sie beim Erstellen eines Dienstendpunkts erhalten, wie beschrieben in: Exemplarische Vorgehensweise: Azure (SAS) für Integration in Dataverse konfigurieren

Sie können verfügbare Dienstendpunkte für Ihre Umgebung mit einer GET-Anforderung an die Web-API abfragen. Verwenden Sie dazu Ihren Browser mit einer Abfrage wie der Folgenden: [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;
            }
        }
    }
}

In Ihrem Plug-In-Code können Sie die schreibbaren Daten im Kontext aktualisieren, bevor Sie die Veröffentlichung initiieren. Sie können beispielsweise ein Schlüssel-/Wertpaar im Kontext den freigegebenen Variablen hinzufügen.

Plug-In-Registrierung

Es gibt ein paar Einschränkungen, wenn Sie ein angepasstes Azure-Plug-in registrieren. Das Plug-In muss für die Ausführung im Sandkasten registriert werden. Darum ist das Plug-In auf den Aufruf von IOrganizationService-Methoden, von Azure-Lösungsmethoden oder den Zugriff auf ein Netzwerk mithilfe eines Webclient beschränkt. Kein anderer externer Zugriff, wie der Zugriff auf ein lokales Dateisystem, ist zulässig.

Für ein Plug-In, das für die Ausführung im asynchronen Modus registriert ist, bedeutet das auch, dass die Reihenfolge der Plug-In-Ausführung verglichen mit anderen asynchronen Plug-Ins nicht garantiert ist. Darüber hinaus werden asynchrone Plug-Ins immer nach dem Dynamics 365-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 synchrones registriertes Plug-In wird eine Ausnahme zurückgegeben. Weitere Informationen: Verwaltung und Meldung von Laufzeitfehlern

Wichtig

Nur für asynchrone registrierte Plug-Ins, wenn der asynchrone Auftrag, der an Azure Service Bus bereitstellt, nach einem Bereitstellungsfehler wiederholt wird, wird die gesamte Plug-In-Logik erneut ausgeführt. Fügen Sie daher dem angepassten Azure-fähigen Plug-In keine weitere Logik hinzu, außer der Änderung des Kontexts und dem Posting an den Service Bus.

Für ein Plug-in, das zur asynchronen Ausführung registriert ist, enthält die RemoteExecutionContext im Körper der Nachricht, die über den Service Bus gesendet wird, eine OperationId-Eigenschaft und eine OperationCreatedOn-Eigenschaft. Diese Eigenschaften enthalten die gleichen Daten wie die Spalten AsyncOperationId und CreatedOn des zugehörigen Datensatzes für den Systemauftrag (AsyncOperation). Diese zusätzlichen Eigenschaften unterstützen die Sequenzierung und die Duplikaterkennung, wenn das Bereitstellen an den Azure Service Bus wiederholt werden muss.

Siehe auch

Azure-Erweiterungen für Dynamics 365
Senden Sie Dynamics 365-Daten über den Microsoft Azure-Servicebus
Beispiel: Benutzerdefiniertes Azure-fähiges Plug-In
Ein Plug-In schreiben
Ereignisausführungspipeline
Registrieren und Bereitstellen von Plug-Ins

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).