Verstehen des Ausführungskontextes
Die Ereignis-Ausführungs-Pipeline übergibt registrierten Plug-Ins eine Fülle von Daten über den aktuellen Vorgang, der verarbeitet wird, und die Umgebung, in der Ihr angepasster Code ausgeführt wird. Die folgenden Abschnitte beschreiben die Daten, die an Ihr Plug-In oder Ihre angepasste Workflow-Aktivität übergeben werden.
Für Plug-Ins
Bei Plug-Ins können Sie auf diese Daten in Ihrem Code zugreifen, indem Sie eine Variable festlegen, die die Schnittstelle IPluginExecutionContext implementiert:
// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
Diese IPluginExecutionContext liefert einige Informationen über die Stage, für die das Plug-In registriert ist, sowie Informationen über die ParentContext.
Weitere Informationen: ParentContext
Für benutzerdefinierte Workflowaktivitäten
Mit benutzerdefinierten Workflowaktivitäten können Sie auf diese Daten in Ihrem Code zugreifen, indem Sie eine Variable setzen, die die Schnittstelle IWorkflowContext implementiert:
// Obtain the execution context using the GetExtension method.
protected override void Execute(CodeActivityContext context)
{
IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...
Diese IWorkflowContext liefert einige Informationen über den Workflow, innerhalb dessen die angepasste Workflow-Aktivität ausgeführt wird.
| Eigenschaft | Beschreibung |
|---|---|
| ParentContext | Ruft den übergeordneten Kontext ab. Siehe Übergeordneter Kontext |
| StageName | Ruft die Phaseninformationen der Prozessinstanz ab. |
| WorkflowCategory | Ruft die Prozesskategorieinformationen der Prozessinstanz ab: Ist es ein Workflow oder ein Dialog (veraltet). |
| WorkflowMode | Gibt an, wie der Workflow ausgeführt werden soll. 0 = asynchron, 1 = synchron |
Übergeordneter Kontext
Der ParentContext bietet Informationen über alle Vorgänge, die das Plug-In oder die benutzerdefinierte Workflowaktivität auslösen.
Mit Ausnahme von speziell dokumentierten Fällen sollten Sie vermeiden, eine Abhängigkeit auf Werte zu übertragen die Sie in ParentContext finden, um Ihre Geschäftslogik anzuwenden. Die entsprechende Reihenfolge, in der Vorgänge auftreten, ist nicht garantiert und kann sich im Laufe der Zeit ändern.
Wenn Sie sich für eine Abhängigkeit von den Werten in ParentContext entscheiden, sollten Sie Maßnahmen ergreifen, um sicherzustellen, dass Ihr Code bei potenziellen Änderungen unverändert bleibt. Sie sollten die Logik regelmäßig testen, um sicherzustellen, dass die Bedingungen, von denen Sie abhängig sind, im Laufe der Zeit auch wirksam bleiben.
ExecutionContext
Die übrigen verfügbaren Informationen werden jedoch von der IExecutionContext-Schnittstelle bereitgestellt, die die IPluginExecutionContext- und IWorkflowContext-Klassen implementieren.
Für Plug-ins bieten alle Eigenschaften dieser Ausführungskontextklasse nützliche Informationen, auf die Sie in Ihrem Code möglicherweise zugreifen müssen.
Hinweis
Für angepasste Workflow-Aktivitäten werden diese Eigenschaften im Allgemeinen nicht verwendet.
Zwei der wichtigsten sind die InputParameters- undOutputParameters-Eigenschaften.
Andere häufig verwendete Eigenschaften sind SharedVariables, PreEntityImages und PostEntityImages.
Tipp
Eine gute Möglichkeit, die Daten, die an den Ausführungskontext übergeben werden, zu visualisieren, ist die Installation der Plug-in Profiler-Lösung, die als Teil des Plug-in Registration Tools verfügbar ist. Der Profiler erfasst die Kontextinformationen sowie Informationen, die die erneute Wiedergabe des Ereignisses lokal ermöglichen, sodass Sie debuggen können. Innerhalb des Plug-in Registration Tools können Sie ein XML-Dokument mit allen Daten des Ereignisses, das den Workflow ausgelöst hat, herunterladen. Weitere Informationen: Plug-in-Profil-Daten anzeigen
ParameterCollections
All Eigenschaften des Ausführungskontexts sind schreibgeschützt. Aber die InputParameters, OutputParameters und SharedVariables sind ParameterCollection-Werte. Sie können die Werte der Elemente in diesen Sammlungen manipulieren, um das Verhalten des Vorgangs zu ändern, je nach Phase in der Ereignisausführungspipeline, für die Ihr Plug-In registriert ist.
Die ParameterCollection-Werte sind als KeyValuePair-Strukturen definiert. Um auf eine Eigenschaft zuzugreifen, müssen Sie den Namen der Eigenschaft wissen, die von der Nachricht zur Verfügung gestellt wird. Um beispielsweise auf die Entity-Eigenschaft zuzugreifen, die als Teil der CreateRequest übergeben wird, müssen Sie wissen, dass der Name dieser Eigenschaft Target ist. Dann können Sie auf diesen Wert folgendermaßen mithilfe von Code zugreifen:
var entity = (Entity)context.InputParameters["Target"];
Verwenden Sie die Dokumentation Microsoft.Xrm.Sdk.Messages und Microsoft.Crm.Sdk.Messages, um die Namen der Nachrichten zu erfahren, die in den SDK-Assemblys definiert sind. Für benutzerdefinierte Aktionen finden Sie weitere Informationen unter den Namen der Parameter, die im System definiert sind.
InputParameters
Die InputParameters stellen den Wert der OrganizationRequest.Parameters- Eigenschaft dar, die den von den Webdiensten eingehenden Vorgang darstellt.
Wie unter Nachrichten mit dem SDK für .NET verwenden beschrieben, sind alle Vorgänge, die sich im System ereignen, letztlich Instanzen der OrganizationRequest-Klasse, die von IOrganizationService.Execute verarbeitet wird Methode.
Wie im Ereignisframework beschrieben, durchlaufen Vorgänge eine Reihe von Phasen, und Sie können Ihr Plug-In in Phasen registrieren, die auftreten, bevor die Daten in die Datenbank geschrieben werden. Innerhalb der PreValidation- und PreOperation-Phasen können Sie die Werte der InputParameters lesen und ändern, sodass Sie das erwartete Ergebnis des Datenenvorgangs steuern können.
Wenn Sie feststellen, dass die Werte in der InputParameters-Sammlung eine Bedingung darstellen, die Sie nicht zulassen können, können Sie eine InvalidPluginExecutionException auslösen (vorzugsweise in der Phase PreValidation). Dadurch wird der Vorgang abgebrochen und dem Benutzer mit einem synchronsen Plug-In ein Fehler angezeigt, oder es wird der Fehler protokolliert, wenn das Plug-In asynchron ist. Weitere Informationen: Abbrechen eines Vorgangs
OutputParameters
Die OutputParameters stellen den Wert der OrganizationResponse.Results- Eigenschaft dar, die den Rückgabewert des Vorgangs darstellt. Jede der von OrganizationResponse abgeleiteten Nachrichtenantwortklassen enthält spezifische Eigenschaften. Um auf diese Eigenschaften zuzugreifen, müssen Sie den Schlüsselwert verwenden, der normalerweise dem Namen der Eigenschaften in der Antwortklasse entspricht. Dies ist jedoch nicht immer der Fall. Die folgende Tabelle listet die Eigenschaften der Nachrichtenantwortklasse auf, deren Schlüssel sich vom Namen der Eigenschaften unterscheiden.
Die OutputParameters werden nicht vor der Datenbanktransaktion aufgefüllt. Somit sind sie erst für Plug-Ins verfügbar, die in der PostOperation-Phase registriert werden. Wenn Sie die Werte ändern möchten, die von dem Vorgang zurückgegeben wurden, können Sie sie in den OutputParameters ändern.
Freigegebene Variablen
Die SharedVariables-Eigenschaft lässt das Einschließen von Daten zu, die von der API oder einem Plug-In an einen Schritt übergeben werden können, der später in der Ausführungspipeline auftritt. Da dies ein ParameterCollection-Wert ist, können Plug-Ins Eigenschaften hinzufügen, lesen oder ändern, um Daten für nachfolgende Schritten freizugeben.
Das folgende Beispiel zeigt, wie ein PrimaryContact-Wert von einem Plug-In übergeben werden kann, das für einen PreOperation-Schritt an einen PostOperation-Schritt registriert ist.
public class PreOperation : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));
// Create or retrieve some data that will be needed by the post event
// plug-in. You could run a query, create an entity, or perform a calculation.
//In this sample, the data to be passed to the post plug-in is
// represented by a GUID.
Guid contact = new Guid("{74882D5C-381A-4863-A5B9-B8604615C2D0}");
// Pass the data to the post event plug-in in an execution context shared
// variable named PrimaryContact.
context.SharedVariables.Add("PrimaryContact", (Object)contact.ToString());
}
}
public class PostOperation : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));
// Obtain the contact from the execution context shared variables.
if (context.SharedVariables.Contains("PrimaryContact"))
{
Guid contact =
new Guid((string)context.SharedVariables["PrimaryContact"]);
// Do something with the contact.
}
}
}
Wichtig
Jede Art von Daten, die der Collection der gemeinsamen Variablen hinzugefügt werden, muss serialisierbar sein, da der Server sonst nicht weiß, wie die Daten serialisiert werden sollen, und die Ausführung des Plugins schlägt fehl.
Hinweis
Bei einem Plug-In, das für die Phasen PreOperation oder PostOperation registriert ist, um auf die freigegebenen Variablen über ein Plug-In zuzugreifen, das für die Phase PreValidation registriert ist, das bei Erstellen, Altualisieren, Löschen oder durch eine RetrieveExchangeRateRequest ausgeführt wird, müssen Sie auf die Sammlung ParentContext.SharedVariables zugreifen. In allen anderen Fällen enthält IPluginExecutionContext.SharedVariables die Sammlung.
Eine gemeinsam genutzte Variable aus der API übergeben
Wenn Sie beim Aufrufen einer API eine gemeinsam genutzte Variable einführen müssen, verwenden Sie das Stichwort tag entweder von der Web-API oder vom SDK für .NET aus, um einen Zeichenfolgenwert zu übergeben.
Auf diesen Wert kann in der Sammlung gemeinsam genutzter Variablen mit dem Stichwort tag zugegriffen werden. Einmal eingestellt, kann dieser Wert nicht mehr geändert werden, er ist unveränderlich.
Weitere Informationen: Eine gemeinsam genutzte Variable zum Plug-In-Ausführungskontext hinzufügen
Entitätsbilder
Wenn Sie einen Schritt für ein Plug-in registrieren, der eine Tabelle als einen der Parameter enthält, haben Sie die Möglichkeit, über die Eigenschaften PreEntityImages und/oder PostEntityImages festzulegen, dass eine Kopie der Tabellendaten als Snapshot oder Bild enthalten sein soll.
Diese Daten bieten einen Vergleichspunkt für die Tabellendaten, während sie durch die Ereignis-Pipeline fließen. Die Verwendung dieser Bilder bietet eine viel bessere Leistung als das Einfügen von Code in ein Plug-In, um eine Tabelle abzurufen, nur um die Attributwerte zu vergleichen.
Wenn Sie ein Entitätsbild definieren, geben Sie einen Entitätsaliaswert an, die Sie verwenden können, um auf das gewünschte Bild zuzugreifen. Wenn Sie z. B. ein Pre-Entity-Bild mit dem Alias 'a' definieren, können Sie den folgenden Code verwenden, um auf den Wert des Attributs name zuzugreifen.
var oldAccountName = (string)context.PreEntityImages["a"]["name"];
Weitere Informationen:
Siehe auch
Ereignisframework
Schreiben eines 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).