Comprendre le contexte de données passé à un plug-in

 

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Lorsqu’un plug-in s’exécute en réponse à un événement de pipeline d’exécution pour lequel il est inscrit, la méthode Execute du plug-in est appelée. Cette méthode passe un objet IServiceProvider en tant que paramètre, qui contient un certain nombre d’objets utiles. Les sections suivantes décrivent certaines informations qui sont transmises à un plug-in lorsqu’il est exécuté.

Contenu de la rubrique

Accéder au contexte d’exécution du plug-in

Accéder au service d’organisation

Accéder au service de notification

Paramètres d’entrée et de sortie

Images de pré-entité et images de post-entité

Accéder au contexte d’exécution du plug-in

IPluginExecutionContext contient des informations qui décrivent l’environnement à l’exécution que le plug-in exécute, des informations relatives au pipeline d’exécution et des informations sur l’entité commerciale. Le contexte est contenu dans le paramètre System.IServiceProvider qui est passé au moment de l’exécution à un plug-in via la méthode Execute.

// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

Lorsqu’un événement système est déclenché pour lequel un plug-in est inscrit, le système crée et remplit le contexte, puis le passe à un plug-in via les classes et les méthodes mentionnées précédemment. Le contexte d’exécution est passé à chaque plug-in inscrit dans le pipeline lorsqu’ils sont exécutés. Chaque plug-in du pipeline d’exécution est en mesure de modifier les propriétés accessibles en écriture dans le contexte. Par exemple, en fonction d’un plug-in inscrit en tant que pré-événementiel et un autre plug-in inscrit en tant que post-événementiel, le plug-in post-événementiel peut recevoir un contexte qui a été modifié par le plug-in pré-événementiel. Le même cas s’applique aux plug-ins qui sont inscrits dans la même phase.

Toutes les propriétés de IPluginExecutionContext sont en lecture seule. Cependant, votre plug-in peut modifier le contenu de ces propriétés qui sont des collections. Pour plus d’informations sur la prévention de boucle infinie, voir Depth.

Accéder au service d’organisation

Pour accéder au service d’organisation Microsoft Dynamics 365, il est nécessaire que le code du plug-in crée une instance de service via la méthode ServiceProvider.GetService.

// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

La plateforme vous fournit les URL du service Web et les informations d’accès réseau appropriées lorsque vous utilisez cette méthode. L’instanciation du proxy de votre propre service Web n’est pas prise en charge car elle crée des problèmes d’interblocage et d’authentification.

Accéder au service de notification

Les plug-ins inscrits synchrones peuvent publier le contexte d’exécution dans Microsoft Azure Service Bus. L’objet fournisseur de services qui est passé au plug-in contient une référence à IServiceEndpointNotificationService. C’est via ce service de notification que les plug-ins synchrones peuvent envoyer des messages sponsorisés à Microsoft Azure Service Bus. Pour plus d’informations sur Microsoft Azure, voir Intégration Azure avec Microsoft Dynamics 365.. Pour plus d’informations sur l’écriture d’un plug-in pouvant publier sur le Microsoft Azure Service Bus, voir Écrire un plug-in compatible Azure personnalisé.

Paramètres d’entrée et de sortie

La propriété InputParameters contient les données contenues dans le message de demande actuellement traité par le pipeline d’exécution de l’événement. Votre code de plug-in peut accéder à ces données. La propriété est de type ParameterCollection où les clés permettant d’accéder aux données de la demande correspondent aux noms des propriétés publiques réelles dans la demande. Par exemple, consultez CreateRequest. Une propriété CreateRequest est nommée Target, qui est de type Entity. Il s’agit de l’entité actuellement opérée sur la plateforme. Pour accéder aux données de l’entité, vous avez l’utiliser le nom « Target » comme clé dans la collection des paramètres d’entrée. Vous devez également effectuer un cast pour l’instance retournée.

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the input parameters.
    Entity entity = (Entity)context.InputParameters["Target"];

Notez que toutes les demandes contiennent une propriété Target qui est de type Entity, donc vous devez regarder à chaque demande ou réponse. Par exemple, DeleteRequest possède une propriété Target, mais son type est EntityReference. L’exemple de code précédent est modifié comme suit.

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&    context.InputParameters["Target"] is EntityReference)
{
    // Obtain the target entity from the input parameters.
    EntityReference entity = (EntityReference)context.InputParameters["Target"];
}

Une fois que vous avez accès aux données d'entité, vous pouvez les lire et les modifier. Toutes les modifications de données de contexte effectuées par les plug-ins enregistrés à la phase 10 ou 20 du pipeline sont passées dans le contexte de l'opération principale de la phase 30.

Important

Les champs d'un enregistrement d'entité qui sont passés à un plug-in via le contexte ne peuvent pas tous être modifiés. Vous devez activer la propriété de métadonnées du champ IsValidForUpdate pour vérifier qu'elle n'est pas définie sur false. La tentative de modification de la valeur d'un champ qui ne peut pas être mis à jour génère une exception.

De même, la propriété OutputParameters contient les données contenues dans le message de réponse, par exemple CreateResponse, actuellement traité par le pipeline d’exécution de l’événement. Toutefois, seuls les plug-in post-événementiels synchrones et les plug-ins inscrits asynchrones ont le paramètre OutputParameters qui est renseigné, car la réponse est le résultat de l’opération de plateforme principale. La propriété est de type ParameterCollection où les clés permettant d’accéder aux données de réponse correspondent aux noms des propriétés publiques réelles dans la réponse.

Images de pré-entité et images de post-entité

PreEntityImages et PostEntityImages contiennent les captures instantanées des attributs de l’entité principale avant (pre) et après (post) l’opération de plateforme principale.Microsoft Dynamics 365 remplit les images de pré-entité et de post-entité en fonction des privilèges de sécurité de l’utilisateur système d’emprunt. Seuls les attributs d’entité qui sont définis avec une certaine valeur ou avec la valeur null sont disponibles dans les images de pré-entité ou les images de post-entité. Vous pouvez spécifier que la plateforme renseigne ces propriétés PreEntityImages et PostEntityImages lorsque vous inscrivez votre plug-in. La valeur d’alias de l’entité que vous spécifiez lors de l’inscription du plug-in est utilisée en tant que clé dans la collection d’images au sein du code du plug-in.

Il existe des événements où les images ne sont pas disponibles. Par exemple, seuls les plug-ins post-événementiels synchrones et les plug-ins inscrits asynchrones ont le paramètre PostEntityImages automatiquement renseigné. L’opération de création (create) ne prend pas en charge une image de pré-entité et l’opération de suppression (delete) ne prend pas en charge une image de post-entité. En outre, seul un petit sous-ensemble de messages prend en charge les images de pré-entité et de post-entité comme l’illustre le tableau suivant.

Demande de message	Propriété	Description
AssignRequest	Cible	Entité attribuée.
CreateRequest	Cible	Entité créée.
DeleteRequest	Cible	Entité supprimée.
DeliverIncomingEmailRequest	EmailId	ID de messagerie fournie.
DeliverPromoteEmailRequest	EmailId	ID de messagerie fournie.
ExecuteWorkflowRequest	Cible	Entité de workflow.
MergeRequest	Cible	Entité parente, dans laquelle les données de l’entité enfant sont fusionnées.
MergeRequest	SubordinateId	Entité enfant qui est fusionnée dans l’entité parente.
SendEmailRequest	EmailId	ID d’entité envoyée.
SetStateRequest	EntityMoniker	Entité pour laquelle l’état est défini.
UpdateRequest	Cible	Entité mise à jour.

L’inscription des images de pré-entité et de post-entité pour accéder aux valeurs d’attribut d’entité permet d’améliorer les performances des plug-ins par rapport à l’obtention d’attributs d’entité dans le code du plug-in via les demandes RetrieveRequest ou RetrieveMultipleRequest.

Sécurité Remarque

Une image de pré-entité, passée dans le contexte d’exécution à un plug-in ou une activité de workflow personnalisée, peut contenir des données pour lesquelles l’utilisateur connecté n’a pas les privilèges d’accès. Les administrateurs de Microsoft Dynamics 365 et d’autres utilisateurs disposant des autorisations de niveau supérieur peuvent inscrire les plug-ins à exécuter sous le compte d’utilisateur « système » ou le code du plug-in peut effectuer des appels en tant qu’utilisateur « système » au nom de l’utilisateur connecté. Dans ce cas, les utilisateurs connectés peuvent accéder à des données auxquelles leur niveau de sécurité ne permettent pas d’accéder.Pour plus d'informations :Emprunt d’identité des plug-ins

Voir aussi

Développement de plug-ins
Gérer les exceptions dans les plug-ins
Pipeline d’exécution des événements
Utiliser les messages (classes de demande et de réponse) avec la méthode Execute
Utilisez le service Organization pour lire et écrire des données ou des métadonnées.
Inscrire et déployer des plug-ins

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright