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é.

Accéder au contexte d'exécution pour les plug-ins

Avec les plug-ins, accédez à ces données dans votre code 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));

Cela IPluginExecutionContext fournit des informations sur le Stage pour lequel le plug-in est enregistré, ainsi que des informations sur le ParentContext.

Pour plus d’informations, consultez ParentContext

Accéder au contexte d'exécution pour les activités de flux de travail personnalisées

Avec les activités de flux de travail personnalisées, accédez à ces données dans votre code 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.

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.

À l’exception de cas documentés spécifiques, évitez de dépendre 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 changer au fil du temps.

Si vous choisissez de prendre une dépendance sur les valeurs trouvées dans le ParentContext, prenez des mesures pour vous assurer que votre code est résilient pour s’adapter aux modifications potentielles. Testez régulièrement la logique pour vérifier que les conditions dont vous dépendez restent en vigueur au fil du temps.

ExecutionContext

L’interface IExecutionContext fournit le reste des informations. Les classes IPluginExecutionContext et IWorkflowContext implémentent cette interface.

Pour les plug-ins, toutes les propriétés de cette classe de contexte d’exécution fournissent des informations utiles que vous devrez peut-être accéder dans votre code.

Deux des propriétés les plus importantes sont les propriétés InputParameters et OutputParameters.

D’autres propriétés souvent utilisées sont SharedVariables, PreEntityImages et PostEntityImages.

CollectionsDeParamètres

Toutes les propriétés du contexte d’exécution sont en lecture seule. Mais les InputParameters, OutputParameters et SharedVariables sont des valeurs ParameterCollection. Vous pouvez modifier le comportement de l’opération en modifiant les valeurs des éléments de ces collections, en fonction de la phase du pipeline d’exécution d’événements pour lequel votre plug-in est inscrit.

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 passée dans le cadre de CreateRequest, vous devez savoir que le nom de cette propriété est Target. Vous pouvez ensuite accéder à cette valeur à l’aide de code comme suit :

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.

Paramètres d'entrée

Les InputParameters représentent la valeur de la propriété OrganizationRequest.Parameters qui représente l’opération provenant des services web.

Comme décrit dans Utiliser des messages avec le Kit de développement logiciel (SDK) pour .NET, toutes les opérations qui se produisent dans le système sont finalement des instances de la OrganizationRequest classe que la IOrganizationServiceméthode .Execute traite.

Comme décrit dans Event Framework, les opérations passent par une série d’étapes. Vous pouvez inscrire votre plug-in à des étapes qui se produisent avant que les données ne 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 constatez que les valeurs de la InputParameters collection représentent une condition que vous ne pouvez pas autoriser, lèvez une InvalidPluginExecutionException (de préférence dans l’étape de prévalidation ) qui annule l’opération et affiche une erreur à l’utilisateur à l’aide d’un plug-in synchrone ou enregistre l’erreur si le plug-in est asynchrone. Pour plus d’informations, consultez Annulation d’une opération.

Paramètres de sortie

Les OutputParameters représentent la valeur de la propriété OrganizationResponse.Results qui représente la valeur de retour de 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, utilisez la valeur de clé qui est généralement identique au nom des propriétés dans la classe de réponse. Toutefois, cela 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.

Le système ne renseigne les OutputParameters qu’après la transaction de base de données, ils ne sont donc disponibles 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

Utilisez la SharedVariables propriété pour transmettre des données de l’API ou d’un plug-in à une étape qui se produit ultérieurement dans le pipeline d’exécution. Étant donné que cette propriété est une ParameterCollection valeur, les plug-ins peuvent ajouter, lire ou modifier des propriétés pour partager des données avec les étapes suivantes.

L’exemple suivant montre comment passer une PrimaryContact valeur d’un plug-in enregistré pour une étape PreOperation vers 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.
        }
    }
}

Passage d’une variable partagée à partir de l’API

Pour introduire une variable partagée lorsque vous appelez une API, utilisez le mot clé tag de l’API web ou du SDK pour .NET pour passer une valeur de chaîne.

Vous pouvez accéder à cette valeur dans la collection de variables partagées à l’aide de la tag clé. Une fois défini, vous ne pouvez pas modifier cette valeur.

Pour plus d’informations, consultez Ajouter une variable partagée au contexte d’exécution du plug-in.

Images d’entité

Lorsque vous inscrivez une étape pour un plug-in qui inclut une table comme l’un des paramètres, vous pouvez spécifier qu’une copie des données de la table doit être incluse en tant qu’instantané ou image à l’aide des propriétés PreEntityImages et PostEntityImages.

Ces données offrent un point de comparaison pour les données de la table lorsqu'elles transitent par 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 :

• Définir des images d’entité
• Images d’entités pour les extensions de workflow

Voir aussi

Infrastructure d’événements
Écrire un plug-in