Ereignisframework

Die Möglichkeit, das Standardverhalten von Microsoft Dataverse zu erweitern, hängt davon ab, wann Ereignisse auf dem Server auftreten. Das Ereignisframework bietet die Möglichkeit, benutzerdefinierten Code zu registrieren, der als Reaktion auf bestimmte Ereignisse ausgeführt werden soll.

Alle Funktionen zum Erweitern des Standardverhaltens der Plattform hängen vom Ereignisframework ab. Wenn Sie einen Workflow so konfigurieren, dass er auf ein Ereignis mit dem Workflow-Designer reagiert, ohne Code zu schreiben, wird dieses Ereignis vom Ereignisframework bereitgestellt.

Als Entwickler verwenden Sie das Plug-In-Registrierungstool, um Plug-Ins , Azure-Integrationen, Virtuelle Tabellendatenanbieter und Webhooks zu konfigurieren, um auf Ereignisse zu reagieren, die vom Ereignisframework bereitgestellt werden. Wenn Ereignisse auftreten und eine Erweiterung registriert wird, um darauf zu reagieren, werden kontextbezogene Informationen zu den daten, die an dem Vorgang beteiligt sind, an die Erweiterung übergeben. Je nachdem, wie die Registrierung für das Ereignis konfiguriert ist, kann die Erweiterung die darin übergebenen Daten ändern, einen automatisierten Prozess initiieren, der sofort angewendet wird, oder definieren, dass eine Aktion zu einer Warteschlange hinzugefügt wird, die später ausgeführt werden soll.

Um das Ereignisframework für Ihre benutzerdefinierten Erweiterungen zu nutzen, müssen Sie Folgendes verstehen:

• Welche Ereignisse verfügbar sind
• Wie das Ereignis verarbeitet wird
• Welche Art von Daten für Ihre benutzerdefinierte Erweiterung verfügbar ist, wenn das Ereignis auftritt
• Welche Zeit- und Ressourcenbeschränkungen gelten
• Wie man die Leistung überwacht

Folgende Ereignisse sind verfügbar

Wie unter "Verwenden von Nachrichten mit dem SDK für .NET" beschrieben, basieren Datenvorgänge in der Dataverse-Plattform auf Nachrichten, und jede Nachricht hat einen Namen. Es gibt Create, Retrieve, RetrieveMultiple, Updateund DeleteAssociateDisassociate Nachrichten, die die grundlegenden Datenvorgänge abdecken, die mit Tabellen geschehen. Es gibt auch spezielle Nachrichten für komplexere Vorgänge, und benutzerdefinierte Aktionen fügen neue Nachrichten hinzu.

Wenn Sie das Plug-In-Registrierungstool verwenden, um eine Erweiterung einer bestimmten Nachricht zuzuordnen, registrieren Sie sie als Schritt. Der folgende Screenshot ist das Dialogfeld " Neuer Schritt registrieren ", das beim Registrieren eines Plug-Ins verwendet wird.

In einem Schritt werden die Informationen darüber bereitgestellt, auf welche Nachricht die Erweiterungen reagieren sollen, sowie eine Reihe anderer Konfigurationsoptionen. Verwenden Sie das Feld "Nachricht ", um die Nachricht auszuwählen, auf die Ihre Erweiterung antwortet.

Im Allgemeinen können Sie davon ausgehen, dass Sie eine Nachricht für die meisten *Request-Klassen in den Microsoft.Crm.Sdk.Messages oder Microsoft.Xrm.Sdk.Messages Namespaces finden, aber Sie werden auch Nachrichten für alle benutzerdefinierten Aktionen finden, die in der Organisation erstellt wurden. Alle Vorgänge, die Tabellendefinitionen umfassen, sind nicht verfügbar.

Daten zu Nachrichten werden in den Tabellen SdkMessage und SdkMessageFilter gespeichert. Das Plug-In-Registrierungstool filtert diese Informationen so, dass nur gültige Nachrichten angezeigt werden.

Um zu überprüfen, ob eine Nachrichten- und Tabellenkombination die Ausführung von Plug-Ins mithilfe einer Datenbankabfrage unterstützt, können Sie die folgende Web-API-Abfrage verwenden:

[Organization URI]/api/data/v9.1/sdkmessages?$select=name
&$filter=isprivate eq false 
and (name ne 'SetStateDynamicEntity' 
and name ne 'RemoveRelated' 
and name ne 'SetRelated' and 
name ne 'Execute') 
and sdkmessageid_sdkmessagefilter/any(s:s/iscustomprocessingstepallowed eq true 
and s/isvisible eq true)
&$expand=sdkmessageid_sdkmessagefilter($select=primaryobjecttypecode;
$filter=iscustomprocessingstepallowed eq true and isvisible eq true)
&$orderby=name

Tipp

Sie können diese Daten mithilfe dieser Abfrage und der anweisungen in diesem Blogbeitrag in ein Excel-Arbeitsblatt exportieren: Suchen von Nachrichten und Tabellen, die für Plug-Ins berechtigt sind, mithilfe der Dataverse

Sie können auch das folgende FetchXML verwenden, um diese Informationen abzurufen. Der FetchXML Builder ist ein nützliches Tool zum Ausführen dieser Art von Abfrage.

<fetch>
  <entity name='sdkmessage' >
    <attribute name='name' />
    <link-entity name='sdkmessagefilter' alias='filter' to='sdkmessageid' from='sdkmessageid' link-type='inner' >
      <filter type='and' >
        <condition attribute='iscustomprocessingstepallowed' operator='eq' value='1' />
        <condition attribute='isvisible' operator='eq' value='1' />
      </filter>
      <attribute name='primaryobjecttypecode' />
    </link-entity>
    <filter>
      <condition attribute='isprivate' operator='eq' value='0' />
      <condition attribute='name' operator='not-in' >
        <value>SetStateDynamicEntity</value>
        <value>RemoveRelated</value>
        <value>SetRelated</value>
	      <value>Execute</value>
      </condition>
    </filter>
    <order attribute='name' />
  </entity>
</fetch>

Vorsicht

Die Execute Nachricht ist verfügbar, Sie sollten jedoch keine Erweiterungen dafür registrieren, da sie von jedem Vorgang aufgerufen wird.

Hinweis

Es gibt bestimmte Fälle, in denen Plug-Ins und Workflows, die für das Update-Ereignis registriert sind, zweimal aufgerufen werden können. Weitere Informationen: Verhalten von spezialisierten Updatevorgängen

Ereignisausführungspipeline

Wenn Sie einen Schritt mit dem Plug-In-Registrierungstool registrieren, müssen Sie auch die Ereignispipelinephase der Ausführung auswählen. Jede Nachricht wird in einer Reihe von vier Phasen verarbeitet, wie in der folgenden Tabelle beschrieben:

Name	Description
PreValidation	Beim Erstbetrieb tritt diese Phase vor dem Betrieb des Hauptsystems auf. Auf diese Weise kann Logik eingebunden werden, mit der sich der Vorgang vor der Datenbanktransaktion abbrechen lässt. Nachfolgende Vorgänge, die von Erweiterungen ausgelöst werden, die in anderen Phasen registriert sind, passieren diese Phase auch, werden aber in die Transaktion der aufrufenden Erweiterungen aufgenommen. Diese Phase tritt vor der Durchführung sämtlicher Sicherheitsprüfungen auf, um zu überprüfen, ob der aufrufende oder angemeldete Benutzer berechtigt ist, den gewünschten Vorgang durchzuführen.
PreOperation	Tritt vor Betrieb des Hauptsystems und während der Datenbanktransaktion auf. Wenn Sie die Werte einer in einer Nachricht enthaltenen Entität ändern möchten, tun Sie dies hier. Brechen Sie an dieser Stelle besser keinen Vorgang ab. Andernfalls wird die Transaktion rückabgewickelt, und es kommt zu erheblichen Leistungseinbußen.
Hauptoperation	Nur für die interne Verwendung mit Ausnahme von benutzerdefinierten API- und benutzerdefinierten Datenanbietern für virtuelle Tabellen. Weitere Informationen: Benutzerdefinierte APIs erstellen und verwenden Benutzerdefinierte Anbieter für virtuelle Tabellendaten
PostOperation	Tritt nach Betrieb des Hauptsystems und während der Datenbanktransaktion auf. Mit dieser Phase können Sie die Eigenschaften der Nachricht ändern, bevor sie an den Anrufer zurückgeht. Die Entitäten in einer Nachricht sollten nicht geändert werden, weil das ein neues Update-Ereignis auslöst. In der PostOperation-Phase können Sie Schritte zur Nutzung des asynchronen Ausführungsmodus aufzeichnen. Diese Schritte erfolgen mithilfe des asynchronen Dienstes außerhalb der Datenbanktransaktion. Sie müssen beim Registrieren Ihres Plug-Ins den asynchronen Modus verwenden, wenn das Plug-In für die Durchführung eines Aktualisierungsvorgangs konzipiert ist und in der Nachricht „Create” der Entität User (SystemUser) registriert ist. Weitere Informationen:Asynchroner Dienst.

Die Phase, die Sie auswählen sollten, hängt vom Zweck der Erweiterung ab. Sie müssen nicht alle Geschäftslogik innerhalb eines einzelnen Schritts anwenden. Sie können mehrere Schritte anwenden, damit Ihre Logik darüber, ob ein Vorgang fortgesetzt werden soll, in der PreValidation-Phase enthalten sein kann, und Ihre Logik zum Vornehmen von Änderungen an den Nachrichteneigenschaften kann in der PostOperation-Phase auftreten.

Von Bedeutung

Eine Ausnahme, die von Ihrem Code in einer synchronen Phase innerhalb der Datenbanktransaktion ausgelöst wird, führt dazu, dass die gesamte Transaktion zurückgesetzt wird. Achten Sie darauf, dass alle möglichen Ausnahmefälle von Ihrem Code behandelt werden. Wenn Sie den Vorgang abbrechen möchten, sollten Sie dies in der PreValidation-Phase erkennen und nur eine InvalidPluginExecutionException entsprechende Meldung auslösen, die beschreibt, warum der Vorgang abgebrochen wurde.

Für dieselbe Nachricht und Stufe können mehrere Erweiterungen registriert werden. Innerhalb der Schrittregistrierung bestimmt der Wert der Ausführungsreihenfolge die Reihenfolge, in der mehrere Erweiterungen für eine bestimmte Phase verarbeitet werden sollen.

Informationen zu registrierten Schritten werden in der SdkMessageProcessingStep-Tabelle gespeichert.

Asynchrone Plug-In-Schritte

Bei der Registrierung für die PostOperation-Phase haben Sie die Möglichkeit, den Schritt für die Ausführung im asynchronen Ausführungsmodus zu registrieren. Diese Plug-Ins werden nach Abschluss des Aufzeichnungsvorgangs ausgeführt.

Dies ist häufig erforderlich, wenn Sie mit Datensätzen arbeiten, die dem aktuellen Datensatz zugeordnet sind, aber in einem anderen Prozess erstellt wurden. Die UserSettings, die mit einem bestimmten SystemUser zusammenhängen, werden zum Beispiel erst erstellt, wenn die SystemUser-Zeile erstellt wird.

Weitere Informationen: Asynchroner Dienst

Ereigniskontext

Wenn ihre Erweiterung ein Plug-In ist, erhält sie einen Parameter, der die IPluginExecutionContext Schnittstelle implementiert. Diese Klasse enthält einige Informationen über das Stage Plug-In, für das das Plug-In registriert ist, sowie Informationen über das ParentContext, was Informationen zu jedem Vorgang innerhalb eines anderen Plug-Ins bereitstellt, das den aktuellen Vorgang ausgelöst hat.

Wenn es sich bei Ihrer Erweiterung um einen Azure Service-Bus-Endpunkt, ein Azure EventHub-Thema oder einen Webhook handelt, werden die Daten, die an den registrierten Endpunkt gepostet werden, in Form eines RemoteExecutionContext vorliegen, das sowohl IPluginExecutionContext als auch IExecutionContext implementiert.

Weitere Informationen zum Ausführungskontext finden Sie unter "Grundlegendes zum Ausführungskontext".