Extensions de workflow

Vous pouvez étendre les options disponibles dans le concepteur de flux de travail utilisé dans Microsoft Dataverse. Ajoutez ces extensions 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, ajoutez 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 :

Utilisez 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 :

Pour en savoir plus, consultez :

• 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. Ces activités apparaissent dans l’éditeur d’application web et sont 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) que la plateforme Dataverse appelle lors de l’exécution de l’activité. 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. Ces paramètres permettent à 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, ajoutez des propriétés pour ces paramètres et annotez-les avec des attributs .NET pour fournir les métadonnées que Dataverse utilise 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é

Ces étapes décrivent comment 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 flux de travail.

1. Créez un projet de bibliothèque de classes qui cible .NET Framework 4.6.2.

   Important

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

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.

   Pour en savoir plus, consultez :

   • 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 effectuée par l’activité.

5. Ajoutez les directives using 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. 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.

   Pour plus d’informations, consultez 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 effectuées par votre activité.

   Pour plus d’informations, consultez 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. Définissez les propriétés Name et WorkflowActivityGroupName pour définir le texte affiché par le concepteur de flux de travail.

    Pour plus d’informations, consultez Inscrire votre assembly.

11. Testez 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, définissez-les en tant que types T InArgument<T>, OutArgument<T> ou InOutArgument<T> . Ces types fournissent des méthodes héritées d’une classe d’arguments commune pour obtenir ou définir les paramètres. Votre code utilise ces méthodes dans la Execute méthode. Pour plus d’informations, consultez 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, ajoutez les attributs .NET appropriés aux propriétés de classe publique qui les définissent. Le concepteur de processus lit ces données 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, 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 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

Pour rendre un paramètre d’entrée requis lors de l’utilisation de l’activité de flux de travail dans un processus, utilisez l’attribut [RequiredArgument] .

Valeurs par défaut

Lorsque vous passez une valeur en tant que paramètre d’entrée ou définissez un paramètre de sortie sans définir la valeur, spécifiez une valeur par défaut. Par exemple, le code suivant définit 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, utilisez l’attribut ReferenceTarget . Cet attribut établit le type de table autorisé. 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, utilisez 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 que vous définissez pour votre classe, utilisez les méthodes Argument.Get ou Argument.Set(ActivityContext, Object). Ces méthodes 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, accédez-y à 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. L’élément 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, accédez-y à l’aide de la méthode CodeActivityContext.GetExtension<T> avec l’interface IOrganizationServiceFactory . À partir de là, utilisez 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. La IWorkflowContextpropriété .InitiatingUserId peut être utilisée 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

Utilisez l’outil d'enregistrement de plug-in (PRT) pour enregistrer des assemblies qui contiennent des activités de flux de travail personnalisées. Cet outil est le même que celui que vous utilisez pour inscrire des plug-ins. Pour les plug-ins et les activités de workflow personnalisées, vous devez inscrire l’assembly pour le charger 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, spécifiez les propriétés suivantes pour contrôler ce que le concepteur de processus de flux de travail affiche.

Déboguer les activités du flux de travail

Lorsque vous déployez des activités de flux de travail personnalisées sur Dataverse, vous pouvez capturer des profils pour relire le débogage local et utiliser le service de suivi pour écrire des informations dans une table.

L’exemple suivant montre comment utiliser le service de suivi pour écrire le message : 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 en savoir plus, consultez :

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

Ajouter à la solution

Lorsque vous inscrivez des assemblys à l’aide de l’outil d’inscription de plug-in, vous les ajoutez à la solution par défaut. Ne confondez pas cette solution avec la solution Common Data Service Default. É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 gérer le code de vos activités de flux de travail personnalisées. Étant donné que les modifications de code peuvent inclure des changements qui causent des ruptures, vous devez gérer ces modifications. Utilisez 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. L’outil d’enregistrement extrait ces informations en utilisant la réflexion 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 corrigez des bogues ou du code refactorisé sans apporter de modifications significatives aux classes publiques ou aux signatures de méthode, mettez à 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 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. Pour plus d’informations, consultez 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 des paramètres, vous interrompez les processus en cours d’exécution définis pour utiliser les signatures d’origine. Dans ce cas, vous devez mettre à niveau l'assemblage. Cette action crée une activité de flux de travail personnalisée qui expose les options permettant de définir la version à appliquer dans le concepteur de processus. Ce contrôle de version permet à chaque processus d’utiliser 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, changez 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. Pour plus d’informations, consultez Inscrire un assembly.

4. Pour chaque processus utilisant l’activité de flux de travail personnalisée, désactivez le processus et modifiez les étapes qui utilisent l’activité de flux de travail personnalisée.

   Vous trouvez 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, utilisez l’outil d’inscription de plug-in pour annuler l’inscription de l’assembly, afin qu’il ne soit plus disponible. Pour plus d’informations, consultez Annuler l’inscription des composants.

Guide de performances

Les considérations relatives aux performances pour vos extensions de flux de travail sont les mêmes que pour les plug-ins ordinaires. Pour plus d’informations, consultez Analyser les performances des plug-ins.

Contrairement à un plug-in ordinaire, les extensions de flux de travail ne fournissent pas la possibilité d’inscrire explicitement votre code pour une étape spécifique. Vous ne contrôlez pas si le code de votre extension de workflow s’exécute de manière synchrone ou asynchrone. Le code qui s’exécute de manière synchrone nécessite une attention particulière, car il affecte directement l’expérience de l’utilisateur de l’application.

En tant que composants réutilisables, vous pouvez ajouter des extensions de flux de travail à n’importe quel flux de travail ou action personnalisée. Vous pouvez configurer le flux de travail 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 vous définissez Activer la restauration.

N’oubliez pas que dans un flux de travail synchrone ou une action personnalisée qui participe à la transaction, toute erreur levée par votre extension de workflow entraîne l’annulation de l’intégralité de la transaction. Cette annulation est une opération coûteuse qui peut avoir un impact sur les performances.

Utilisez 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

Lorsque vous utilisez une extension de flux de travail dans un flux de travail en temps réel (synchrone), le pipeline d’exécution d’événements appelle l’extension à des étapes spécifiques. Le tableau suivant présente ces étapes. Pour plus d’informations, consultez le pipeline d’exécution d’événements.

Utilisez la valeur dans la propriété IWorkflowContext.StageName pour détecter l’étape.

Pour l’opération de mise à jour , vous pouvez configurer l’étape à l’aide des options Avant ou Après dans le concepteur de flux de travail. Pour plus d’informations, consultez 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, l’étape à laquelle elle s'exécute détermine si les données sont disponibles dans IWorkflowContext.InputParameters et IWorkflowContext.OutputParameters.

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

Vous ne pouvez pas configurer d’images d’entité pour les extensions de flux de travail. Vous enregistrez uniquement l’assembly, et l’activité de workflow s’exécute dans son contexte. 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, consultez Images d’entité.

Voir aussi

Meilleures pratiques et directives concernant le développement de plug-ins et de workflows
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