Infrastructure d’événements

La possibilité d’étendre le comportement par défaut de Microsoft Dataverse dépend de la détection lorsque des événements se produisent sur le serveur. Event Framework offre la possibilité d’inscrire du code personnalisé à exécuter en réponse à des événements spécifiques.

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

En tant que développeur, vous allez utiliser l’outil d’inscription de plug-ins pour configurer des plug-ins, des intégrations Azure, des fournisseurs de données de table virtuelle et des webhooks pour répondre aux événements fournis par l’infrastructure d’événements. Lorsque des événements se produisent et qu’une extension est inscrite pour y répondre, des informations contextuelles sur les données impliquées dans l’opération sont transmises à l’extension. Selon la façon dont l’inscription de l’événement est configurée, l’extension peut modifier les données transmises, lancer un processus automatisé à appliquer immédiatement ou définir qu’une action est ajoutée à une file d’attente à effectuer ultérieurement.

Pour tirer parti de l’infrastructure d’événements pour vos extensions personnalisées, vous devez comprendre :

• Quels événements sont disponibles
• Traitement de l’événement
• Quel type de données est disponible pour votre extension personnalisée lorsque l’événement se produit
• Quelles sont les contraintes de temps et de ressource qui s’appliquent
• Comment surveiller les performances

Événements disponibles

Comme décrit dans Use messages with the SDK for .NET, les opérations de données dans la plateforme Dataverse sont basées sur les messages et chaque message a un nom. Il existe Create, , RetrieveRetrieveMultipleUpdate, , Deleteet AssociateDisassociate des messages qui couvrent les opérations de données de base qui se produisent avec des 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 d’inscription de plug-in pour associer une extension à un message particulier, vous l’inscrireez en tant qu’étape. La capture d’écran ci-dessous est la boîte de dialogue Inscrire une nouvelle étape utilisée lors de l’inscription d’un plug-in.

Une étape fournit les informations sur le message auquel les extensions doivent répondre ainsi qu’un certain nombre d’autres choix de configuration. Utilisez le champ Message pour choisir le message auquel votre extension répond.

Généralement, vous pouvez trouver un message pour la plupart des classes *Request dans les espaces de noms Microsoft.Crm.Sdk.Messages ou Microsoft.Xrm.Sdk.Messages, mais vous trouverez également des messages pour toutes les actions personnalisées qui ont été créées dans l’organisation. Toutes les opérations impliquant des définitions de table ne sont pas disponibles.

Les données relatives aux messages sont stockées dans les tables SdkMessage et SdkMessageFilter . L’outil d’inscription de plug-in filtre ces informations pour afficher uniquement les messages valides.

Pour vérifier si une combinaison de messages et de tables 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

Vous pouvez également utiliser le fetchXML suivant pour récupérer ces informations. 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>

Pipeline d’exécution d’événements

Lorsque vous inscrivez une étape à l’aide de l’outil d’inscription de plug-in, vous devez également choisir l’étape d’exécution du pipeline d’événements. Chaque message est traité dans une série de 4 étapes, comme décrit dans le tableau suivant :

La phase que vous devez choisir dépend de l’objectif de l’extension. Vous n’avez pas besoin d’appliquer toute votre logique métier à une seule étape. Vous pouvez appliquer plusieurs étapes afin que votre logique indiquant s’il faut autoriser une opération à continuer peut se trouver dans l’étape PreValidation et que votre logique pour apporter des modifications aux propriétés du message peut se produire dans l’étape PostOperation .

Plusieurs extensions peuvent être inscrites pour le même message et la même étape. Dans l'enregistrement de l'étape, la valeur d'ordre d'exécution détermine la séquence dans laquelle plusieurs extensions doivent être traitées pour une étape donnée.

Les informations sur les étapes inscrites sont stockées dans la table SdkMessageProcessingStep.

Étapes de plug-in asynchrones

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

Cela est souvent nécessaire lors de l’utilisation d’enregistrements associés à l’enregistrement actif, mais créés dans un autre processus. Par exemple, UserSettings en rapport avec un élément spécifique SystemUser ne sera pas créé tant que la ligne SystemUser n’est pas créée.

Plus d’informations : Service asynchrone

Contexte d’événement

Si votre extension est un plug-in, elle reçoit un paramètre qui implémente l’interface IPluginExecutionContext . Cette classe fournit des informations sur le Stage pour lequel le plug-in est enregistré, ainsi que des renseignements sur le ParentContext, qui concernent toute opération dans un autre plug-in ayant déclenché l'opération en cours.

Si votre extension est un point de terminaison Azure Service Bus, un sujet Azure EventHub ou un webhook, les données qui seront publiées sur le point de terminaison inscrit seront sous la forme d’un RemoteExecutionContext qui implémente à la fois IPluginExecutionContext et IExecutionContext.

Pour plus d’informations sur le contexte d’exécution, consultez Comprendre le contexte d’exécution.