Extensions de workflow

Vous pouvez étendre les options disponibles dans le concepteur de workflows utilisé dans Microsoft Dataverse. Ces extensions sont ajoutées en ajoutant un assembly contenant une classe qui étend la classe CodeActivity. Ces extensions sont généralement appelées des assemblys de workflow ou des activités de workflow.

Vous pouvez utiliser ces extensions personnalisées dans le concepteur de workflows, les actions personnalisées et les dialogues (déconseillé).

Quand créer une extension de workflow

Si vous ne trouvez pas la fonctionnalité dont vous avez besoin en utilisant les activités de processus par défaut, vous pouvez ajouter des activités personnalisées pour qu’elles soient disponibles dans l’éditeur utilisé pour composer des processus de workflow, de dialogue et d’action.

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

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

Si vous disposez des solutions Dynamics 365 Sales ou Service, d’autres actions de commande sont disponibles selon la solution :

Pour plus d’informations :

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

Technologie utilisée

Vous pouvez enregistrer un assembly créé à l’aide de la bibliothèque d’activités .NET Framework qui définit les activités personnalisées qui s’affichent dans l’éditeur de l’application Web et qui sont appelées pendant l’exécution du processus.

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

Les activités de workflow doivent également définir des paramètres d’entrée et de sortie qui sont visibles dans le concepteur de processus et qui permettent à un utilisateur de transmettre des données dans l’activité de workflow et de recevoir la sortie traitée. Lorsque vous écrivez la classe, vous ajoutez des propriétés pour ces paramètres et les annotez avec les attributs .NET pour fournir les métadonnées que Dataverse utilise pour exposer votre activité de workflow personnalisée avec les paramètres dans le concepteur.

Créer un assembly d’activité de workflow personnalisée

Voici les étapes générales utilisées pour créer une activité de workflow personnalisée à l’aide de Visual Studio. Pour un exemple pas à pas complet, voir Didacticiel : Créer une extension de workflow .

1. Créez un projet Bibliothèque de classes en utilisant .NET Framework 4.6.2 comme structure cible.

   Important

   Bien que les assemblys créés à l’aide de versions ultérieures devraient généralement fonctionner, s’ils utilisent une fonctionnalité introduite après la version 4.6.2, une erreur se produira.

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

   Ce package comprend le package Microsoft.CrmSdk.CoreAssemblies.

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

   Pour 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 qui doit être exécutée 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 les attributs .NET pour fournir les métadonnées nécessaires pour exposer ces propriétés au concepteur de processus de workflow.

   Pour plus d’informations, voir : Ajouter des paramètres

7. Faites dériver votre classe de la classe CodeActivity et mettez en œuvre la méthode Execute(CodeActivityContext) qui contient les opérations qui seront exécutées par votre activité.

   Pour plus d’informations, voir : Ajouter votre code à la méthode Execute

8. Signez votre assembly.

9. Générez votre assembly.

10. Enregistrez votre assembly à l’aide de Plug-in Registration Tool et configurez les propriétés Name et WorkflowActivityGroupName pour définir le texte qui est visible dans le concepteur de workflow.

    Pour plus d’informations, voir : Enregistrer votre assembly

11. Tester votre activité de workflow en l’appelant à partir d’un processus de workflow, de dialogue ou d’action

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

Ajouter des paramètres

Lorsque vous définissez des paramètres pour votre classe, vous devez les définir comme types 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 Exécute. Pour plus d’informations, voir : Ajouter votre code à la méthode Execute

Lorsque votre activité de workflow 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 publiques qui les définissent. Ces données sont lues par le concepteur de processus pour définir la manière dont les paramètres peuvent être définis dans le concepteur de processus.

Vous pouvez utiliser les types suivants de propriétés 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, utilisez le modèle suivant avec les attributs .NET.

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

or

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

Une seule propriété de 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

Pour rendre un paramètre d’entrée ou de sortie obligatoire lorsque vous utilisez l’activité de workflow dans un processus, vous devez utiliser l’attribut [RequiredArgument].

Valeurs par défaut

Lorsqu’une valeur transmise comme paramètre d’entrée ou configurée comme 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é. Le tableau suivant présente des exemples :

Paramètres d’EntityReference

Lorsque vous définissez une propriété pour un paramètre EntityReference, vous devez utiliser l’attribut ReferenceTarget. Cet attribut définit le type de table autorisé. Par exemple :

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

Paramètres d’OptionSetValue

Lorsque vous définissez une propriété pour un paramètre OptionSetValue, vous devez utiliser l’attribut AttributeTarget. Cet attribut définit la table et la colonne contenant l’ensemble de valeurs valides 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 le rôle de votre activité de workflow.

Paramètres de référence

Pour référencer les paramètres définis pour votre classe, utilisez les méthodes Argument.Get ou Argument.Set(ActivityContext, Object) fournies qui nécessitent l’instance CodeActivityContext transmise à la méthode Execute. L’exemple suivant décrit l’accès à la valeur d’un paramètre d’entrée et la définition de 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 les 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’interface IWorkflowContext. Cet objet est dérivé de l’interface IExecutionContext, qui donne accès à plusieurs propriétés en lecture seule qui décrivent le contexte de l’opération. La méthode IWorkflowContext fournit des informations contextuelles similaires qui sont spécifiques au workflow d’exécution qui utilise votre assembly de workflow.

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

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

Utiliser le SDK pour .NET

Lorsque vous devez exécuter des opérations de données à l’aide du SDK pour .NET, vous pouvez y accéder en utilisant la méthode CodeActivityContext.GetExtension<T> avec l’interface IOrganizationServiceFactory. Vous pouvez ensuite utiliser la méthode CreateOrganizationService(Nullable<Guid>) pour accéder à une instance du proxy du service pour exécuter des opérations de données. La méthode IWorkflowContext.InitiatingUserId peut être utilisée pour déterminer le contexte utilisateur à utiliser si vous souhaitez que l’opération soit exécutée dans le même contexte que le processus appelant. Utilisez le code suivant dans votre fonction Execute pour obtenir un accès au service 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 utilisez Plug-in Registration Tool (PRT) pour enregistrer des assemblys contenant des activités de workflow personnalisées. Il s’agit du même outil que celui utilisé pour enregistrer des plug-ins. Pour les plug-ins et les activités de workflow personnalisées, vous devez enregistrer l’assembly, qui les télécharge dans votre environnement. Toutefois, vous n’enregistrez pas les étapes des activités de workflow personnalisées.

Pour les activités de workflow personnalisées, vous devez spécifier les propriétés suivantes pour contrôler les éléments affichés dans le concepteur de processus de workflow.

Déboguer des activités de workflow

Avec les activités de workflow personnalisées déployées dans Dataverse, vous pouvez capturer des profils à relire pour le débogage local et utiliser le service de suivi pour entrer des informations dans une table.

L’exemple suivant illustre l’utilisation du 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");
...

Pour plus d’informations :

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

Ajouter une activité à la solution

Lorsque vous enregistrez des assemblys à l’aide de Plug-in Registration Tool, ceux-ci sont ajoutés à la Solution par défaut, à ne pas confondre avec la Solution par défaut Common Data Service. Comme la Solution par défaut contient toutes les personnalisations non gérées appliquées à l’environnement, avant de pouvoir distribuer votre activité de workflow personnalisée à l’aide d’une solution, vous devez l’ajouter à une solution non gérée. Par exemple, vous pouvez l’ajouter à la Solution par défaut Common Data Service ou à toute solution non gérée que vous avez créée.

Gérer les modifications des activités de workflow personnalisées

Vous devez gérer le code de vos activités de workflow personnalisées. Comme les modifications du code peuvent inclure des modifications de dernière minute, vous devez gérer ces modifications. Vous utilisez différentes étapes pour mettre à jour ou mettre à niveau vos assemblys de workflow personnalisées.

Lorsque vous enregistrez un assembly contenant des activités de workflow 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 fichier AssemblyInfo.cs dans votre projet Visual Studio.

Vous trouverez une section en bas qui se présente comme suit :

// 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 workflow personnalisée

Lorsque vous effectuez des modifications pour corriger des bogues ou refactoriser le code qui n’entraînent pas de changements importants des classes publiques ou des signatures de méthode, vous pouvez mettre à jour l’assembly afin que tous les processus en cours d’exécution démarrent automatiquement à l’aide de la nouvelle version de l’assembly.

Pour mettre à jour un assembly

1. Modifiez uniquement le Numéro de version et les Valeurs de révision dans votre attribut AssemblyInfo.cs AssemblyVersion. Par exemple, remplacez 1.0.0.0 par 1.0.10.5.
2. Utilisez Plug-in Registration Tool pour mettre à jour l’assembly. Pour plus d’informations, voir : Mettre à jour un assembly

Mettre à niveau un assembly d’activité de workflow personnalisée

Si vos modifications comprennent des changements importants des classes publiques ou des signatures de méthode, comme la modification des paramètres, vous risquez d’interrompre les processus en cours d’exécution définis pour utiliser les signatures d’origine. Dans ce cas, vous devez mettre à niveau l’assembly. Cela crée une nouvelle activité de workflow personnalisée qui expose des options définissant la version à appliquer dans le concepteur de processus. Cela permet de reconfigurer chaque processus qui utilise cette activité pour l’adapter aux modifications incluses dans le nouvel assembly. Une fois que tous les processus qui utilisent l’assembly d’origine sont mis à jour pour utiliser l’assembly mis à niveau, vous pouvez annuler l’enregistrement de l’ancien assembly.

Pour mettre à niveau un assembly

1. Vérifiez que le nouvel assembly a les mêmes Name, PublicKeyToken et Culture que l’assembly existant.

2. Modifiez les valeurs Version principale et/ou Version secondaire dans votre attribut AssemblyInfo.cs AssemblyVersion. Par exemple, remplacez 1.0.0.0 par 2.0.0.0.

3. Utilisez Plug-in Registration Tool pour enregistrer l’assembly comme nouvel assembly. Pour plus d’informations, voir : Enregistrer un assembly

4. Pour chaque processus qui utilise l’activité de workflow personnalisée, vous devez désactiver les processus et modifier les étapes qui utilisent l’activité de workflow personnalisée.

   Vous trouverez un sélecteur de Version dans le concepteur de processus qui vous permet de choisir la version de l’assembly à utiliser.

   

Lorsque tous les processus sont convertis pour utiliser le nouvel assembly, vous pouvez utiliser Plug-in Registration Tool pour annuler l’enregistrement de l’assembly, afin qu’il ne soit plus disponible. Pour plus d’informations, voir : Annuler l’enregistrement des composants

Guide de performances

Les considérations de performances pour les extensions de workflow sont les mêmes que pour les connexions ordinaires. Pour plus d’informations : Analyser les performances des plug-ins

Contrairement aux plug-ins ordinaires, avec les extensions de workflow, vous n’avez pas la possibilité d’enregistrer explicitement votre code pour une étape spécifique. Cela signifie que vous ne contrôlez pas si le code dans votre extension de workflow s’exécutera de manière synchrone ou asynchrone. Un soin particulier doit être pris en compte pour le code qui s’exécute de manière synchrone, car cela aura un impact direct sur l’expérience de l’utilisateur de l’application.

En tant que composants réutilisables, les extensions de workflow peuvent être ajoutées à n’importe quel action de workflow ou personnalisées. Le workflow peut être configuré pour le workflow temps réel, ce qui signifie qu’il s’exécutera de manière synchrone. Les actions personnalisées sont toujours synchrones, mais elles ne participent à une transaction de base de données que si elles sont définies sur Activer la restauration.

Vous devez également savoir que, dans un workflow synchrone ou une action personnalisée faisant partie de la transaction, toute erreur générée par l’extension de votre workflow entraîne l’annulation de la transaction dans son intégralité, ce qui représente une opération coûteuse pouvant affecter les performances.

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

Phases de workflow en temps réel

Lorsqu’une extension de workflow est utilisée dans un workflow en temps réel (synchrone), elle est invoquée dans les étapes du pipeline d’exécution d’événements présentées dans le tableau suivant. Pour plus d’informations : Pipeline d’exécution des événements

Vous pouvez utiliser la valeur dans la propriété IWorkflowContext.StageName pour détecter la phase.

Pour l’opération Mettre à jour, la phase est configurable à l’aide des options Avant ou Après configurables dans le concepteur de workflow. Pour plus d’informations : Utilisation de workflows en temps réel.

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

Images d’entités pour les extensions de workflow

Il n’existe aucun moyen de configurer des images d’entité pour les extensions de workflow car vous stockez uniquement l’assembly et l’activité de workflow fonctionne dans le contexte du workflow. 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. Pour plus d’informations : Images d’entité

Voir aussi

Meilleures pratiques et conseils concernant le développement de plug-in et de workflow Didacticiel : Créer une extension de workflow
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