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é).
Important
Le cas échéant, envisagez d’appliquer une des options déclaratives pour définir la logique métier. Pour plus d’informations, consultez : Appliquer la logique métier dans Dataverse
Utilisez des extensions de workflow lorsqu’un processus déclaratif ne répond pas à vos besoins.
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 :
| Activité | Workflow | Action | Dialogue |
|---|---|---|---|
| Rechercher des données | X | ||
| Attribuer une valeur | X | X | |
| Créer l’enregistrement | X | X | X |
| Mettre à jour l’enregistrement | X | X | X |
| Attribuer l’enregistrement | X | X | X |
| Envoyer un courrier électronique | X | X | X |
| Lancer le workflow enfant | X | X | X |
| Exécuter l’action | X | X | |
| Lier le dialogue enfant | X | ||
| Modifier le statut | X | X | X |
| Arrêter le workflow | X | X | |
| Arrêter le dialogue | X |
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 :
| Actions | Actions (suite) | Actions (suite) |
|---|---|---|
| AddToQueue | AddUserToRecordTeam | RemoveUserFromRecordTeam |
| SetProcess | SetWordTemplate |
Si vous disposez des solutions Dynamics 365 Sales ou Service, d’autres actions de commande sont disponibles selon la solution :
| Actions | Actions (suite) | Actions (suite) |
|---|---|---|
| ApplyRoutingRule | CalculateActualValue | CloseOpportunity |
| GetQuoteProductsFromOpportunity | GetSalesOrderProductsFromOpportunity | LockInvoicePricing |
| LockSalesOrderPricing | QualifyLead | RemoveUserFromRecordTeam |
| ResolveIncident | ResolveQuote | Réviser |
| UnlockInvoicePricing | UnlockSalesOrderPricing |
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 .
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.
Installez le package NuGet Microsoft.CrmSdk.Workflow.
Ce package comprend le package Microsoft.CrmSdk.CoreAssemblies.
(Facultatif) Si vous souhaitez utiliser les classes de table à liaison anticipée, incluez-les dans le projet.
Pour plus d’informations :
Ajoutez une classe publique. Le nom de la classe doit correspondre à l’action qui doit être exécutée par l’activité.
Ajoutez les instructions d’utilisation suivantes.
using System.Activities; using Microsoft.Xrm.Sdk; using Microsoft.Xrm.Sdk.Workflow;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
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
Signez votre assembly.
Générez votre assembly.
Enregistrez votre assembly à l’aide de Plug-in Registration Tool et configurez les propriétés
NameetWorkflowActivityGroupNamepour définir le texte qui est visible dans le concepteur de workflow.Pour plus d’informations, voir : Enregistrer votre assembly
Tester votre activité de workflow en l’appelant à partir d’un processus de workflow, de dialogue ou d’action
(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 :
| Propriétés | Propriétés (suite) | Propriétés (suite) |
|---|---|---|
| bool | Date/Heure | Décimal |
| Double | EntityReference | int |
| Money | OptionSetValue | string |
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 :
| Type | Exemple |
|---|---|
| bool | [Default("True")] |
| Date/Heure | [Default("2004-07-09T02:54:00Z")] |
| Décimal | [Default("23.45")] |
| Double | [Default("23.45")] |
| Money | [Default("23.45")] |
| EntityReference | [Default("3B036E3E-94F9-DE11-B508-00155DBA2902", "account")] |
| int | [Default("23")] |
| OptionSetValue | [Default("3")] |
| string | [Default("string default")] |
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.
Important
Le code de la méthode Execute doit être inscrit comme sans état. Il est déconseillé d’utiliser des variables globales ou de membre pour transmettre des données d’un appel à l’autre.
Pour améliorer les performances, Dataverse met en cache les instances d’activité de workflow personnalisées. Ainsi, le constructeur n’est pas appelé pour chaque appel de l’activité de workflow personnalisée. En outre, plusieurs threads système peuvent exécuter l’activité de workflow personnalisée simultanément. Vous devez uniquement utiliser les informations transmises via le paramètre CodeActivityContext à la méthode Execute.
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>();
...
Important
Vous ne devez inclure aucune dépendance de logique en fonction des informations de contexte. Lorsque votre activité de workflow personnalisée est utilisée dans un workflow, tous les paramètres d’entrée appropriés doivent être définis dans le concepteur. La valeur de sortie ou le comportement de l’activité personnalisée doit toujours être déterminée uniquement par les paramètres d’entrée afin qu’il n’existe aucun facteur masqué qui modifie le comportement. Lorsqu’un utilisateur utilise l’activité personnalisée dans le concepteur, le comportement doit toujours être prévisible.
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.
| Champ | Description |
|---|---|
Description |
Non visible dans l’interface utilisateur du concepteur de processus, mais peut être utile pour générer la documentation à partir des données issues de la table PluginType qui stocke ces informations. |
FriendlyName |
Nom de plug-in convivial. |
Name |
Nom du menu représenté |
WorkflowActivityGroupName |
Nom du sous-menu ajouté au menu principal du concepteur de procédure Dataverse. |
Notes
Ces valeurs ne seront pas visibles dans la solution non gérée lorsque vous testez votre activité de workflow. Cependant, lorsque vous exportez une solution gérée incluant cette activité de workflow, ces valeurs seront visibles dans le concepteur de processus.
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 :
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
- Modifiez uniquement le Numéro de version et les Valeurs de révision dans votre attribut
AssemblyInfo.csAssemblyVersion. Par exemple, remplacez1.0.0.0par1.0.10.5. - 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
Vérifiez que le nouvel assembly a les mêmes
Name,PublicKeyTokenetCultureque l’assembly existant.Modifiez les valeurs Version principale et/ou Version secondaire dans votre attribut
AssemblyInfo.csAssemblyVersion. Par exemple, remplacez1.0.0.0par2.0.0.0.Utilisez Plug-in Registration Tool pour enregistrer l’assembly comme nouvel assembly. Pour plus d’informations, voir : Enregistrer un assembly
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.
Important
Lorsque votre extension de workflow est utilisée dans un workflow synchrone ou une action personnalisée, le temps passé à exécuter le code a une incidence directe sur l’expérience de l’utilisateur. Pour cette raison, les extensions de workflow ne doivent pas nécessiter plus de deux secondes pour s’effectuer lorsqu’elles sont utilisées de manière synchrone. Si votre extension nécessite plus de temps que cela, vous devez la documenter et décourager son utilisation dans des workflows synchrones ou des actions personnalisées.
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
| Message | Étape |
|---|---|
| Créer | PostOperation |
| Supprimer | Opération préalable |
| Update | PreOperation ou PostOperation |
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
Notes
Nous ne recommandons pas d’inclure des dépendances de logique en fonction de OutputParameters et InputParameters. Les extensions de workflow doivent dépendre des paramètres d’entrée et de sortie configurés pour que la personne utilisant l’extension de workflow puisse comprendre le comportement attendu sans rien cacher.
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
Notes
Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)
Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour