Workflowerweiterungen

Sie können die verfügbaren Optionen im Workflow-Designer erweitern, der in Microsoft Dataverse verwendet wird. Fügen Sie diese Erweiterungen hinzu, indem Sie eine Assembly hinzufügen, die eine Klasse enthält, die die CodeActivity-Klasse erweitert. Diese Erweiterungen werden häufig als Workflowassemblys oder Workflowaktivitäten bezeichnet.

Sie können diese benutzerdefinierten Erweiterungen im Workflow-Designer, in benutzerdefinierten Aktionen und Dialogfeldern (veraltet) verwenden.

Wann man eine Workflowerweiterung erstellen sollte

Wenn Sie die erforderlichen Funktionen nicht mithilfe der Standardprozessaktivitäten finden, fügen Sie benutzerdefinierte Aktivitäten hinzu, sodass sie im Editor verfügbar sind, der zum Verfassen von Workflows, Dialogen und Aktionsprozessen verwendet wird.

Standardmäßig enthalten diese Prozesse einen allgemeinen Satz von Aktivitäten, die Sie ausführen können, wie in der folgenden Tabelle dargestellt:

Verwenden Sie die Aktivität "Aktion ausführen", um benutzerdefinierte Aktionen oder die folgenden Systemmeldungen mit dem Namen "Befehlsaktionen" auszuführen:

Wenn Sie über Dynamics 365 Sales- oder Servicelösungen verfügen, finden Sie je nach Lösung weitere Befehlsaktionen:

Weitere Informationen findest du unter:

• Konfigurieren von Workflowphasen und -schritten
• Verwenden von Dataverse-Dialogfeldern für geführte Prozesse
• Erstellen einer benutzerdefinierten Aktion

Verwendete Technologie

Sie können eine Assembly registrieren, die mithilfe der .NET Framework-Aktivitätsbibliothek erstellt wird, die benutzerdefinierte Aktivitäten definiert. Diese Aktivitäten werden im Webanwendungs-Editor angezeigt und beim Ausführen des Prozesses aufgerufen.

Benutzerdefinierte Workflowaktivitäten erfordern das Erstellen einer .NET Framework-Assembly, die mindestens eine von der abstrakten CodeActivity-Klasse abgeleitete Klassen enthält. Diese Klasse stellt die Execute(CodeActivityContext)-Methode bereit, die die Dataverse-Plattform aufruft, wenn die Aktivität ausgeführt wird. Jede Klasse in Ihrer Assembly definiert eine bestimmte Aktivität.

Workflowaktivitäten sollten Eingabe- und Ausgabeparameter definieren, die im Prozess-Designer sichtbar sind. Diese Parameter ermöglichen es jemanden, Daten an die Workflowaktivität zu übergeben und die verarbeitete Ausgabe zu empfangen. Wenn Sie die Klasse schreiben, fügen Sie Eigenschaften für diese Parameter hinzu, und kommentieren Sie sie mit .NET-Attributen , um die Metadaten bereitzustellen, die Dataverse verwendet, um Ihre benutzerdefinierte Workflowaktivität mit allen Parametern im Designer verfügbar zu machen.

Erstellen einer benutzerdefinierten Assembly von Workflowaktivitäten

In diesen Schritten wird beschrieben, wie Sie mithilfe von Visual Studio eine benutzerdefinierte Workflowaktivität erstellen. Ein vollständiges Schritt-für-Schritt-Beispiel finden Sie im Lernprogramm: Erstellen der Workflowerweiterung.

1. Erstellen Sie ein Klassenbibliotheksprojekt, das auf .NET Framework 4.6.2 ausgerichtet ist.

   Von Bedeutung

   Während Assemblys, die mit späteren Versionen erstellt wurden, in der Regel funktionieren sollten, tritt ein Fehler auf, wenn sie Features verwenden, die nach 4.6.2 eingeführt wurden.

2. Installieren Sie das Microsoft.CrmSdk.Workflow NuGet-Paket.

   Dieses Paket enthält das Paket "Microsoft.CrmSdk.CoreAssemblies ".

3. (Optional) Wenn Sie früh gebundene Tabellenklassen verwenden möchten, fügen Sie sie in das Projekt ein.

   Weitere Informationen findest du unter:

   • Programmierung mit später und früher Bindung mithilfe des SDK für .NET
   • Generieren von Klassen mit früher Bindung für das SDK für .NET

4. Fügen Sie eine öffentliche Klasse hinzu. Der Name der Klasse sollte der Aktion entsprechen, die von der Aktivität ausgeführt wird.

5. Die folgenden Nutzungs-Direktiven hinzufügen.

   using System.Activities;
   using Microsoft.Xrm.Sdk;
   using Microsoft.Xrm.Sdk.Workflow;
   

6. Fügen Sie der Klasse Eigenschaften hinzu, um alle Eingabe- oder Ausgabeparameter darzustellen. Verwenden Sie .NET-Attribute , um die erforderlichen Metadaten bereitzustellen, um diese Eigenschaften für den Workflowprozess-Designer verfügbar zu machen.

   Weitere Informationen finden Sie unter Hinzufügen von Parametern.

7. Leiten Sie Ihre Klasse von der CodeActivity-Klasse ab, und implementieren Sie die Execute(CodeActivityContext)-Methode , die die Vorgänge enthält, die Ihre Aktivität ausführt.

   Weitere Informationen finden Sie unter Hinzufügen ihres Codes zur Execute-Methode.

8. Signieren Sie Ihre Assembly.

9. Erstellen Sie Ihre Baugruppe.

10. Registrieren Sie Ihre Assembly mithilfe des Plug-In-Registrierungstools. Legen Sie die Eigenschaften Name und WorkflowActivityGroupName fest, um den Text zu definieren, den der Workflow-Designer anzeigt.

    Weitere Informationen finden Sie unter: Ihre Assembly registrieren.

11. Testen Sie Ihre Workflowaktivität, indem Sie sie innerhalb eines Workflows, Dialogfelds oder Aktionsprozesses aufrufen.

12. Empfohlen: Fügen Sie Ihre Workflowaktivität zu einer Lösung hinzu.

Parameter hinzufügen

Wenn Sie Parameter für Ihre Klasse definieren, sollten Sie sie als InArgument<T>, OutArgument<T> oder InOutArgument<T>-Typen festlegen. Diese Typen stellen Methoden bereit, die von einer allgemeinen Argumentklasse geerbt werden, um die Parameter abzurufen oder festzulegen. Ihr Code verwendet diese Methoden in der Execute Methode. Weitere Informationen finden Sie unter Hinzufügen ihres Codes zur Execute-Methode.

Wenn Ihre benutzerdefinierte Workflowaktivität Eingabe- oder Ausgabeparameter verwendet, fügen Sie die entsprechenden .NET-Attribute zu den eigenschaften der öffentlichen Klasse hinzu, die sie definieren. Der Prozess-Designer liest diese Daten vor, um zu definieren, wie die Parameter im Prozess-Designer festgelegt werden können.

Sie können die folgenden Eigenschaftentypen als Eingabe- oder Ausgabeparameter verwenden:

Eingabe- und Ausgabeparameter

Verwenden Sie zum Definieren des Texts, der für einen Eingabe- oder Ausgabeparameter im Prozess-Designer angezeigt werden soll, das folgende Muster mit .NET-Attributen:

[Input("Integer input")]
public InArgument<int> IntInput { get; set; }

or

[Output("Integer output")]
public OutArgument<int> IntOutput { get; set; }

Eine einzelne Eigenschaft in Ihrer Klasse kann ein Eingabe- und Ausgabeparameter sein, indem beide Attribute eingeschlossen werden:

[Input("Int input")]  
[Output("Int output")]  
public InOutArgument<int> IntParameter { get; set; }

Erforderliche Werte

Verwenden Sie das [RequiredArgument] Attribut, um einen Eingabeparameter zu erstellen, der für die Verwendung der Workflowaktivität in einem Prozess erforderlich ist.

Standardwerte

Wenn Sie einen Wert als Eingabeparameter übergeben oder einen Ausgabeparameter festlegen, ohne den Wert zu definieren, geben Sie einen Standardwert an. Der folgende Code legt z. B. den Standardwert für eine Bool-Eigenschaft fest:

[Input("Bool input")]
[Default("True")]
public InArgument<bool> Bool { get; set; }

Das Format für den Standardwert hängt vom Typ der Eigenschaft ab. Beispiele sind in der folgenden Tabelle:

EntityReference-Parameter

Wenn Sie eine Eigenschaft für einen EntityReference Parameter definieren, verwenden Sie das ReferenceTarget Attribut. Dieses Attribut legt fest, welche Art von Tabelle zulässig ist. Beispiel:

[Input("EntityReference input")]
[Output("EntityReference output")]
[ReferenceTarget("account")]
public InOutArgument<EntityReference> AccountReference { get; set; }

OptionSetValue-Parameter

Wenn Sie eine Eigenschaft für einen OptionSetValue Parameter definieren, verwenden Sie das AttributeTarget Attribut. Dieses Attribut definiert, welche Tabelle und Spalte den gültigen Wertesatz für den Parameter enthält. Beispiel:

[Input("Account IndustryCode value")]
[AttributeTarget("account", "industrycode")]
[Default("3")]
public InArgument<OptionSetValue> IndustryCode { get; set; }

Fügen Sie Ihren Code zur Execute-Methode hinzu

Die Logik, die Sie in die CodeActivity.Execute(CodeActivityContext)-Methode einschließen, definiert, was Ihre Workflowaktivität bewirkt.

Parameter referenzieren

Um auf Parameter zu verweisen, die Sie für Ihre Klasse definieren, verwenden Sie die Methoden Argument.Get oder Argument.Set(ActivityContext, Object) Für diese Methoden ist die CodeActivityContext-Instanz erforderlich, die an die Execute Methode übergeben wird. Das folgende Beispiel zeigt, wie Sie auf den Wert eines Eingabeparameters zugreifen und den Wert eines Ausgabeparameters festlegen.

using Microsoft.Xrm.Sdk.Workflow;
using System.Activities;

namespace SampleWorkflowActivity
{
  public class IncrementByTen : CodeActivity
  {
    [RequiredArgument]
    [Input("Decimal input")]
    public InArgument<decimal> DecInput { get; set; }

    [Output("Decimal output")]
    public OutArgument<decimal> DecOutput { get; set; }

    protected override void Execute(CodeActivityContext context)
    {
      decimal input = DecInput.Get(context);
      DecOutput.Set(context, input + 10);
    }
  }
}

Abrufen kontextbezogener Informationen

Wenn Ihr Code kontextbezogene Informationen benötigt, greifen Sie mithilfe der CodeActivityContext.GetExtension<T-Methode> mit der IWorkflowContext Schnittstelle darauf zu. Dieses Objekt ist von der IExecutionContext-Schnittstelle abgeleitet, die den Zugriff auf viele schreibgeschützte Eigenschaften ermöglicht, die den Kontext des Vorgangs beschreiben. Dies IWorkflowContext stellt ähnliche Kontextinformationen bereit, die für den ausgeführten Workflow spezifisch sind, der Ihre Workflowassembly verwendet.

Verwenden Sie den folgenden Code in Ihrer Execute Funktion, um auf folgendes IWorkflowContextzuzugreifen:

protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...

Das SDK für .NET verwenden

Wenn Sie Datenvorgänge mithilfe des SDK für .NET ausführen müssen, greifen Sie mithilfe der CodeActivityContext.GetExtension<T-Methode> mit der IOrganizationServiceFactory Schnittstelle darauf zu. Verwenden Sie von dort aus die CreateOrganizationService(Nullable<Guid>) Methode, um auf eine Instanz des Dienstproxys zuzugreifen, die Sie zum Ausführen von Datenvorgängen verwenden können. Die IWorkflowContext.InitiatingUserId -Eigenschaft kann verwendet werden, um den zu verwendenden Benutzerkontext zu bestimmen, wenn der Vorgang im gleichen Kontext wie der aufrufende Prozess ausgeführt werden soll. Verwenden Sie den folgenden Code in Ihrer Execute Funktion, um Zugriff auf den Organisationsdienst zu erhalten:

protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
 IOrganizationServiceFactory serviceFactory = context.GetExtension<IOrganizationServiceFactory>();

 // Use the context service to create an instance of IOrganizationService.             
 IOrganizationService service = serviceFactory.CreateOrganizationService(workflowContext.InitiatingUserId);
...

Registrieren Sie Ihre Assembly

Verwenden Sie das Plug-In-Registrierungstool (PRT), um Assemblys zu registrieren, die benutzerdefinierte Workflowaktivitäten enthalten. Dieses Tool ist dasselbe, das Sie zum Registrieren von Plug-Ins verwenden. Für Plug-Ins und benutzerdefinierte Workflowaktivitäten müssen Sie die Assembly registrieren, um sie in die Umgebung hochzuladen. Sie registrieren jedoch keine Schritte für benutzerdefinierte Workflowaktivitäten.

Geben Sie für benutzerdefinierte Workflowaktivitäten die folgenden Eigenschaften an, um zu steuern, was der Workflowprozess-Designer anzeigt.

Debuggen von Workflowaktivitäten

Wenn Sie benutzerdefinierte Workflowaktivitäten für Dataverse bereitstellen, können Sie Profile erfassen, um die Wiedergabe für das lokale Debuggen durchzuführen und den Ablaufverfolgungsdienst zum Schreiben von Informationen in eine Tabelle zu verwenden.

Das folgende Beispiel zeigt, wie Sie den Tracing-Dienst verwenden, um die Nachricht zu schreiben: Add your message.

protected override void Execute(CodeActivityContext context)
{
//Create the tracing service
ITracingService tracingService = context.GetExtension<ITracingService>();

//Use the tracing service
tracingService.Trace("{0} {1} {2}.", "Add", "your", "message");
...

Weitere Informationen findest du unter:

• Debuggen von Workflowaktivitäten
• Ablaufverfolgung verwenden
• Ablaufverfolgungsprotokolle anzeigen

Zur Lösung hinzufügen

Wenn Sie Assemblys mithilfe des Plug-In-Registrierungstools registrieren, fügen Sie sie zur Standardlösung hinzu. Verwechseln Sie diese Lösung nicht mit der Standardlösung "Common Data Service". Da die Standardlösung alle nicht verwalteten Anpassungen enthält, die auf die Umgebung angewendet werden, müssen Sie sie einer nicht verwalteten Lösung hinzufügen, bevor Sie Ihre benutzerdefinierte Workflowaktivität mithilfe einer Lösung verteilen können. Sie können es beispielsweise zur Common Data Service Standardlösung oder zu einer von Ihnen erstellten nicht verwalteten Lösung hinzufügen.

Verwalten von Änderungen an benutzerdefinierten Workflowaktivitäten

Sie müssen den Code für Ihre benutzerdefinierten Workflowaktivitäten verwalten. Da Codeänderungen Fehler verursachende Änderungen beinhalten können, müssen Sie diese Änderung verwalten. Führen Sie verschiedene Schritte aus, um Ihre benutzerdefinierten Workflow-Assemblies zu aktualisieren oder zu verbessern.

Wenn Sie eine Assembly registrieren, die benutzerdefinierte Workflowaktivitäten enthält, ist die Version der Assembly enthalten. Das Registrierungstool extrahiert diese Informationen mithilfe der Spiegelung aus der Assembly. Sie können die Versionsnummer mithilfe der AssemblyInfo.cs Datei in Ihrem Visual Studio-Projekt steuern.

Unten finden Sie einen Abschnitt, der wie folgt aussieht:

// Version information for an assembly consists of the following four values:
//
//      Major Version
//      Minor Version 
//      Build Number
//      Revision
//
// You can specify all the values or you can default the Build and Revision Numbers 
// by using the '*' as shown below:
//[assembly: AssemblyVersion("1.0.0.*")]
[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("1.0.0.0")]

Diese Versionsinformationen sind wichtig, da Sie Updates auf bereitgestellte Assemblys oder Upgradeassemblys anwenden können, wenn Sie neue Funktionen einbeziehen möchten.

Aktualisierung einer benutzerdefinierten Assembly für Workflow-Aktivitäten

Wenn Sie Fehler beheben oder Code umgestalten, ohne wesentliche Änderungen an öffentlichen Klassen oder Methodensignaturen vorzunehmen, aktualisieren Sie die Assembly so, dass alle ausgeführten Prozesse automatisch mit der neuen Version der Assembly beginnen.

So aktualisieren Sie eine Assembly

1. Ändern Sie nur die Buildnummer und Revisionswerte in Ihrem AssemblyInfo.csAssemblyVersion-Attribut. Ändern Sie z. B. von 1.0.0.0 zu 1.0.10.5.
2. Verwenden Sie das Plug-In-Registrierungstool, um die Assembly zu aktualisieren. Weitere Informationen finden Sie unter Aktualisieren einer Assembly.

Aktualisieren einer benutzerdefinierten Workflow-Aktivitätsassembly

Wenn Sie Änderungen vornehmen, die erhebliche Änderungen an öffentlichen Klassen oder Methodensignaturen enthalten, z. B. das Ändern der Parameter, unterbrechen Sie alle derzeit ausgeführten Prozesse, die für die Verwendung der ursprünglichen Signaturen definiert sind. In diesem Fall müssen Sie die Assembly aktualisieren. Diese Aktion erstellt eine neue benutzerdefinierte Workflowaktivität, die Optionen verfügbar macht, um zu definieren, welche Version im Prozess-Designer angewendet werden soll. Mit dieser Versionsverwaltung kann jeder Prozess, der diese Aktivität verwendet, neu konfiguriert werden, um sich an die Änderungen anzupassen, die in der neuen Assembly enthalten sind. Nachdem alle Prozesse aktualisiert wurden, um die aufgerüstete Assembly zu verwenden, können Sie die ältere Assembly deregistrieren.

So aktualisieren Sie eine Assembly

1. Stellen Sie sicher, dass die neue Assembly dieselben Name, PublicKeyToken und Culture wie die vorhandene Assembly aufweist.

2. Ändern Sie die Werte der Hauptversion und/oder der Nebenversion in Ihrem AssemblyInfo.csAssemblyVersion Attribut. Ändern Sie z. B. von 1.0.0.0 zu 2.0.0.0.

3. Verwenden Sie das Plug-In-Registrierungstool, um die Assembly als neue Assembly zu registrieren. Weitere Informationen finden Sie unter: Eine Assembly registrieren.

4. Deaktivieren Sie für jeden Prozess, der die benutzerdefinierte Workflowaktivität verwendet, den Prozess, und bearbeiten Sie die Schritte, die die benutzerdefinierte Workflowaktivität verwenden.

   Sie finden eine Versionsauswahl im Prozess-Designer, mit der Sie auswählen können, welche Version der Assembly verwendet werden soll.

   

Wenn alle Prozesse in die Verwendung der neuen Assembly konvertiert werden, verwenden Sie das Plug-In-Registrierungstool, um die Registrierung der Assembly aufzuheben, sodass sie nicht mehr verfügbar ist. Weitere Informationen finden Sie unter Aufheben der Registrierung von Komponenten.

Leistungsleitfaden

Leistungsüberlegungen für Ihre Workflowerweiterungen sind identisch mit normalen Plug-Ins. Weitere Informationen finden Sie unter Analysieren der Plug-In-Leistung.

Im Gegensatz zu einem normalen Plug-In bieten Workflowerweiterungen nicht die Möglichkeit, Ihren Code explizit für einen bestimmten Schritt zu registrieren. Sie steuern nicht, ob der Code in der Workflowerweiterung synchron oder asynchron ausgeführt wird. Code, der synchron ausgeführt wird, erfordert besondere Sorgfalt, da er sich direkt auf die Benutzererfahrung der Anwendung auswirkt.

Als wiederverwendbare Komponenten können Sie Workflowerweiterungen zu einer beliebigen Workflow- oder benutzerdefinierten Aktion hinzufügen. Sie können den Workflow als Echtzeitworkflow konfigurieren, was bedeutet, dass er synchron ausgeführt wird. Benutzerdefinierte Aktionen sind immer synchron, nehmen aber nicht an einer Datenbanktransaktion teil, es sei denn, Sie legen "Rollback aktivieren" fest.

Beachten Sie, dass in einem synchronen Workflow oder einer benutzerdefinierten Aktion, die an der Transaktion teilnimmt, jeder fehler, der von der Workflowerweiterung ausgelöst wird, dazu führt, dass die gesamte Transaktion zurückgerollt wird. Dieses Rollback ist ein kostspieliger Vorgang, der sich auf die Leistung auswirken kann.

Verwenden Sie den Wert in der IWorkflowContextEigenschaft .WorkflowMode , um zu ermitteln, ob der Workflow synchron ausgeführt wird.

Workflowphasen in Echtzeit

Wenn Sie eine Workflow-Erweiterung in einem Echtzeit- (synchronen) Workflow verwenden, ruft die Ereignisausführungspipeline die Erweiterung zu bestimmten Zeitpunkten auf. Die folgende Tabelle zeigt diese Phasen. Weitere Informationen finden Sie unter Ereignisausführungspipeline.

Verwenden Sie den Wert in der IWorkflowContextEigenschaftStageName, um die Phase zu erkennen.

Für den Aktualisierungsvorgang können Sie die Phase mithilfe der Optionen "Vor " oder "Nach" im Workflow-Designer konfigurieren. Weitere Informationen finden Sie unter Verwenden von Echtzeitworkflows.

Wenn Ihre Workflowerweiterung von Daten abhängig ist, die an den Ausführungskontext übergeben werden, steuert die Phase, in der sie ausgeführt wird, ob die Daten hier verfügbar sind: IWorkflowContext.InputParameters und IWorkflowContext.OutputParameters.

Entitätsbilder für Workflow-Erweiterungen

Sie können Entitätsimages nicht für Workflowerweiterungen konfigurieren. Sie registrieren nur die Assembly, und die Workflowaktivität wird im Kontext des Workflows ausgeführt. Für Workflowerweiterungen sind Entitätsbilder mithilfe der Schlüsselwerte PreBusinessEntity und PostBusinessEntity jeweils für vorherige und spätere Entitätsbilder verfügbar. Weitere Informationen finden Sie unter Entitätsbilder.

Siehe auch

Beste Praktiken und Anleitungen hinsichtlich Plug-In und Workflow-Entwicklung
Lernprogramm: Erstellen einer Workflow-Erweiterung
Beispiel: Eine benutzerdefinierte Workflowaktivität erstellen
Beispiel: Aktualisieren des nächsten Geburtstags mithilfe einer benutzerdefinierten Workflowaktivität
Beispiel: Berechnen einer Kreditbewertung mit einer benutzerdefinierten Workflowaktivität