Présentation du contexte d’exécution
Le Pipeline d’exécution des événements passe aux plug-ins enregistrés une grande quantité de données sur l’opération en cours étant traitée et l’environnement de l’exécution du code personnalisé. Les sections suivantes décrivent les données transmises à votre plug-in ou à votre activité de workflow personnalisé.
Pour les plug-ins
Avec les plug-ins, vous pouvez accéder à ces données dans votre code de plug-in en définissant une variable qui implémente l’interface IPluginExecutionContext :
// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
IPluginExecutionContext fournit des informations sur Stage dont le plug-in est enregistré, ainsi que des informations sur ParentContext.
Pour plus d’informations, consultez ParentContext
Pour les activités de workflow personnalisées
Avec les activités de workflow personnalisées, vous pouvez accéder à ces données dans votre code de plug-in en définissant une variable qui implémente l’interface IWorkflowContext :
// Obtain the execution context using the GetExtension method.
protected override void Execute(CodeActivityContext context)
{
IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...
IWorkflowContext fournit des informations sur le workflow dans lequel l’activité de workflow personnalisée s’exécute.
| Propriété | Description |
|---|---|
| ParentContext | Obtient le contexte parent. Voir ParentContext |
| StageName | Obtient les informations de la phase de l’instance de processus. |
| WorkflowCategory | Obtient les informations de processus de catégories de l’instance de processus : workflow ou boîte de dialogue (obsolète). |
| WorkflowMode | Indique comment le workflow doit être exécuté. 0 = asynchrone, 1 = synchrone |
ParentContext
ParentContext fournit des informations sur une opération qui déclenche l’exécution du plug-in ou l’activité de workflow personnalisée.
Sauf pour des cas documentés spécifiques, vous devriez éviter de prendre une dépendance à des valeurs que vous trouvez dans ParentContext pour appliquer votre logique métier. L’ordre spécifique dans lequel les opérations se produisent n’est pas garanti et peut évoluer sur la durée.
Si vous décidez de créer une dépendance sur les valeurs disponibles dans ParentContext, vous devez veiller à ce que votre code soit résilient pour s’adapter aux modifications potentielles. Vous devez tester régulièrement la logique pour vérifier que les conditions dont vous dépendez demeurent en vigueur dans le temps.
ExecutionContext
Le reste des informations disponibles est fourni par l’interface IExecutionContext que les classes IPluginExecutionContext et IWorkflowContext implémentent.
Pour les plug-ins, toutes les propriétés de ce contexte d’exécution fournissent des informations utiles pour accéder à votre code.
Notes
Pour les activités de workflow personnalisées, ces propriétés ne sont pas généralement utilisées.
Les deux propriétés les plus importantes sont les suivantes : InputParameters et OutputParameters.
D’autres propriétés souvent utilisées sont SharedVariables, PreEntityImages et PostEntityImages.
Conseil
Pour visualiser les données transmises au contexte d’exécution, installez la solution Profileur de plug-in qui est disponible dans le cadre de l’outil Plug-in Registration Tool. Le profileur capture les informations de contexte ainsi que les informations permettant de relire l’événement localement pour le débogage. Dans l’outil Plug-in Registration Tool, vous pouvez télécharger un document XML avec toutes les données de l’événement qui a déclenché le workflow. Pour plus d’informations, voir : Afficher les données de profil du plug-in
ParameterCollections
Toutes les propriétés du contexte d’exécution sont en lecture seule. Mais les collections InputParameters, OutputParameters et SharedVariables sont des valeurs ParameterCollection. Vous pouvez manipuler les valeurs des éléments dans ces collections pour modifier le comportement de l’opération, selon la phase du pipeline d’exécution des événements pour laquelle votre plug-in est enregistré.
Les valeurs ParameterCollection sont définies comme des structures KeyValuePair. Pour accéder à une propriété, vous devez connaître le nom de la propriété exposée par le message. Par exemple, pour accéder à la propriété Entity qui est transmise dans le cadre de CreateRequest, vous devez savoir que le nom de cette propriété est Target. Vous pouvez ensuite accéder à cette valeur en utilisant le code suivant :
var entity = (Entity)context.InputParameters["Target"];
Utilisez la documentation Microsoft.Xrm.Sdk.Messages et Microsoft.Crm.Sdk.Messages pour connaître les noms des messages définis dans les assemblys SDK. Pour des actions personnalisées, reportez-vous aux noms des paramètres définis dans le système.
InputParameters
La collection InputParameters représente la valeur de la propriété OrganizationRequest.Parameters qui représente l’opération provenant des services Web.
Comme décrit dans la rubrique Utiliser des messages avec le SDK pour .NET, toutes les opérations qui se produisent dans le système sont des instances de la classe OrganizationRequest traitée par la méthode IOrganizationService.Execute .
Comme décrit dans la rubrique Infrastructure d’événements, les opérations passent par une série de phases et vous pouvez enregistrer votre plug-in dans les phases qui se produisent avant que les données soient écrites dans la base de données. Dans les phases PreValidation et PreOperation, vous pouvez lire et modifier les valeurs de la collection InputParameters afin de pouvoir contrôler les résultats attendus de l’opération de données.
Si vous trouvez que les valeurs de la collection InputParameters représentent une condition que vous ne pouvez pas autoriser, vous pouvez lever une exception InvalidPluginExecutionException (de préférence pendant la phase PreValidation) qui annule l’opération et affiche une erreur à l’utilisateur pour un plug-in synchrone, ou consigne l’erreur si le plug-in est asynchrone. Pour plus d’informations, voir : Annulation d’une opération
OutputParameters
La collection OutputParameters représente la valeur de la propriété OrganizationResponse.Results qui représente la valeur retournée par l’opération. Chacune des classes de réponse de messages dérivées de OrganizationResponse contient des propriétés spécifiques. Pour accéder à ces propriétés vous devez utiliser la valeur principale qui est généralement les mêmes que le nom les propriétés dans la classe de réponse. Toutefois, ce n’est pas toujours vrai. Le tableau suivant répertorie les propriétés de classe de réponse de message qui ont des clés différentes du nom des propriétés.
La collection OutputParameters n’est renseignée qu’après la transaction de base de données, elle n’est donc disponible que pour les plug-ins enregistrés dans la phase PostOperation. Pour modifier les valeurs retournées par l’opération, vous pouvez le faire dans la collection OutputParameters.
Variables partagées
La propriété SharedVariables permet d’inclure des données qui peuvent être transmises de l’API ou d’un plug-in à une étape qui se produit plus tard dans le pipeline d’exécution. Comme il s’agit d’une valeur ParameterCollection, les plug-ins peuvent ajouter, lire ou modifier des propriétés pour partager des données avec les étapes suivantes.
L’exemple suivant décrit comment une valeur PrimaryContact peut être transmise d’un plug-in enregistré pour une étape PreOperation à une étape PostOperation.
public class PreOperation : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));
// Create or retrieve some data that will be needed by the post event
// plug-in. You could run a query, create an entity, or perform a calculation.
//In this sample, the data to be passed to the post plug-in is
// represented by a GUID.
Guid contact = new Guid("{74882D5C-381A-4863-A5B9-B8604615C2D0}");
// Pass the data to the post event plug-in in an execution context shared
// variable named PrimaryContact.
context.SharedVariables.Add("PrimaryContact", (Object)contact.ToString());
}
}
public class PostOperation : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));
// Obtain the contact from the execution context shared variables.
if (context.SharedVariables.Contains("PrimaryContact"))
{
Guid contact =
new Guid((string)context.SharedVariables["PrimaryContact"]);
// Do something with the contact.
}
}
}
Important
Tous les types de données ajoutés à la collection de variables partagées doivent être sérialisées sinon le serveur ne sait pas comment sérialiser les données et l’exécution du plug-in échoue.
Notes
Pour un plug-in inscrit pour les phases PreOperation ou PostOperation afin d’accéder aux variables partagées à partir d’un plug-in inscrit pour la phase PreValidation qui s’exécute lors des opérations Create, Update et Delete, ou via RetrieveExchangeRateRequest, vous devez accéder à la collection ParentContext.SharedVariables. Pour tous les autres incidents, IPluginExecutionContext.SharedVariables contient la collection.
Transmission d’une variable partagée depuis l’API
Si vous devez introduire une variable partagée lorsque vous appelez une API, utilisez le mot-clé tag soit depuis l’API web, soit depuis le SDK pour .NET pour transmettre une valeur de chaîne.
Cette valeur est accessible dans la collection de variables partagées à l’aide du mot-clé tag. Une fois définie, cette valeur ne peut pas être modifiée, elle est immuable.
Plus d’informations : Ajouter une variable partagée au contexte d’exécution du plug-in.
Images d’entité
Lorsque vous enregistrez une étape pour un plug-in qui comprend une table parmi ses paramètres, vous avez la possibilité de préciser qu’une copie des données de la table soit incluse comme capture d’écran ou image à l’aide des propriétés PreEntityImages et/ou PostEntityImages.
Ces données offrent un point de comparaison pour les données de la table puisqu’elles traversent le pipeline d’événements. L’utilisation de ces images offre de meilleures performances qu’en incluant du code dans un plug-in pour récupérer une table pour comparer les valeurs d’attribut.
Lorsque vous définissez une image d’entité, vous spécifiez une valeur d’alias d’entité que vous pouvez utiliser pour accéder à l’image spécifique. Par exemple, si vous définissez une image pré-entité avec l’alias a, vous pouvez utiliser le code suivant pour accéder à la valeur d’attribut name.
var oldAccountName = (string)context.PreEntityImages["a"]["name"];
Pour plus d’informations :
Voir aussi
Infrastructure d’événements
Écrire un plug-in
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