Workflowerweiterungen

Sie können die Optionen erweitern, die innerhalb des Designers für Workflows zur Verfügung stehen, der für Common Data Service verwendet wird. Diese Erweiterungen werden hinzufügt, indem eine Assembly hinzufügt wird, 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 innerhalb des Designers verwenden, der für Workflows, benutzerdefinierte Aktionen und Dialoge verwendet wird.

Wichtig

Wenn immer möglich, sollten Sie zunächst erwägen, eine von mehreren deklarativen Optionen zur Definition der Geschäftslogik anzuwenden. Weitere Informationen: Anwenden von Geschäftslogik in Common Data Service

Verwenden Sie Workflowerweiterungen, wenn ein deklarativer Prozess nicht Ihre Bedingung erfüllt.

Wann eine Workflowerweiterung zu erstellen ist

Wenn Sie mithilfe der Standardprozessaktivitäten nicht die erforderliche Funktion finden, können Sie benutzerdefinierte Aktivitäten hinzufügen, sodass sie im Editor verfügbar sind, der zum Erstellen von Workflow-, Dialog- und Aktionsprozessen verwendet wird.

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

Aktivität Workflow Aktion Dialogfeld
Daten abfragen X
Wert zuweisen X X
Datensatz erstellen X X X
Datensatz aktualisieren X X X
Datensatz zuweisen X X X
E-Mail senden X X X
Untergeordneten Workflow starten X X X
Aktion durchführen X X
Untergeordnetes Dialogfeld verknüpfen X
Status ändern X X X
Workflow beenden X X
Dialog anhalten X

Sie können die Aktivität Aktion durchführen verwenden, um sämtliche benutzerdefinierten Aktionen oder die folgenden Systemmeldungen, die als Befehlsaktionen bezeichnet werden, auszuführen:

AddToQueue AddUserToRecordTeam RemoveUserFromRecordTeam
SetProcess SetWordTemplate

Wenn Sie Dynamics 365 Customer Engagement Sales oder Service-Lösungen haben, können Sie andere Befehlsaktionen, je nach Lösung, finden:

ApplyRoutingRule CalculateActualValue Verkaufschance schließen
GetQuoteProductsFromOpportunity GetSalesOrderProductsFromOpportunity LockInvoicePricing
LockSalesOrderPricing QualifyLead RemoveUserFromRecordTeam
ResolveIncident ResolveQuote Überarbeiten
UnlockInvoicePricing UnlockSalesOrderPricing

Weitere Informationen:

Verwendete Technik

Da Prozesse Windows Workflow Foundation verwenden, können Sie eine erstellte Assembly mithilfe der .NET Framework-Aktivitätsbibliothek speichern, die benutzerdefinierte Aktivitäten definiert, die innerhalb des Webanwendungs-Editors angezeigt werden und aufgerufen werden, wenn der Prozess ausgeführt wird.

Benutzerdefinierte Workflowaktivitäten erfordern das Erstellen einer .NET Framework-Assembly, die mindestens eine Klasse enthält, die aus der Zusammenfassung abgeleitet ist CodeActivity-Klasse. Diese Klasse stellt die Execute(CodeActivityContext)-Methode bereit, die von der "Common Data Service"-Plattform aufgerufen wird, wenn die Aktivität ausgeführt wird. Jede Klasse in Ihrer Assembly definiert eine bestimmte Aktivität.

Workflowaktivitäten können auch Eingabe- und Ausgabeparameter definieren, die im Prozess-Designer sichtbar sind, und sie ermöglichen es einer Person, Daten an die Workflowaktivität zu übergeben und die verarbeitete Ausgabe zu erhalten. Wenn Sie die Klasse schreiben, fügen Sie Parameter für diese Eigenschaften hinzu und fügen zu ihnen Anmerkungen mit .NET-Attributen hinzu, um die Metadaten bereitzustellen, die Common Data Service verwenden wird, um Ihre benutzerdefinierte Workflowaktivität mit sämtlichen Parametern im Designer verfügbar zu machen.

Visual Studio-Anforderungen

Um benutzerdefinierte Workflowaktivitäten zu erstellen, müssen Sie Visual Studio mit der Workload .NET-Desktopentwicklung installieren sowie die einzelne Komponente Windows Workflow Foundation.

Sie können die kostenlose Visual Studio 2017 Community-Edition oder die Professional- und Enterprise-Editionen verwenden.

Zur Überprüfung der Installation oder um diese Komponente hinzuzufügen:

  1. Öffnen Sie Visual Studio 2017
  2. Wählen Sie Extras > Tools und Funktionen abrufen… . Dadurch wird das Visual Studio-Installationsprogramm geöffnet
  3. Stellen Sie auf der Registerkarte Workloads sicher, dass die Workload .NET-Desktopentwicklung ausgewählt ist. Erforderliche Visual Studio-Workloads
  4. Wählen Sie Einzelne Komponenten aus, und führen Sie einen Bildlauf nach unten zum Abschnitt Entwicklungsaktivitäten durch. Erforderliche einzelne Komponenten von Visual Studio
  5. Wenn Windows Workflow Foundation nicht ausgewählt ist, wählen Sie es aus. Die Komponente Windows Communication Foundation wird ebenfalls einbezogen.
  6. Wenn Sie neue Workloads oder Komponenten hinzugefügt haben, klicken Sie auf Ändern, damit das Visual Studio-Installationsprogramm sie installieren kann. Andernfalls schließen Sie das Visual Studio-Installationsprogramm.

Weitere Informationen: Installieren von Visual Studio 2017

Erstellen einer benutzerdefinierten Workflowaktivitäts-Assembly

Im Folgenden werden allgemeine Schritte angegeben, die verwendet werden, um eine benutzerdefinierte Workflowaktivität mithilfe von Visual Studio zu erstellen. Ein vollständiges Beispiel mit einer Schritt-für-Schritt-Anleitung finden Sie unter Tutorial: Erstellen einer Workflowerweiterung Sie unter.

  1. Erstellen Sie ein Workflowaktivitäts-Bibliotheksprojekt mithilfe von .NET Framework 4.6.2 als Zielframework

  2. Löschen Sie die Datei Activity1.xaml, die mit dem Projekt generiert wurde.

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

    Dieses Paket umfasst das Microsoft.CrmSdk.CoreAssemblies-Paket.

  4. (Optional) Wenn Sie Entitätsklassen mit früher Bindung verwenden möchten, schließen Sie in das Projekt ein.

    Weitere Informationen:

  5. Fügen Sie eine öffentliche Klasse hinzu. Der Name der Klasse sollte der von der Aktivität auszuführenden Aktion entsprechen.

  6. Die folgenden using-Direktiven hinzufügen

    using System.Activities;
    using Microsoft.Xrm.Sdk;
    using Microsoft.Xrm.Sdk.Workflow;
    
  7. Fügen Sie Eigenschaften der Klasse hinzu, um alle Eingabe- oder Ausgabeparameter darzustellen und verwenden Sie .NET-Attribute, um die erforderlichen Metadaten bereitzustellen, um diese Eigenschaften dem Workflowprozess-Designer verfügbar zu machen.

    Weitere Informationen: Parameter hinzufügen

  8. Stellen Sie sicher, dass Ihre Klasse von der CodeActivity-Klasse abgeleitet ist, und implementieren Sie die Execute(CodeActivityContext)-Methode, die die Vorgänge enthält, die Ihre Aktivität ausführen wird.

    Weitere Informationen: Fügen Sie Ihren Code der Execute-Methode hinzu

  9. Signieren Sie Ihre Assembly

  10. Erstellen Sie Ihre Assembly.

  11. Registrieren Sie Ihre Assembly mithilfe des Plug-In-Registrierungstools, und legen Sie die Eigenschaften "Name" und "WorkflowActivityGroupName" fest, um den Text zu definieren, der im Dyn365CE-Prozessdesigner angezeigt wird.

    Weitere Informationen: Ihre Assembly registrieren

  12. Testen Sie Ihre Workflowaktivität, indem Sie sie von innerhalb eines Workflows, eines Dialogs oder von Aktionsprozessen aus aufrufen

  13. (Empfohlen) Fügen Sie Ihrer Workflowaktivität einer Lösung hinzu.

Parameter hinzufügen

Wenn Sie Parameter für Ihre Klasse definieren, müssen Sie sie als InArgument-, OutArgument-, or InOutArgument-Typen definieren. Diese Typen stellen Methoden bereit, die von einer allgemeinen Argument-Klasse geerbt werden zum Abrufen oder Festlegen der Parameter. Ihr Code verwendet diese Methoden in der Execute-Methode. Weitere Informationen: Fügen Sie Ihren Code der Execute-Methode hinzu

Wenn Ihre benutzerdefinierte Workflowaktivität Eingabe- oder Ausgabeparameter verwendet, müssen Sie den öffentlichen Klasseneigenschaften, die sie definieren, entsprechende .NET-Attribute hinzufügen. Die Daten werden vom Prozess-Designer gelesen, um zu definieren, wie die Parameter im Prozess-Designer festgelegt werden können.

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

bool DateTime Dezimalzahl
Doppelt EntityReference int
Money OptionSetValue Zeichenfolge

Eingabe- und Ausgabeparameter

Um den Text zu definieren, der für ein Eingabe- oder Ausgabeparameter im Prozess-Designer angezeigt werden soll, verwenden Sie das folgende Muster mithilfe von .NET Attributen.

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

oder

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

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

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

Erforderliche Werte

Wenn Sie einen Eingabeparameter erstellen möchten, der bei der Verwendung der Workflowaktivität in einem Prozess erforderlich ist, müssen Sie das [RequiredArgument]-Attribut verwenden.

Standardwerte

Wird ein Wert, der als Eingabeparameter übergeben wird oder als Ausgabeparameter festgelegt wird, nicht definiert wird, können Sie einen Standardwert angeben. So legen Sie beispielsweise den Standardwert für eine boolesche 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. In der folgenden Tabelle sind einige Beispiele:

Typ Beispiel
bool [Default("True")]
DateTime [Default("2004-07-09T02:54:00Z")]
Dezimalzahl [Default("23.45")]
Doppelt [Default("23.45")]
Money [Default("23.45")]
EntityReference [Default("3B036E3E-94F9-DE11-B508-00155DBA2902", "account")]
int [Default("23")]
OptionSetValue [Default("3")]
Zeichenfolge [Default("string default")]

EntityReference-Parameter

Wenn Sie eine Eigenschaft für einen EntityReference-Parameter definieren, müssen Sie das Attribut ReferenceTarget verwenden. Dies legt fest, welcher Attributtyp 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, müssen Sie das Attribut AttributeTarget verwenden. Dieses Attribut definiert, welche Entitäten und welches Attribut den gültigen Satz von Werten 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 der Execute-Methode hinzu

Die Logik, die Sie in die CodeActivity.Execute(CodeActivityContext)-Methode-Methode einbeziehen, definiert, was Ihre Workflowaktivität ausführt.

Wichtig

Der Code in der Execute-Methode sollte als statusfrei geschrieben werden. Es wird nicht empfohlen, globale oder Membervariablen zu verwenden, um Daten von einem Aufruf zum nächsten zu übergeben. Zur Verbesserung der Leistung werden benutzerdefinierte Workflowaktivitätsinstanzen von Common Data Service zwischengespeichert. Deshalb wird der Konstruktor nicht für jeden Aufruf der benutzerdefinierten Workflowaktivität aufgerufen. Außerdem könnten mehrere Systemthreads die benutzerdefinierte Workflowaktivität gleichzeitig ausführen. Sie sollten nur die Informationen verwenden, die über den Parameter CodeActivityContext an die Execute-Methode übergeben werden.

Parameter referenzieren

Um auf Parameter, die für Ihre Klasse definiert sind, zu verweisen, verwenden Sie die Methoden Argument.Get oder Argument.Set(ActivityContext, Object), die sie bereitstellen. Diese erfordern die Instanz CodeActivityContext, die an die Execute-Methode übergeben wird. Im folgenden Beispiel wird gezeigt, wie auf den Wert eines Eingabeparameters zugegriffen wird und wie der Wert eines Ausgabeparameters festgelegt wird.

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);
    }
  }
}

Kontextbezogene Informationen abrufen

Wenn Ihr Code kontextbezogene Informationen benötigt, können Sie darauf mithilfe der CodeActivityContext.GetExtension-Methode mit der IWorkflowContext-Schnittstelle zugreifen. Dieses Objekt wird von der IExecutionContext-Schnittstelle abgeleitet, welche Zugriff auf viele schreibgeschützte Eigenschaften bereitstellt, die den Kontext des Vorgangs beschreiben. Der IWorkflowContext stellt ähnliche kontextbezogene Informationen bereit, die für den ausführenden Workflow spezifisch sind, der Ihre Workflowassembly verwendet.

Verwenden Sie den folgenden Code in Ihrer Execute-Funktion, um auf IWorkflowContext zuzugreifen:

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

...

Verwenden Sie den Organisationsservice

Wenn Sie Datenvorgänge mithilfe des Organisationsdiensts ausführen müssen, können Sie darauf mithilfe der CodeActivityContext.GetExtension-Methode mit der IOrganizationServiceFactory-Schnittstelle zugreifen. Von dort aus können Sie die CreateOrganizationService(Nullable<Guid>)-Methode verwenden, um auf eine Instanz oder den Service-Proxy zuzugreifen, den Sie für die Durchführung von Datenvorgängen verwenden können. Im IWorkflowContext.InitiatingUserId kann verwendet werden, um den zu verwendenden Benutzerkontext zu bestimmen, wenn Sie möchten, dass der Vorgang im selben Kontext wie der aufrufende Prozess ausgeführt wird. 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 Ihrer Assembly

Sie verwenden das Plug-In-Registrierungstool (PRT), um Assemblys zu registrieren, die benutzerdefinierte Workflowaktivitäten enthalten. Dies ist dasselbe Tool, das Sie verwenden, um Plug-Ins zu registrieren. Sowohl bei Plug-Ins als auch bei benutzerdefinierten Workflowaktivitäten müssen Sie die Assembly registrieren, die sie in die Umgebung hochladen wird. Sie registrieren jedoch keine Schritte für benutzerdefinierte Workflowaktivitäten.

Für benutzerdefinierte Workflowaktivitäten müssen Sie die folgenden Eigenschaften angeben, um zu steuern, was im Workflowprozess-Designer angezeigt wird.

Feld Beschreibung
Beschreibung Wird in der Benutzeroberfläche des Prozessdesigners nicht angezeigt, kann aber bei der Erstellung der Dokumentation von Daten aus der PluginType-Entität hilfreich sein, in der diese Informationen gespeichert werden.
FriendlyName Anzeigename des Benutzers für das Plug-In.
Name Der Name des dargestellten Menüs.
WorkflowActivityGroupName Der Name des Untermenüs, das dem Hauptmenü im Common Data Service-Prozess hinzugefügt wurde.

Beschreibende Eigenschaften festlegen

Hinweis

Diese Werte werden in der nicht verwalteten Lösung nicht angezeigt, wenn Sie Ihre Workflowaktivität testen. Wenn Sie allerdings eine verwaltete Lösung exportieren, die diese Workflowaktivität enthält, werden diese Werte im Prozessdesigner angezeigt.

Workflowaktivitäten debuggen

Mit benutzerdefinierten Workflowaktivitäten, die für Common Data Service bereitgestellt sind, können Sie Profile erfassen, um sie für lokale Debugvorgänge erneut wiederzugeben und Sie können den Ablaufverfolgungsdienst verwenden, um Informationen in eine Entität zu schreiben.

Das folgende Bespiel zeigt, wie mithilfe des Ablaufverfolgungsdiensts die folgende Nachricht geschrieben wird: Add your message.

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

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

...

Weitere Informationen:

Zur Lösung hinzufügen

Wenn Sie Assemblys mithilfe des Plug-In-Registrierungstools registrieren, werden sie der Standardlösung hinzugefügt, die nicht mit der Common Data Service-Standardlösung zu verwechseln ist. Da die Standardlösung alle nicht verwalteten Anpassungen enthält, die auf die Umgebung angewendet werden, bevor Sie Ihre benutzerdefinierte Workflowaktivität mithilfe einer Lösung verteilen können, müssen Sie sie einer nicht verwalteten Lösung hinzufügen. Sie könnten sie beispielsweise der Common Data Service-Standardlösung oder einer beliebigen nicht verwalteten Lösung hinzufügen, die Sie erstellt haben.

Änderungen an benutzerdefinierten Workflowaktivitäten verwalten

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. Sie verwenden verschiedene Schritte, um Ihre benutzerdefinierten Workflowassemblys zu aktualisieren oder ein Upgrade an ihnen auszuführen.

Wenn Sie eine Assembly registrieren, die benutzerdefinierte Workflowaktivitäten enthält, wird die Version der Assembly einbezogen. Diese Informationen werden mithilfe der Reflektion von der Assembly extrahiert. Sie können die Versionsnummer mithilfe der Datei AssemblyInfo.cs in Ihrem Visual Studio-Projekt steuern.

Sie finden einen Abschnitt unten, der so 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 es Ihnen ermöglichen, Updates auf bereitgestellte Assemblys anzuwenden oder Upgrade bei Assemblys auszuführen, wenn Sie neue Funktionen einschließen möchten.

Eine benutzerdefinierte Workflowaktivitäts-Assembly aktualisieren

Wenn Sie Änderungen vornehmen, um Bugs zu beheben oder Code umzugestalten, die zu keinen bedeutenden Änderungen bei öffentlichen Klassen oder Methodensignaturen führen, können Sie die Assembly aktualisieren, sodass alle Prozesse, die ausgeführt werden, automatisch mithilfe der neuen Version der Assembly starten.

So wird eine Assembly aktualisiert:

  1. Ändern Sie nur die Buildnummer und die Revisionswerte in Ihrem AssemblyInfo.cs AssemblyVersion-Attribut. Beispielsweise eine Änderung von 1.0.0.0 zu 1.0.10.5.
  2. Verwenden Sie das Plug-In-Registrierungstool, um die Assembly zu aktualisieren. Weitere Informationen: Aktualisieren einer Assembly

Ein Upgrade bei einer benutzerdefinierten Workflowaktivitäts-Assembly durchführen:

Wenn Sie Änderungen vornehmen, die signifikante Änderungen an öffentlichen Klassen oder Methodensignaturen umfassen, wie das Ändern der Parameter, würden Sie sämtliche aktuell ausgeführten Prozesse unterbrechen, die so definiert sind, dass sie die ursprünglichen Signaturen verwenden. In diesem Fall müssen Sie ein Upgrade an der Assembly ausführen. Dadurch wird eine neue benutzerdefinierte Workflowaktivität erstellt, die Optionen zur Verfügung stellt, die definieren, welche Version im Prozess-Designer anzuwenden ist. So kann jeder Prozess der diese Aktivität benützt, neu konfiguriert werden, um sich an die Änderungen anzupassen, die in der neuen Assembly enthalten sind. Nachdem alle Prozesse, die die ursprüngliche Assembly verwenden, aktualisiert sind, um die aktualisierte Assembly zu verwenden, können Sie die Registrierung der älteren Assembly aufheben.

So wird ein Upgrade an einer Assembly ausgeführt:

  1. Stellen Sie sicher, dass die neue Assembly denselben/dieselbe Name, PublicKeyToken und Culture, wie die vorhandene Assembly hat.

  2. Ändern Sie die Werte Hauptversion und/oder Nebenversion in Ihrem AssemblyInfo.cs AssemblyVersion-Attribut. Beispielsweise eine Änderung 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: Eine Assembly registrieren

  4. Für jeden Prozess, der die benutzerdefinierte Workflowaktivität verwendet, müssen Sie den Prozess deaktivieren und die Schritte bearbeiten, die die benutzerdefinierte Workflowaktivität verwenden.

    Sie finden einen Version-Selektor im Prozess-Designer, mit dem Sie wählen können, welche Version der Assembly verwendet werden soll.

    für den Workflow festgelegte Version

Wenn alle Prozesse konvertiert sind, um die neue Assembly zu verwenden, können Sie das Plug-In-Registrierungstool verwenden, um die Registrierung der Assembly aufzuheben, sodass sie nicht mehr verfügbar ist. Weitere Informationen: Registrierung für Komponenten aufheben

Siehe auch

Bewährte Methoden und Anweisungen zu Workflowentwicklung Plug-In- und Lernprogramm: Erstellen einer Workflow-Erweiterung
Beispiel: Eine benutzerdefinierte Workflowaktivität erstellen
Beispiel: Aktualisieren des nächsten Geburtstags mithilfe einer benutzerdefinierten Workflowaktivität
Beispiel: Berechnen Sie mit einer benutzerdefinierten Workflowaktivität einen Kreditscore