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, besteht das empfohlene Design darin, 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 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 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. Dieser Rollback könnte Dataverse und einen externen Dienst in einem nicht synchronisierten Zustand belassen.
Synchron registrierte Plug-Ins können den Ausführungskontext der aktuellen Transaktion an Azure Service Bus senden.
Schreiben des Plug-In-Codes
Im folgenden Beispiel-Plug-In wurde Code hinzugefügt, um den Azure-Dienstanbieter abzurufen und durch einen Aufruf die Veröffentlichung des Ausführungskontexts im Service Bus zu initiieren Execute(EntityReference, IExecutionContext). 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
Beim Registrieren eines Azure-fähigen benutzerdefinierten Plug-Ins gelten einige Einschränkungen. Das Plug-In muss für die Ausführung im Sandkasten registriert werden. Durch die Sandbox-Registrierung wird das Plug-In auf das Aufrufen von IOrganizationService Methoden, Azure-Lösungsmethoden oder den Zugriff auf ein Netzwerk über einen Webclient beschränkt. Kein anderer externer Zugriff, wie der Zugriff auf ein lokales Dateisystem, ist zulässig.
Bei einem Plug-In, das für die Ausführung im asynchronen Modus registriert ist, ist die Reihenfolge der Plug-In-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 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-Integration
Arbeiten mit Microsoft Dataverse Daten in Ihrer Azure-Lösung
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).