Erstellen Ihrer eigenen Aktionen

  • Artikel

Sie können die Funktionen von Dynamics 365 Customer Engagement (on-premises) erweitern, indem Sie benutzerdefinierte Meldungen erstellen, die als Aktionen bekannt sind. Diese Aktionen verfügen über zugewiesene Antwort-/Anforderungsklassen, und eine Web API-Aktion wird generiert. Aktionen werden in der Regel verwendet, um neue domänenspezifische Funktionen zum Organisationswebdienst hinzuzufügen oder um mehrere Webdienstmeldungsanforderungen einer Organisation zu einer einzelnen Anforderung zu kombinieren. Beispielsweise können Sie in einem Supportcallcenter die Meldungen , Erstellen, Zuweisen und Setstate zur einer einzelnen neuen „Eskalieren“-Meldung kombinieren.

Die Geschäftslogik einer Aktion wird mithilfe eines Workflows implementiert. Wenn Sie eine Aktion erstellen, wird der zugeordnete Echtzeitworkflow automatisch registriert, um in Phase 30 (Kernvorgang) der Ausführungspipeline ausgeführt zu werden. Weitere Informationen zu Echtzeitworkflows finden Sie unter Workflowtypen.

Während Aktionen sowohl in Dynamics 365 for Customer Engagement unterstützt werden, wird das Erstellen einer Aktion im Code (unter Verwendung von XAML) nur von lokalen und IFD-Bereitstellungen unterstützt. Onlinekunden müssen Aktionen interaktiv in der Webanwendung erstellen.

 

Informationen zu Aktionsdefinitionen

Eine Aktion wird mithilfe eines Workflow-Entitätsdatensatzes definiert, der ähnlich wie ein Echtzeitworkflow ist. Einige wichtige Punkte dazu, was eine Aktion ist und wie sie funktioniert, sind in der folgenden Liste enthalten:

  • Kann einer einzelnen Entität oder global (keiner bestimmten Entität) zugeordnet werden.

  • Wird in der Kernvorgangsphase 30 der Ereignisausführungspipeline ausgeführt.

  • Unterstützt den Aufruf von Plug-Ins, die in den vorgelagerten und nachgelagerten Vorgangsphasen der Ereignisausführungspipeline registriert werden.

  • Kann die Plug-Ins in den vorgelagerten und nachgelagerten Vorgangsphasen nur registrieren, wenn der Aktionsstatus aktiviert ist.

  • Ist durch die Internet API oder organization.svc und organization.svc/web-Endpunkte verfügbar.

  • Kann über eine JavaScript-Webressource ausgeführt werden. Weitere Informationen: Ausführen einer Aktion mit einer JavaScript Web-Ressource

  • Wird immer im Sicherheitskontext des aufrufenden Benutzers ausgeführt.

  • Datensatz kann nicht gelöscht werden, während Plug-In-Schritte auf der Aktion registriert sind.

  • Kann optional, durch eine Konfigurationseinstellung, an der aktuellen Datenbanktransaktion teilnehmen.

  • Unterstützt einen Umfang nicht, in dem die Ausführung auf einen Benutzer, eine Unternehmenseinheit oder eine Organisation begrenzt ist. Aktionen werden immer im Organisationsumfang ausgeführt.

  • Unterstützt Ein- und Ausgabeargumente.

  • Unterstützt die Überwachung von Datenänderungen.

  • Wird nicht mit Offline-Clients unterstützt.

  • Kann mit einem Webdienstmethodenaufruf aufgerufen werden.

  • Kann direkt in einem Workflow aufgerufen werden.

Erforderliche Berechtigungen

Ein Sicherheitsrecht mit der Bezeichnung Echtzeitprozesse aktivieren (prvActivateSynchronousWorkflow) ist erforderlich, um einen Echtzeitworkflow der Aktion zu aktivieren, damit sie ausgeführt werden kann. Dies wird zusätzlich zu beliebigen Rechten benötigt, um einen Workflow erstellen.

Erstellen einer Aktion mithilfe von Code

In der Regel wird eine Aktion von Anpasser mithilfe des interaktiven Workflowdesigners der Webanwendung implementiert. Entwickler können jedoch mithilfe von SDK-Aufrufen Aktionen implementieren und bei Bedarf auf einem lokalen oder IFD-Server bereitstellen.

Die Workflowentitätsattribute, die für eine Aktion verwendet werden, sind in der folgenden Tabelle beschrieben. Beispielcode für einen Echtzeitworkflow finden Sie im Thema Erstellen eines Echtzeitworkflow im Code.

Workflowattribut Beschreibung
Category Festgelegt auf WorkflowCategory.CustomOperation.
SyncWorkflowLogOnError Wenn true, werden Fehler in ProcessSession-Datensätzen protokolliert. Im Gegensatz zu asynchronen Workflows wird die Ausführung von Echtzeitworkflows nicht in System Job-Datensätzen protokolliert.
Mode Nicht verwendet.
IsTransacted Festgelegt auf true, wenn die Aktion an der Datenbanktransaktion teilnehmen soll; andernfalls false. Der Standardwert ist true.
UniqueName Ein eindeutiger Name für die Aktion. Der Name besteht aus einem Herausgeberpräfix + "_" + dem eindeutigen Namen.
Xaml Legen Sie den XAML-Code fest, der den Echtzeitworkflow der Aktion definiert. Es gibt keine Möglichkeit, um auf einen anderen Echtzeitworkflow zu verweisen.

Hinzufügen von Ein- und Ausgabeargumenten

Aktionen unterstützen Ein- und Ausgabeargumente, die dem Workflow mithilfe des Typs DynamicActivityProperty hinzugefügt werden können. Wenn Sie diese Argumente zum Workflow einer Aktion hinzufügen, werden sie zu Eigenschaften in der Nachrichtenanforderung und den Antwortklassen, die dieser Aktion zugeordnet sind. Beispielsweise zeigt das folgende Beispiel C#- und XAML-Code für zwei Eingabeargumente und ein Ausgabeargument.

DynamicActivityProperty inputProperty1 = new DynamicActivityProperty     { Name = "Subject", Type = typeof(InArgument<string>) };  
DynamicActivityProperty inputProperty2 = new DynamicActivityProperty     { Name = "EntityCollection", Type = typeof(InArgument<EntityCollection>) };  
DynamicActivityProperty outputProperty1 = new DynamicActivityProperty     { Name = "Output", Type = typeof(OutArgument<string>) };  
  
inputProperty1.Attributes.Add(new ArgumentRequiredAttribute(true));  
inputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The subject"));  
inputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));  
  
inputProperty2.Attributes.Add(new ArgumentRequiredAttribute(false));  
inputProperty2.Attributes.Add(new ArgumentDescriptionAttribute("The entity collection"));  
inputProperty2.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));  
  
outputProperty1.Attributes.Add(new ArgumentRequiredAttribute(false));  
outputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The output"));  
outputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Output));  

<x:Property Name="Subject"  
            Type="InArgument(x:String)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="True" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The subject " />  
  <mxsw:ArgumentDirectionAttribute Value="Input" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>  
<x:Property Name="EntityCollection"  
            Type="InArgument(mxs:EntityCollection)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="False" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The entity collection" />  
  <mxsw:ArgumentDirectionAttribute Value="Input" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>  
<x:Property Name="Output"  
            Type="OutArgument(x:String)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="False" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The output" />  
  <mxsw:ArgumentDirectionAttribute Value="Output" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>

Die Namen, die für die Eigenschaften verwendet werden, sollten konsistent mit den Argumentnamen sein, da die Codegenerierung diese Namen als Anforderungs- oder Antworteigenschaften definiert.

Unterstützte Argumenttypen für die Eingabe- und Ausgabeargumente werden in der folgenden Tabelle gezeigt.

.NET-Typ Argumenttyp
System.Int32 Integer
System.String String
EntityReference EntityReference
Entity Entity
EntityCollection EntityCollection
System.DateTime DateTime
System.Double Gleitkomma
System.Decimal Dezimal
Money Zahlung
System.Boolean Boolean
OptionSetValue Picklist

Unterstützte Argumentattribute werden in der folgenden Tabelle aufgelistet.

Argumentattribut Beschreibung
ArgumentRequiredAttribute Gibt an, ob das Argument erforderlich ist.
ArgumentDirectionAttribute Gibt an, ob die Richtung des Arguments eine Ein- oder Ausgabe ist.
ArgumentDescriptionAttribute Gibt eine Beschreibung für das Argument an.
ArgumentEntityAttribute Wird verwendet, wenn Sie eine Entität übergeben möchten.
ArgumentTargetAttribute Dieses Attribut wird automatisch generiert oder hinzugefügt. Es verweist auf die primäre Entität, für die der Workflow ausgeführt wird. Dieses Attribut ist optional für globale Aktionen.

Packen einer Aktion zur Verteilung

Um Ihre Aktion so zu verteilen, dass sie in eine Dynamics 365 Customer Engagement (on-premises)-Organisation importiert werden kann, fügen Sie Ihre Aktion zu einer Customer Engagement-Lösung hinzu. Mit der Webanwendung ist das ganz einfach, indem Sie zu Einstellungen>Anpassungen>Lösungen gehen. Sie können auch Code schreiben, um die Lösung zu erstellen. Weitere Informationen zur Verwendung von Lösungen finden Sie unter Packen und Verteilen von Erweiterungen.

Generieren von Typen mit früher Bindung für eine Aktion

Mithilfe des CrmSvcUtil-Tools können Sie Anforderungs- und Antwortklassen für Ihre Aktion generieren, um sie in Ihren Anwendungscode aufzunehmen. Bevor Sie jedoch diese Klassen erstellen, müssen Sie die Aktion aktivieren.

Um das CrmSvcUtil.exe herunterzuladen, siehe Dataverse Entwicklungswerkzeuge.

Das folgende Beispiel zeigt das Format zum Ausführen des Tools über die Befehlszeile für eine lokale Installation von Customer Engagement. Sie stellen die Parameterwerte für die Installation bereit.

CrmSvcUtil.exe /url:https://<serverName>/<organizationName>/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /domain:<domainName> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions

Das folgende Beispiel zeigt das Format für das Ausführen des Tools über die Befehlszeile mit Dynamics 365 for Customer Engagement. Sie stellen die geeigneten Parameterwerte für Ihr Konto und Ihren Server bereit.

CrmSvcUtil.exe /url:https://<organizationUrlName>.api.crm.dynamics.com/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions

Beachten Sie die Verwendung des /generateActions-Parameters. Weitere Informationen: Erstellen Sie frühzeitig gebundene Entitätsklassen mit dem Code Generation Tool (CrmSvcUtil.exe).

Sie können Typen mit früher oder später Bindung mit den erstellen Anforderungs- und Antwortklassen für die Aktion verwenden.

Ausführen einer Aktion mithilfe der Web-API

Eine neue Aktion wird im Web-API erstellt, wenn es erstellt wird. Wenn die Aktion im Kontext einer Entität erstellt wird, wird sie an diese Entität gebunden. Andernfalls ist es eine ungebundene Aktion. Weitere Informationen finden Sie unter Verwenden von Web-API-Aktionen.

Ausführen einer Aktion mithilfe einer JavaScript-Webressource

Eine Aktion kann mithilfe des Web-API genauso wie eine beliebige Systemmaßnahme ausgeführt werden. Weitere Informationen: Xrm.WebApi.online.execute

Ausführen einer Aktion mithilfe des Organisationsservice

Damit Sie eine Aktion unter Verwendung des Organisationswebdiensts mithilfe von verwaltetem Code ausführen können, führen Sie die folgenden Schritte aus.

  1. Nehmen Sie die früh gebundene Typendatei auf, die Sie mithilfe des CrmSvcUtil-Tools im Projekt Ihrer Anwendung erstellt haben.

  2. Instanziieren Sie in Ihrem Anwendungscode die Aktionsanforderung, und füllen Sie die erforderlichen Eigenschaften aus.

  3. Rufen Sie Execute auf, und übergeben Sie die Anforderung als Argument.

    Bevor Sie den Anwendungscode ausführen, stellen Sie sicher, dass die Aktion aktiviert ist. Andernfalls erhalten Sie einen Laufzeitfehler.

Ausführen einer Aktion mithilfe eines Prozesses

Sie können eine Aktion aus Workflows, Dialogen oder anderen Prozessaktionen ausführen. Aktivierte benutzerdefinierte Aktionen sind für Prozesse verfügbar, indem Sie das Element Aktion durchführen in der Dropdownliste Schritt hinzufügen des Webanwendungsprozessformulars auswählen. Nachdem der Schritt dem Prozess hinzugefügt wurde, können Sie die neue benutzerdefinierte Aktion (oder eine andere Aktion) aus der Liste Aktion auswählen, die in dem Schritt bereitgestellt wird. Wählen Sie Eigenschaften festlegen in dem Schritt, um Eingabeparameter, die für die benutzerdefinierte Aktionen erforderlich sind, anzugeben.

Notiz

Wenn eine benutzerdefinierte Aktion nicht unterstützte Parametertypen aufweist, z. B. "Auswahlliste", "Entität" oder "Entitätssammlung", wird die benutzerdefinierte Aktion nicht in der Liste Aktion aufgeführt.

Die Möglichkeit, eine Aktion aus einem Prozess heraus auszuführen, wurde mit Dynamics CRM Online 2015 Update 1 eingeführt.

Die vorhandenen Depth-Plattformprüfungen stellen sicher, dass keine Endlosschleife auftritt. Weitere Informationen zu diesen Tiefenlimits finden Sie unter MaxDepth.

Achten auf lang laufende Aktionen

Wenn einer der Schritte im Echtzeitworkflow der Aktion eine benutzerdefinierte Workflowaktivität ist, wird diese benutzerdefinierte Workflowaktivität innerhalb der isolierten Laufzeitumgebung des Sandkastens ausgeführt und unterliegt dem zweiminütigen Timeoutlimit, ähnlich wie Plug-Ins in Sandkästen verwaltet werden. Es gibt allerdings keine Einschränkungen für die Gesamtzeit, die die Aktion selbst benötigen kann. Wenn eine Aktion an einer Transaktion teilnimmt, bei der Rollback aktiviert ist, gelten außerdem SQL Server-Timeouts.

Trinkgeld

Eine bewährte Vorgehensweise ist, dass lang laufende Vorgänge außerhalb von Dynamics 365 Customer Engagement (on-premises) mithilfe von asynchronen oder im Hintergrund laufenden .NET-Prozessen ausgeführt werden.

Siehe auch

Erstellen von Echtzeitworkflows
Verwenden von Dialogen für Kundeninteraktionen
Ereignisausführungspipeline
Erstellen von Workflows zum Automatisieren von Geschäftsprozessen
Anpassen des Systems