Infrastructure d’événement

La capacité d′étendre le comportement par défaut de Microsoft Dataverse dépend de la détection du moment où surviennent les événements sur le serveur. L′infrastructure d′événements permet d′enregistrer le code personnalisé à exécuter en réponse à des événements spécifiques.

Toutes les fonctionnalités visant à étendre le comportement par défaut de la plateforme dépendent de l′infrastructure d′événements. Lorsque vous configurez un workflow pour répondre à un événement à l′aide du concepteur de workflow sans écrire de code, l′événement est fourni par l′infrastructure d′événements.

En tant que développeur, vous allez utiliser l’outil Plug-in Registration Tool pour configurer les plug-ins, les intégrations Azure, les fournisseurs de données de table virtuelle et les webhooks pour répondre aux événements fournis par l’infrastructure d’événements. Lorsque des événements surviennent et qu′une extension est enregistrée pour y répondre, des informations contextuelles concernant les données impliquées dans l′opération sont transmises à l′extension. Selon la manière dont l’enregistrement est configuré pour l’événement, l’extension peut modifier les données transmises, initier certains processus automatisés à appliquer immédiatement ou définir qu’une action est ajoutée à une file d’attente à exécuter ultérieurement.

Pour optimiser l′infrastructure d′événements pour vos extensions personnalisées, vous devez comprendre :

• Quels sont les événements disponibles
• Comment est traité l′événement
• Quel type de données sont disponibles pour votre extension personnalisée lorsque l’événement survient
• Quelles contraintes s′appliquent en termes de temps et de ressources
• Comment surveiller les performances

Événements disponibles

Comme décrit dans Utiliser les messages avec le SDK pour .NET, les opérations des données sur la plateforme Dataverse sont basées sur les messages et chaque message a un nom. Les messages Create, Retrieve, RetrieveMultiple, Update, Delete, Associate et Disassociate couvrent les opérations de données de base qui surviennent avec les tables. Il existe également des messages spécialisés pour des opérations plus complexes et des actions personnalisées ajoutent de nouveaux messages.

Lorsque vous utilisez l’outil Plug-in Registration pour associer une extension à un message spécifique, vous allez l’enregistrer comme étape. Le capture d′écran ci-dessous présente la boîte de dialogue Inscrire une nouvelle étape utilisée lors de l′enregistrement d′un plug-in.

Une étape fournit les informations concernant à quel message les extensions doivent répondre ainsi que plusieurs autres options de configuration. Utilisez le champ Message pour choisir le message auquel votre extension va répondre.

En général, vous pouvez vous attendre à trouver un message pour la plupart des classes *Requête dans les espaces de nom Microsoft.Crm.Sdk.Messages ou Microsoft.Xrm.Sdk.Messages, mais vous trouverez également des messages pour toute action personnalisée créée dans l′organisation. Aucune opération impliquant les définitions de table n’est disponible.

Les données concernant les messages sont stockées dans les tables SdkMessage et SdkMessageFilter. L′outil Plug-in Registration filtre ces informations pour n′afficher que les messages valides.

Pour vérifier si l’association d’une table et d’un message prend en charge l’exécution de plug-ins à l’aide d’une requête de base de données, vous pouvez utiliser la requête d’API Web suivante :

[Organization URI]/api/data/v9.1/sdkmessages?$select=name
&$filter=isprivate eq false 
and (name ne 'SetStateDynamicEntity' 
and name ne 'RemoveRelated' 
and name ne 'SetRelated' and 
name ne 'Execute') 
and sdkmessageid_sdkmessagefilter/any(s:s/iscustomprocessingstepallowed eq true 
and s/isvisible eq true)
&$expand=sdkmessageid_sdkmessagefilter($select=primaryobjecttypecode;
$filter=iscustomprocessingstepallowed eq true and isvisible eq true)
&$orderby=name

Conseil

Vous pouvez exporter ces données vers une feuille de calcul Excel à l’aide de cette requête et des instructions fournies dans cette publication de blog : Trouver des messages et des tables éligibles pour les plug-ins avec Dataverse

Vous pouvez également utiliser ce qui suit FetchXML pour récupérer ces informations. Le FetchXML Builder est un outil utile pour exécuter ce type de requête.

<fetch>
  <entity name='sdkmessage' >
    <attribute name='name' />
    <link-entity name='sdkmessagefilter' alias='filter' to='sdkmessageid' from='sdkmessageid' link-type='inner' >
      <filter type='and' >
        <condition attribute='iscustomprocessingstepallowed' operator='eq' value='1' />
        <condition attribute='isvisible' operator='eq' value='1' />
      </filter>
      <attribute name='primaryobjecttypecode' />
    </link-entity>
    <filter>
      <condition attribute='isprivate' operator='eq' value='0' />
      <condition attribute='name' operator='not-in' >
        <value>SetStateDynamicEntity</value>
        <value>RemoveRelated</value>
        <value>SetRelated</value>
          <value>Execute</value>
      </condition>
    </filter>
    <order attribute='name' />
  </entity>
</fetch>

Attention

Le message Execute est disponible, mais nous vous recommandons de ne pas inscrire d′extensions pour lui puisqu′il est appelé à chaque opération.

Notes

Il existe certains cas où des plug-ins et des workflows enregistrés pour l’événement de mise à jour peuvent être appelés deux fois. Pour plus d′informations : Comportement des opérations de mise à jour spécifiques

Pipeline d′exécution des événements

Lorsque vous enregistrez une étape avec l’outil Plug-In Registration, vous devez également choisir la Phase d’exécution dans le pipeline d’événement. Chaque message est traité dans une série de 4 étapes comme décrit dans le tableau suivant :

Nom	Description
Validation préalable	Pour l'opération initiale, cette phase se produit avant l'exécution du système principal. Cela permet d'inclure une logique pour annuler l'opération avant la transaction de base de données. Les opérations suivantes déclenchées par les extensions stockées dans d'autres phases passeront également cette phase mais seront incluses dans la transaction des extensions appelantes. Cette phase se produit avant l'exécution des contrôles de sécurité pour vérifier que l'appelant ou l’utilisateur connecté dispose de l'autorisation appropriée pour effectuer l'opération prévue.
Opération préalable	Se produit avant l'exécution du système principal et au sein de la transaction de base de données. Si vous souhaitez modifier les valeurs d'une entité incluse dans le message, vous devez le faire ici. Évitez d'annuler une opération ici. L'annulation déclenchera une restauration de la transaction et aura un impact important sur les performances.
MainOperation	À usage interne uniquement, sauf pour les fournisseurs de données de tables virtuelles personnalisées et d’API personnalisées. Pour plus d’informations : Créer et utiliser des API personnalisées Fournisseurs de données de tables virtuelles personnalisées
PostOperation	Se produit après l’exécution du système principal et au sein de la transaction de base de données. Utilisez cette phase pour modifier les propriétés du message afin qu’il soit renvoyé à l’appelant. Évitez d’appliquer les modifications à une entité incluse dans le message, car cela déclenche un nouvel événement de mise à jour. À l’étape PostOperation, vous pouvez enregistrer les étapes pour utiliser le mode d’exécution asynchrone. Ces étapes s’exécutent en dehors de la transaction de base de données à l’aide du service asynchrone. Vous devez utiliser le mode asynchrone lors de l’enregistrement de votre plug-in si le plug-in est conçu pour effectuer une opération de mise à jour et est enregistré sur le message Create de l’entité utilisateur (SystemUser). Plus d’informations : Service asynchrone.

La phase à choisir dépend de l’objectif de l’extension. Inutile d′appliquer toutes vos logiques métier en une seule étape. Vous pouvez appliquer plusieurs étapes de telle sorte que votre logique concernant le fait d′autoriser ou non une opération pour continuer peut se trouver à la phase Validation préalable et votre logique pour apporter des modifications aux propriétés du message peut survenir dans la phase PostOperation.

Important

Une exception générée par votre code lors de toute phase synchrone dans une transaction de base de données entraîne l’annulation de l’intégralité de la transaction. Vous devez veiller à ce que tout cas d′exception éventuel soit traité par votre code. Si vous souhaitez annuler l′opération, vous devez le détecter à la phase Validation préalable et ne générer qu′une InvalidPluginExecutionException contenant un message approprié décrivant pourquoi l′opération a été annulée.

Plusieurs extensions peuvent être enregistrées pour le même message et la même phase. Lors de l′enregistrement de l′étape, la valeur Ordre d′exécution détermine l′ordre dans lequel plusieurs extensions doivent être traitées pour une phase donnée.

Les informations concernant les étapes inscrites sont enregistrées dans Table SdkMessageProcessingStep.

Étapes de plug-in asynchrones

Lors de l’inscription à l’étape PostOperation, vous avez la possibilité d’enregistrer l’étape pour l’exécuter en Mode d’exécution asynchrone. Ces plug-ins s’exécuteront une fois l’opération d’enregistrement terminée.

Cela est souvent nécessaire lorsque vous travaillez avec des enregistrements associés à l’enregistrement actuel mais créés dans un processus différent. Par exemple,UserSettings lié à un SystemUser spécifique ne sera pas créé avant que la ligne SystemUser soit créée.

Plus d’informations : Service asynchrone

Contexte de l’événement

Si votre extension est un plug-in, elle reçoit un paramètre qui implémente l’interface IPluginExecutionContext. Cette classe donne des informations sur la Stage pour laquelle le plug-in est enregistré, ainsi que des informations sur la ParentContext qui donne des informations sur toute opération au sein d’un autre plug-in qui a déclenché l’opération actuelle.

Si votre extension est un point de terminaison de bus Azure Service, une rubrique Azure EventHub ou un webhook, les données publiées vers le point de terminaison enregistré sont sous la forme d’un RemoteExecutionContext qui met en place à la fois IPluginExecutionContext et IExecutionContext

Pour plus d′informations sur le contexte d′exécution, lisez Présentation du contexte d′exécution.

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