Extensions de workflow

Vous pouvez étendre les options disponibles dans le concepteur de flux de travail utilisé dans Microsoft Dataverse. Ces extensions sont ajoutées en ajoutant un assembly qui contient une classe qui étend la classe CodeActivity . Ces extensions sont couramment appelées assemblys de flux de travail ou activités de flux de travail.

Vous pouvez utiliser ces extensions personnalisées dans le concepteur de flux de travail, les actions personnalisées et les boîtes de dialogue (déconseillées).

Quand créer une extension de flux de travail

Si vous ne trouvez pas les fonctionnalités dont vous avez besoin à l’aide des activités de processus par défaut, vous pouvez ajouter des activités personnalisées afin qu’elles soient disponibles dans l’éditeur utilisé pour composer le flux de travail, la boîte de dialogue et les processus d’action.

Par défaut, ces processus incluent un ensemble commun d’activités que vous pouvez effectuer comme indiqué dans le tableau suivant :

Vous pouvez utiliser l’activité Effectuer une action pour exécuter des actions personnalisées ou les messages système suivants appelés Actions de commande :

Si vous avez des solutions Dynamics 365 Sales ou Service, vous pouvez trouver d’autres actions de commande en fonction de la solution :

Plus d’informations :

• Configurer les étapes de traitement et les phases du flux de travail
• Utiliser des dialogues Dataverse pour les processus guidés
• Créer une action personnalisée

Technologie utilisée

Vous pouvez inscrire un assembly généré à l’aide de la bibliothèque d’activités .NET Framework qui définit des activités personnalisées qui apparaîtront dans l’éditeur d’application web et qui seront appelées lors de l’exécution du processus.

Les activités de flux de travail personnalisées nécessitent la création d’un assembly .NET Framework qui inclut une ou plusieurs classes dérivées de la classe CodeActivity abstraite. Cette classe fournit la méthode Execute(CodeActivityContext) appelée par la plateforme Dataverse lorsque l’activité est exécutée. Chaque classe de votre assembly définit une activité spécifique.

Les activités de flux de travail doivent définir des paramètres d’entrée et de sortie visibles dans le concepteur de processus et permettre à une personne de transmettre des données à l’activité de flux de travail et de recevoir la sortie traitée. Lorsque vous écrivez la classe, vous allez ajouter des propriétés pour ces paramètres et les annoter avec des attributs .NET pour fournir les métadonnées que Dataverse utilisera pour exposer votre activité de flux de travail personnalisée avec tous les paramètres du concepteur.

Créer un assembly d’activité de flux de travail personnalisé

Il s’agit des étapes générales utilisées pour créer une activité de flux de travail personnalisée à l’aide de Visual Studio. Pour obtenir un exemple pas à pas complet, consultez tutoriel : Créer une extension de workflow.

1. Créez un projet de bibliothèque de classes à l’aide de .NET Framework 4.6.2 comme framework cible.

   Important

   Bien que les assemblys générés à l’aide de versions ultérieures fonctionnent généralement, s’ils utilisent des fonctionnalités introduites après la version 4.6.2, une erreur se produit.

2. Installez le package NuGet Microsoft.CrmSdk.Workflow .

   Ce package inclut le package Microsoft.CrmSdk.CoreAssemblies .

3. (Facultatif) Si vous souhaitez utiliser les classes de table à liaison anticipée, incluez-les dans le projet.

   Plus d’informations :

   • Programmation avec liaison tardive et anticipée à l’aide du SDK pour .NET
   • Générer des classes à liaison anticipée pour le SDK pour .NET

4. Ajoutez une classe publique. Le nom de la classe doit correspondre à l’action à effectuer par l’activité.

5. Ajoutez les instructions d’utilisation suivantes.

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

6. Ajoutez des propriétés à la classe pour représenter les paramètres d’entrée ou de sortie et utilisez des attributs .NET pour fournir les métadonnées nécessaires pour exposer ces propriétés au concepteur de processus de flux de travail.

   Plus d’informations : Ajouter des paramètres

7. Faites dériver votre classe de la classe CodeActivity et implémentez la méthode Execute(CodeActivityContext) qui contient les opérations que votre activité effectuera.

   Plus d’informations : Ajouter votre code à la méthode Execute

8. Signez votre assembly.

9. Assemblez votre assembly.

10. Inscrivez votre assembly à l’aide de l’outil d'enregistrement de plug-in et définissez les propriétés Name et WorkflowActivityGroupName pour définir le texte qui sera visible dans le concepteur de flux de travail.

    Pour plus d’informations, voir : Enregistrer votre assembly

11. Tester votre activité de flux de travail en l’appelant à partir d’un flux de travail, d’une boîte de dialogue ou d’un processus d’action

12. (Recommandé) Ajoutez votre activité de flux de travail à une solution.

Ajouter des paramètres

Lorsque vous définissez des paramètres pour votre classe, vous devez les définir en tant que types T InArgument<T>, OutArgument<T> ou InOutArgument<T> . Ces types fournissent des méthodes héritées d’une classe Argument commune pour obtenir ou définir les paramètres. Votre code utilise ces méthodes dans la méthode Execute. Plus d’informations : Ajouter votre code à la méthode Execute

Lorsque votre activité de flux de travail personnalisée utilise des paramètres d’entrée ou de sortie, vous devez ajouter des attributs .NET appropriés aux propriétés de classe publique qui les définissent. Ces données sont lues par le concepteur de processus pour définir la façon dont les paramètres peuvent être définis dans le concepteur de processus.

Vous pouvez utiliser les types de propriétés suivants comme paramètres d’entrée ou de sortie :

Paramètres d’entrée et de sortie

Pour définir le texte à afficher pour un paramètre d’entrée ou de sortie dans le concepteur de processus, vous allez utiliser le modèle suivant à l’aide d’attributs .NET.

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

or

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

Une propriété unique dans votre classe peut être à la fois un paramètre d’entrée et de sortie en incluant les deux attributs :

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

Valeurs requises

Si vous souhaitez rendre un paramètre d’entrée requis lors de l’utilisation de l’activité de flux de travail dans un processus, vous devez utiliser l’attribut [RequiredArgument] .

Valeurs par défaut

Lorsqu’une valeur passée en tant que paramètre d’entrée ou définie en tant que paramètre de sortie n’est pas définie, vous pouvez spécifier une valeur par défaut. Par exemple, pour définir la valeur par défaut d’une propriété bool :

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

Le format de la valeur par défaut dépend du type de propriété. Les exemples se trouvent dans le tableau suivant :

Paramètres de référence d'entité

Lorsque vous définissez une propriété pour un EntityReference paramètre, vous devez utiliser l’attribut ReferenceTarget . Cela définit les types de tables autorisés. Par exemple:

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

Paramètres OptionSetValue

Lorsque vous définissez une propriété pour un OptionSetValue paramètre, vous devez utiliser l’attribut AttributeTarget . Cet attribut définit la table et la colonne qui contiennent l’ensemble valide de valeurs pour le paramètre. Par exemple:

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

Ajouter votre code à la méthode Execute

La logique que vous incluez dans la méthode CodeActivity.Execute(CodeActivityContext) définit ce que fait votre activité de flux de travail.

Paramètres de référence

Pour référencer les paramètres définis pour votre classe, vous allez utiliser les méthodes Argument.Get ou Argument.Set(ActivityContext, Object) qui nécessitent l’instance CodeActivityContext passée à la Execute méthode. L’exemple suivant montre comment accéder à la valeur d’un paramètre d’entrée et définir la valeur d’un paramètre de sortie.

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

Obtenir des informations contextuelles

Lorsque votre code nécessite des informations contextuelles, vous pouvez y accéder à l’aide de la méthode CodeActivityContext.GetExtension<T> avec l’interfaceIWorkflowContext. Cet objet est dérivé de l’interface IExecutionContext , qui fournit l’accès à de nombreuses propriétés en lecture seule qui décrivent le contexte de l’opération. Le IWorkflowContext fournit des informations contextuelles similaires spécifiques au flux de travail en cours d'exécution qui utilise votre assemblage de flux de travail.

Utilisez le code suivant dans votre fonction Execute pour accéder au IWorkflowContext :

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

Utiliser le SDK pour .NET

Lorsque vous devez effectuer des opérations de données à l’aide du Kit de développement logiciel (SDK) pour .NET, vous pouvez y accéder à l’aide de la méthode CodeActivityContext.GetExtension<T> avec l’interface IOrganizationServiceFactory . À partir de là, vous pouvez utiliser la CreateOrganizationService(Nullable<Guid>) méthode pour accéder à une instance du proxy de service que vous pouvez utiliser pour effectuer des opérations de données. Le IWorkflowContext.InitiatingUserId peut être utilisé pour déterminer le contexte utilisateur à utiliser si vous souhaitez que l’opération soit effectuée dans le même contexte que le processus appelant. Utilisez le code suivant dans votre Execute fonction pour accéder au service d’organisation :

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

Enregistrer votre assembly

Vous allez utiliser l'outil d'enregistrement de modules complémentaires (PRT) pour enregistrer des assemblies contenant des activités de flux de travail personnalisées. Il s’agit du même outil que celui que vous utilisez pour inscrire des plug-ins. Pour les plug-ins et les activités de flux de travail personnalisées, vous devez inscrire l’assembly, qui le chargera dans l’environnement. Toutefois, vous n’inscrivez pas les étapes pour les activités de flux de travail personnalisées.

Pour les activités de flux de travail personnalisées, vous devez spécifier les propriétés suivantes pour contrôler ce qui s’affiche dans le concepteur de processus de flux de travail.

** Déboguer des activités de flux de travail

Avec les activités de flux de travail personnalisées déployées sur Dataverse, vous pouvez capturer des profils afin de les rejouer pour le débogage local et utiliser le service de traçage pour écrire des informations dans une table.

L’exemple suivant montre comment utiliser le service de suivi pour écrire le message suivant : 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");
...

Plus d’informations :

• Déboguer des activités de flux de travail
• Utiliser le suivi
• Afficher les journaux de suivi

Ajouter à la solution

Lorsque vous inscrivez des assemblies à l’aide de l’outil d’inscription de plug-in, elles seront ajoutées à la solution par défaut, et ne doivent pas être confondues avec la solution par défaut de Common Data Service. Étant donné que la solution par défaut contient toutes les personnalisations non managées appliquées à l’environnement, avant de pouvoir distribuer votre activité de flux de travail personnalisée à l’aide d’une solution, vous devez l’ajouter à une solution non managée. Par exemple, vous pouvez l’ajouter à la solution Common Data Service Default ou à toute solution non managée que vous avez créée.

Gérer les modifications apportées aux activités de flux de travail personnalisées

Vous devez conserver le code de vos activités de flux de travail personnalisées. Étant donné que les modifications de code peuvent inclure des modifications disruptives, vous devrez gérer ces modifications. Vous allez utiliser différentes étapes pour mettre à jour ou mettre à niveau vos assemblys de flux de travail personnalisés.

Lorsque vous inscrivez un assembly contenant des activités de flux de travail personnalisées, la version de l’assembly est incluse. Ces informations sont extraites par réflexion à partir de l’assembly. Vous pouvez contrôler le numéro de version à l’aide du AssemblyInfo.cs fichier dans votre projet Visual Studio.

Vous trouverez une section en bas qui ressemble à ceci :

// 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")]

Ces informations de version sont importantes, car elles vous permettent d’appliquer des mises à jour aux assemblys déployés ou de mettre à niveau des assemblys lorsque vous souhaitez inclure de nouvelles fonctionnalités.

Mettre à jour un assembly d’activité de flux de travail personnalisé

Lorsque vous apportez des modifications pour corriger des bogues ou du code refacteur qui n’apportent pas de modifications significatives aux classes publiques ou aux signatures de méthode, vous pouvez mettre à jour l’assembly afin que tous les processus en cours d’exécution commencent automatiquement à utiliser la nouvelle version de l’assembly.

Pour mettre à jour un assemblage

1. Modifiez uniquement les valeurs Numéro de build et Révision dans votre AssemblyInfo.csAssemblyVersion attribut. Par exemple, changez de 1.0.0.0 à 1.0.10.5.
2. Utilisez l’outil d’inscription de module d'extension pour mettre à jour l’assemblage. Plus d'informations : Mettre à jour un assemblage

Mettre à niveau un assembly d’activité de flux de travail personnalisé

Si vous apportez des modifications importantes aux classes publiques ou aux signatures de méthode, telles que la modification de paramètres, vous risquez d'interrompre les processus actuellement en cours, qui ont été définis pour utiliser les signatures d'origine. Dans ce cas, vous devez mettre à niveau l'assemblage. Cela crée une activité de flux de travail personnalisée qui expose les options qui définissent la version à appliquer dans le concepteur de processus. Cela permet à chaque processus qui utilise cette activité d’être reconfiguré pour s’adapter aux modifications incluses dans le nouvel assembly. Une fois que tous les processus utilisant l’assembly d’origine sont mis à jour pour utiliser l’assembly mis à niveau, vous pouvez désinscrire l’ancien assembly.

Pour mettre à niveau un assemblage

1. Vérifiez que le nouvel assemblage a le même Name, PublicKeyToken, et Culture que l'assemblage existant.

2. Modifiez les valeurs Version principale et/ou Version mineure dans votre AssemblyInfo.csAssemblyVersion attribut. Par exemple, passez de 1.0.0.0 à 2.0.0.0.

3. Utilisez l’outil d’enregistrement de plug-in pour enregistrer l’assemblage en tant que nouvel assemblage. Plus d’informations : Enregistrer un assemblage

4. Pour chaque processus utilisant l’activité de flux de travail personnalisée, vous devez désactiver le processus et modifier les étapes qui utilisent l’activité de flux de travail personnalisée.

   Vous trouverez un sélecteur de version dans le concepteur de processus que vous pouvez utiliser pour choisir la version de l’assembly à utiliser.

   

Lorsque tous les processus sont convertis pour utiliser le nouvel assembly, vous pouvez utiliser l’outil d’inscription de plug-in pour annuler l’inscription de l’assembly, afin qu’il ne soit plus disponible. Plus d’informations : Annuler l’inscription des composants

Conseils sur les performances

Les considérations relatives aux performances pour vos extensions de flux de travail sont les mêmes que pour les plug-ins ordinaires. Plus d’informations : Analyser les performances du plug-in

Contrairement à un plug-in ordinaire, avec des extensions de flux de travail, vous n’avez pas la possibilité d’inscrire explicitement votre code pour une étape spécifique. Cela signifie que vous ne contrôlez pas si le code de votre extension de workflow s’exécute de manière synchrone ou asynchrone. Une attention particulière doit être prise en compte pour le code qui s’exécute de manière synchrone, car elle aura un impact direct sur l’expérience de l’utilisateur de l’application.

En tant que composants réutilisables, les extensions de flux de travail peuvent être ajoutées à n’importe quel flux de travail ou action personnalisée. Le flux de travail peut être configuré en tant que flux de travail en temps réel , ce qui signifie qu’il s’exécute de manière synchrone. Les actions personnalisées sont toujours synchrones, mais elles ne participent pas à une transaction de base de données, sauf si elles ont activé la restauration définie.

Il est important de savoir que dans un flux de travail synchrone ou une action personnalisée participant à la transaction, toute erreur levée par votre extension de flux de travail entraînera l'annulation de la transaction entière, une opération coûteuse ayant un impact sur les performances.

Vous pouvez utiliser la valeur dans la IWorkflowContextpropriété .WorkflowMode pour déterminer si le flux de travail s’exécute de manière synchrone.

Phases de flux de travail en temps réel

Lorsqu’une extension de flux de travail est utilisée dans un flux de travail en temps réel (synchrone), elle est appelée dans les étapes du pipeline d’exécution d’événements indiquées dans le tableau suivant. Pour plus d’informations : pipeline d’exécution d’événements

Vous pouvez utiliser la valeur dans la propriété IWorkflowContextStageName pour détecter l’étape.

Pour l’opération de mise à jour , l’étape est configurable à l’aide des options Avant ou Après dans le concepteur de flux de travail. Plus d’informations : Utilisation de flux de travail en temps réel

Si votre extension de flux de travail dépend des données transmises dans le contexte d’exécution, la phase dans laquelle elle s’exécute contrôle si les données sont disponibles dans . IWorkflowContextInputParameters et IWorkflowContext.OutputParameters.

Images d’entité pour les extensions de flux de travail

Il n’existe aucun moyen de configurer des images d’entité pour les extensions de flux de travail, car vous inscrivez uniquement l’assembly et l’activité de flux de travail s’exécute dans le contexte du flux de travail. Les images d’entité des extensions de workflow sont disponibles à l’aide des valeurs de clé PreBusinessEntity et PostBusinessEntity, respectivement pour les images d’entité antérieure et postérieure. Plus d’informations : Images d’entité

Voir aussi

Meilleures pratiques et conseils concernant le didacticiel de développement de plug-in et de flux de travail: Créer une extension de flux de travail
Exemple : créer une activité de workflow personnalisée
Exemple : mettre à jour l’anniversaire suivant à l’aide d’une activité de workflow personnalisée
Exemple : calculer un score de crédit avec une activité de workflow personnalisée