Nachvollziehen des Datenkontexts, der an einem Plug-In übergeben wird
Veröffentlicht: Januar 2017
Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Wenn ein Plug-In als Antwort auf ein Ausführungspipelineereignis ausgeführt wird, für das es registriert ist, wird die Execute-Methode des Plug-Ins aufgerufen. Diese Methode übergibt ein IServiceProvider-Objekt als Parameter, der eine Anzahl nützlicher Objekte enthält. In den folgenden Abschnitten werden einige der Informationen beschrieben, die an ein Plug-In übergeben werden, wenn es ausgeführt wird.
In diesem Thema
Auf den Ausführungskontext des Plug-Ins zugreifen
Auf den Organisationsservice zugreifen
Auf den Benachrichtigungsservice zugreifen
Ein- und Ausgabeparameter
Vorherige und spätere Entitätsbilder
Auf den Ausführungskontext des Plug-Ins zugreifen
IPluginExecutionContext enthält Informationen, die die Laufzeitumgebung, die das Plug-In ausführt, beschreiben, Informationen die sich auf die Ausführungspipeline und Entitätsgeschäftsinformationen beziehen. Der Kontext ist im System.IServiceProvider-Parameter enthalten, der zur Laufzeit durch die Execute-Methode an ein Plug-In übergeben wird.
// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
Wenn ein Systemereignis ausgelöst wird, für das ein Plug-In registriert ist, erstellt das System den Kontext und füllt diesen auf. Es übergibt ihn durch die zuvor erwähnten Klassen und Methoden an ein Plug-In. Der Ausführungskontext wird an jedes registrierte Plug-In in der Pipeline übergeben, wenn diese ausgeführt werden. Jedes Plug-In in der Ausführungspipeline ist dazu in der Lage, beschreibbare Eigenschaften im Kontext zu ändern. Beispielsweise, sofern ein Plug-In für ein vorheriges Event registriert ist und ein anderes Plug-In für ein späteres Event registriert ist, kann das spätere Event-Plug-In einen Kontext empfangen, der durch das vorherige Event-Plug-In geändert wurde. Dieselbe Situation gilt für Plug-Ins, die innerhalb derselben Phase registriert werden.
Alle Eigenschaften in IPluginExecutionContext sind schreibgeschützt. Allerdings kann Ihr Plug-In die Inhalte der Eigenschaften festlegen, die Sammlungen sind. Weitere Informationen über die Verhinderung von Endlosschleifen finden Sie unter Depth.
Auf den Organisationsservice zugreifen
Wenn Sie auf den Microsoft Dynamics 365-Organisationsservice zugreifen, ist es erforderlich, dass Plug-In-Code eine Instanz des Services durch die ServiceProvider.GetService-Methode erstellt.
// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);
Die Plattform stellt die korrekten Webdienst-URLs und Netzwerkanmeldeinformationen für Sie bereit, wenn Sie diese Methode verwenden. Das Instanziieren Ihres eigenen Webdienstproxys wird nicht unterstützt, da es zu Deadlock- und Authentifizierungsproblemen führt.
Auf den Benachrichtigungsservice zugreifen
Synchrone, registrierte Plug-Ins können den Ausführungskontext an den Microsoft Azure Service Bus übermitteln. Das Dienstanbieterobjekt, das an den Plug-In übergeben wird, enthält einen Verweis auf IServiceEndpointNotificationService. Durch eben diesen Benachrichtigungsservice können synchrone Plug-Ins Brokermessages an Microsoft Azure Service Bus senden. Weitere Informationen zu Microsoft Azure finden Sie unter Azure-Integration in Microsoft Dynamics 365. Weitere Informationen über das Schreiben eines Plug-Ins, das an den Microsoft Azure Service Bus übermitteln kann, finden Sie unter Schreiben eines benutzerdefinierten Azure-Plug-Ins.
Ein- und Ausgabeparameter
Die Eigenschaft InputParameters enthält die Daten, die sich in der Anforderungsmessage befinden, die gerade durch die Ereignisausführungspipeline verarbeitet wird. Ihr Plug-In-Code kann auf diese Daten zugreifen. Die Eigenschaft ist vom Typ ParameterCollection, wo die Schlüssel zum Zugriff auf die Anforderungsdaten die Namen der tatsächlichen öffentlichen Eigenschaften in der Anforderung sind. Als Beispiel betrachten Sie CreateRequest. Eine Eigenschaft von CreateRequest wird Target genannt, die vom Typ Entity ist. Dies ist die Entität, auf der derzeit durch die Plattform Vorgänge ausgeführt werden. Um auf die Daten der Entität zuzugreifen, würden Sie den Namen "Ziel" als Schlüssel in der Eingabeparametersammlung verwenden. Darüber hinaus müssen Sie die zurückgegebene Instanz umwandeln.
// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&
context.InputParameters["Target"] is Entity)
{
// Obtain the target entity from the input parameters.
Entity entity = (Entity)context.InputParameters["Target"];
Beachten Sie, dass alle Anforderungen eine Target-Eigenschaft enthalten, die vom Typ Entity ist, deshalb müssen Sie jede Anforderung oder Antwort beachten. Beispielsweise hat DeleteRequest eine Target-Eigenschaft, ihr Typ ist allerdings EntityReference. Das vorangehende Codebeispiel würde folgendermaßen geändert.
// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") && context.InputParameters["Target"] is EntityReference)
{
// Obtain the target entity from the input parameters.
EntityReference entity = (EntityReference)context.InputParameters["Target"];
}
Wenn Sie für die Daten der Entität Zugriff haben, können Sie sie lesen und ändern. Alle Datenänderungen am Kontext, die mit Plug-Ins durchgeführt wurden, die in der Phase 10 oder 20 der Pipeline registriert sind, werden im Kontext an den Kernvorgang in Phase 30 übergeben.
Wichtig
Nicht alle Felder in einem Entitätsdatensatz, die einem Plug-In über den Kontext übergeben werden, können geändert werden. Sie sollten die Metadateneigenschaft des IsValidForUpdate-Felds überprüfen, um sicherzustellen, dass sie nicht auf false festgelegt ist. Wenn Sie versuchen, den Wert eines Felds zu ändern, das nicht aktualisiert werden kann, wird eine Ausnahme ausgelöst.
In ähnlicher Weise enthält die Eigenschaft OutputParameters die Daten, die sich in der Antwortmessage befinden, beispielsweise CreateResponse, die aktuell durch diese Ereignisausführungspipeline weitergegeben wird. Jedoch nur synchrone Post-Event-Plug-Ins und asynchrone, registrierte Plug-Ins haben OutputParameters aufgefüllt als Antwort auf das Ergebnis des Kernplattformvorgangs. Die Eigenschaft ist vom Typ ParameterCollection, wo die Schlüssel zum Zugriff auf die Antwortdaten die Namen der tatsächlichen öffentlichen Eigenschaften in der Antwort sind.
Vorherige und spätere Entitätsbilder
PreEntityImages und PostEntityImages enthalten Momentaufnahmen der primären Attribute der Entität vor (pre) und nach (post) dem Hauptplattformvorgang.Microsoft Dynamics 365 füllt die Vor-Entitäts- und Nach-Entitäts-Abbilder anhand der Sicherheitsrechte der angenommenen Systembenutzeridentität auf. Nur Entitätsattribute, für die ein Wert festgelegt ist oder die NULL entsprechen, stehen in den vorherigen und späteren Entitätsbildern zur Verfügung. Sie können angeben, dass die Plattform diese PreEntityImages- und PostEntityImages-Eigenschaften auffüllt, wenn Sie das Plug-In registrieren. Der Entitätsaliaswert, den Sie während der Plug-In-Registrierung angeben, wird als Schlüssel zur Bildsammlung in Ihrem Plug-In-Code verwendet.
Es gibt manche Ereignisse, bei denen keine Bilder verfügbar sind. Beispielsweise werden nur synchronen Post-Event-Plug-Ins und asynchronen, registrierten Plug-Ins PostEntityImages aufgefüllt. Der Erstellungsvorgang unterstützt kein vorheriges Bild und ein Löschvorgang unterstützt kein späteres Bild. Zudem unterstützt nur eine kleine Teilmenge von Messages vorherige und spätere Bilder, wie in der folgenden Tabelle gezeigt wird.
Messageanforderung |
Eigenschaft |
Beschreibung |
|---|---|---|
Ziel |
Die zugewiesene Entität. |
|
Ziel |
Die erstellte Entität. |
|
Ziel |
Die gelöschte Entität. |
|
EmailId |
Die zugestellte E-Mail-ID. |
|
EmailId |
Die zugestellte E-Mail-ID. |
|
Ziel |
Die Workflowentität. |
|
Ziel |
Die übergeordnete Entität, in die die Daten aus der untergeordneten Entität zusammengeführt werden. |
|
SubordinateId |
Die untergeordnete Entität, die in die übergeordnete Entität zusammengeführt wird. |
|
EmailId |
Die gesendete Entitäts-ID. |
|
EntityMoniker |
Die Entität, für die der Status festgelegt ist. |
|
Ziel |
Die aktualisierte Entität. |
Das Registrieren für vorherige oder spätere Bilder, um auf Entitätsattributwerte zuzugreifen, führt zu verbesserter Leistung des Plug-Ins im Vergleich dazu, wenn Entitätsattribute im Plug-In-Code durch RetrieveRequest- oder RetrieveMultipleRequest-Anforderungen bezogen werden.
.jpeg "System_CAPS_security") Sicherheit Hinweis |
|---|
Ein Vor-Abbild, das im Ausführungskontext an eine Plug-In- oder benutzerdefinierte Workflowaktivität übergeben wurde, kann Daten enthalten, für die der angemeldete Benutzer unter Umständen keine Rechte für den Zugriff besitzt.Microsoft Dynamics 365-Administratoren und andere Benutzer mit hohen Berechtigungen können Plug-Ins, die im "System"-Benutzerkonto ausgeführt werden können, oder Plug-In-Code registrieren, der Aufrufe als "System"-Benutzer im Namen des angemeldeten Benutzers vornehmen kann. Wenn dies passiert, können angemeldete Benutzer auf Daten zugreifen, auf die ihr Zugriff auf Feldebene keinen Zugriff ermöglichen würde.Weitere Informationen:Identitätswechsel in Plug-Ins |
Siehe auch
Plug-In-Entwicklung
Behandlung von Ausnahmen in Plug-ins
Ereignisausführungspipeline
Verwendung von Nachrichten (Anforderungs- und Antwortklassen) mit der Ausführensmethode
Verwenden des Organisationsdienstes, um Daten oder Metadaten zu lesen und zu schreiben
Registrieren und Bereitstellen von Plug-Ins
Microsoft Dynamics 365
© 2017 Microsoft. Alle Rechte vorbehalten. Copyright