Enregistrer un plug-in

Une fois qu’un plug-in a été écrit et compilé, il doit être enregistré auprès de l’infrastructure d’événements pour s’exécuter lorsqu’un type d’entité (table) et une opération (message) spécifiques sont traités par Dataverse. L’enregistrement d’un plug-in avec l’infrastructure d’événements Dataverse nécessite l’utilisation d’un outil : l’outil d’enregistrement de plug-in (PRT) ou l’extension Power Platform Tools pour Visual Studio.

Le PRT crée des enregistrements d’objet Dataverse et prend en charge la modification de ces enregistrements. Cet article explique comment enregistrer un assembly et une étape de plug-in, ajouter un assembly à une solution et effectuer d’autres opérations courantes liées au plug-in à l’aide de l’outil d’enregistrement de plug-in.

L’extension Visual Studio fournit un environnement de développement enrichi en fonctionnalités et couvre l’ensemble du processus de développement de codage, de déploiement et de débogage/profilage. Pour plus d’informations sur l’utilisation de l’extension Power Platform Tools pour Visual Studio, consultez le guide de démarrage rapide.

À propos de l’outil Plug-in Registration Tool

Plug-in Registration Tool (PRT) prend en charge l’enregistrement des assemblages de plug-in, des étapes de traitement des messages et d’autres types d’objets avec Dataverse. PRT est l’un des nombreux outils Dataverse disponibles au téléchargement depuis NuGet.org. Suivez les instructions des outils de développement Dataverse pour télécharger PRT et éventuellement d’autres outils de développement.

Après avoir téléchargé l’outil PRT, suivez les instructions Se connecter à l’aide de l’outil PRT pour connecter l’outil à votre environnement Dataverse cible où votre plug-in doit être enregistré.

Inscription d’assembly

L’enregistrement d’un assembly est le processus de téléchargement de l’assembly dans la base de données Dataverse, qui est gérée par l’outil. Consultez les instructions indiquées dans Enregistrer votre assembly dans le Didacticiel : Entrer et enregistrer un plug-in

Notes

Vous trouverez des options relatives au mode d’isolation et à l’emplacement pour l’assembly. Elles font référence aux options qui s’appliquent aux déploiements sur site. Dataverse n’est pas disponible pour les déploiements locaux, donc vous accepterez toujours les options par défaut Bac à sable (sandbox) et Base de données pour ces options.

Quand un assemblage est chargé, il est stocké dans la table PluginAssembly. La plupart des propriétés sont définies à l’aide d’une réflexion de l’assembly importé. Les octets encodés en base64 de l’assembly sont stockés dans la colonne Content. Au moment de la visualisation de l’assembly Propriétés dans le PRT, vous ne pouvez modifier que la valeur Description. Toutes les classes compilées au sein de l’assembly qui implémentent l’interface IPlugin ou qui en dérivent CodeActivity sont automatiquement enregistrées.

Afficher les assemblys enregistrés

Vous pouvez afficher des informations sur les assemblys de plug-ins enregistrés dans Power Apps Classic, dans l’Explorateur de solutions, sous Solutions dans le volet de navigation de gauche de Power Apps et dans la vue de l’assembly PRT. Pour accéder à l’Explorateur de solutions dans Power Apps, choisissez Solutions puis choisissez Passer en classique dans la barre d’outils. Pour accéder à la solution par défaut à partir de Power Apps, choisissez Solutions, sélectionnez Solution par défaut dans la liste, puis choisissez Assemblys de plug-ins dans le volet Objets de gauche.

Notes

Chaque assembly que vous enregistrez sera ajouté à la Solution par défaut, à ne pas confondre avec la solution par défaut de Common Data Services. Pour plus d’informations sur les solutions, consultez la page Présentation des solutions

Ajouter votre assembly à une solution

Comme décrit dans Afficher les assemblys enregistrés, l’enregistrement d’un assembly que vous avez créé a été ajouté au système Solution par défaut. Vous devez ajouter votre assembly à une solution non gérée afin de pouvoir la distribuer à d’autres organisations. Le PRT ne vous permet pas de spécifier une solution lors de l’enregistrement d’un assemblage ou d’étapes.

Pour en savoir plus sur les solutions et comment en créer une, voir Aperçu des solutions et Créer une solution. Une fois que vous avez créé une solution, vous pouvez y ajouter votre assembly de plug-in dans Power Apps en choisissant d’abord la solution dans la liste de solutions, puis en choisissant Ajouter un existant > Plus > Développeur > Assembly plug-in.

Notes

Aucun enregistrement d’étape existant ou ultérieur (voir la section suivante) n’est ajouté à la solution non gérée qui inclut les assemblys de plug-in. Vous devez ajouter chaque étape enregistrée à la solution séparément. Pour plus d’informations : Ajouter une étape à la solution

Enregistrement d’étape

Lorsqu’un assembly est chargé ou mis à jour, toutes les classes qui implémentent IPlugin sont disponibles dans le PRT. Utilisez les instructions dans Inscrire une nouvelle étape dans Didacticiel : Entrer et enregistrer un plug-in pour créer une nouvelle inscription d’étape.

Lorsque vous enregistrez une étape, de nombreuses options d’enregistrement s’offrent à vous, qui dépendent de l’étape du pipeline d’événements et de la nature de l’opération à laquelle vous enregistrerez le code auquel vous souhaitez répondre.

Champs d’information sur la configuration générale

Champ	Description
Message	L’outil PRT remplit automatiquement les noms de messages disponibles dans le système. Pour plus d’informations : Utiliser des messages avec le SDK pour .NET
Entité principale	PRT remplit automatiquement les tables valides qui s’appliquent au message sélectionné. Ces messages ont un paramètre Target qui accepte un type Entity ou EntityReference. Si des tables valides s’appliquent, vous devez définir cette valeur de champ lorsque vous souhaitez limiter le nombre d’appels du plug-in. Si vous laissez ce champ vide pour les messages de la table principale comme Update, Delete, Retrieve et RetrieveMultiple ou tout message qui peut être appliqué avec le message, le plug-in est appelé pour toutes les tables qui prennent en charge ce message.
Entité secondaire	Ce champ est conservé pour la compatibilité ascendante pour les messages déconseillés qui acceptaient un groupe de EntityReference en tant que paramètre Target. Ce champ n’est généralement plus utilisé.champ
Filtrage d’attributs	Avec le message Update ou OnExternalUpdated, lorsque vous définissez Entité principale, le filtrage des colonnes limite l’exécution du plug-in uniquement aux cas où les colonnes sélectionnées sont incluses dans la mise à jour. Définir ce champ est une meilleure pratique pour la performance. N’incluez pas la clé primaire de l’entité dans les attributs de filtrage. La clé primaire est toujours incluse dans les opérations de mise à jour ; par conséquent, si vous le faites, tous les autres attributs filtrés sont annulés.
Gestionnaire d’événements	Cette valeur de champ sera remplie sur le nom de l’assembly et de la classe de plug-in.
Nom de l’étape	Nom de l’étape. Une valeur est pré-remplie selon la configuration de l’étape, mais cette valeur peut être remplacée.
Exécuter dans le contexte utilisateur	Fournit des options pour appliquer l’emprunt d’identité à l’étape. La valeur par défaut est Utilisateur appelant. Si l’utilisateur appelant ne dispose pas des privilèges nécessaires pour effectuer les opérations de l’étape, vous devrez peut-être définir cette valeur de champ pour un utilisateur disposant de ces privilèges. Pour plus d’informations : Définir l’emprunt d’identité d’utilisateur pour une étape
Ordre d’exécution	Plusieurs étapes peuvent être enregistrées pour la même étape du même message. Le numéro de ce champ détermine l’ordre d’application, du moins élevé au plus élevé. Remarque : définissez cela pour contrôler l’ordre dans lequel les plug-ins sont appliqués à ce stade. Il n’est pas recommandé d’accepter simplement la valeur par défaut. L’ordre d’exécution réel des plug-ins avec la même valeur d’ordre d’exécution (pour la même étape, table et message) n’est pas garanti et peut être aléatoire.
Description	Description de l’étape. Cette valeur est préremplie mais peut être remplacée.

Phase d’exécution dans le pipeline d’événements

Choisissez la phase du pipeline d’événements qui convient le mieux à votre plug-in.

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

Pour plus d’informations : Pipeline d’exécution des événements

Mode d’exécution

Il existe deux modes d’exécution : asynchrone et synchrone.

Option	Description
Asynchrone	Le contexte d’exécution et la définition de la logique métier à appliquer sont déplacés vers le travail système à exécuter une fois l’opération terminée.
Synchrone	Les plug-ins s’exécutent immédiatement en fonction de la phase d’exécution et de l’ordre d’exécution. L’opération entière attendra la fin des exécutions.

Les plug-ins asynchrones peuvent uniquement être enregistrés pour la phase PostOperation. Pour plus d’informations sur le fonctionnement des tâches système, consultez Service asynchrone

Scénarios d’enregistrement de l’étape spéciaux

Il existe certains scénarios où un enregistrement d’étape et une combinaison de table ne sont pas évidents. C’est le résultat de la façon dont le système est conçu en interne quand il existe une relation spéciale entre les tables ou les opérations. Les informations ci-dessous identifient ces cas et fournissent des instructions d’enregistrement d’étape.

• Il existe certains cas où des plug-ins enregistrés pour l’événement Update peuvent être appelés deux fois. Pour plus d’informations : Comportement des opérations de mise à jour spécifiques
• Enregistrer une étape de plug-in sur account ou contact quand vous souhaitez gérer les modifications de données au niveau des enregistrements customeraddress, leadaddress, publisheraddress ou competitoraddress.

Déploiement

Option	Description
Serveur	Le plug-in s’exécute sur le serveur Dataverse.
Déconnecté(e)	Le plug-in fonctionnera dans Dynamics 365 for Outlook lorsque l’utilisateur est en mode hors connexion.

Définir des données de configuration

Les champs Configuration non sécurisée et Configuration sécurisée du PRT vous permettent de spécifier les données de configuration à transmettre au plug-in pour une étape spécifique.

Notes

Les données de configuration sécurisée ne sont pas incluses dans l’enregistrement de l’étape lorsque vous exportez une solution.

Vous pouvez écrire votre plug-in pour accepter les valeurs de chaîne dans le constructeur afin d’utiliser ces données pour contrôler le fonctionnement du plug-in pour l’étape. Pour plus d’informations : Transmettre des données de configuration à votre plug-in

Définir des images d’entité

Dans votre plug-in, vous souhaiterez peut-être référencer des valeurs de propriété de table principale qui n’étaient pas incluses dans une opération. Par exemple, dans une opération Update, vous voudrez peut-être savoir quelle était la valeur avant sa modification, mais le contexte d’exécution ne fournit pas ces informations, il ne contient que la valeur modifiée.

Si l’étape du plug-in est enregistrée dans les phases Validation préalable ou Opération préalable du pipeline d’exécution, vous pouvez utiliser l’instance IOrganizationService d’organisation pour récupérer la valeur actuelle de la propriété, mais ce n’est pas recommandé en termes de performances. Une bonne pratique consiste à définir une image pré-entité avec l’enregistrement de votre étape de plug-in. Cela capturera un « instantané » de la table avec les champs qui vous intéressent tels qu’ils existaient avant l’opération que vous pouvez utiliser pour comparer avec les valeurs modifiées.

Important

Le comportement par défaut lors de la création d’une image d’entité consiste à sélectionner toutes les colonnes. N’utilisez pas ce comportement par défaut. Cela peut avoir un impact négatif sur les performances. N’incluez que les colonnes requises par la logique de votre plug-in.

Messages qui prennent en charge les images d’entité

Dans Dataverse, seuls les messages suivants prennent en charge les images d’entité :

Message	Propriété de classe de demande	Description
Assign	Target	La table assignée.
Create	Target	La table créée.
Delete	Target	La table supprimée.
DeliverIncoming	EmailId	ID de messagerie fournie.
DeliverPromote	EmailId	ID de messagerie fournie.
Merge	Target ou SubordinateId	La table parent, dans laquelle les données de la table enfant sont fusionnées ou la table enfant qui est fusionnée dans la table parent.
Route	Target	L’élément est en cours d’acheminement.
Send	FaxId, EmailId ou TemplateId	L’élément est en cours d’envoi.
SetState	EntityMoniker	La table pour laquelle l’état est défini.
Update	Target	La table mise à jour.

Types d’images d’entité

Il existe deux types d’images d’entité : Pré-image et Post-image. Lorsque vous configurez les images, celles-ci seront disponibles dans le contexte d’exécution en tant que PreEntityImages and PostEntityImages respectivement. Comme leur nom l’indique, ces instantanés représentent à quoi ressemble la table avant et après l’opération. Quand vous configurez une image d’entité, vous définissez une valeur alias* de table qui est la valeur clé que vous utilisez pour accéder à une image d’entité spécifique à partir des propriétés PreEntityImages ou PostEntityImages.

Disponibilité des images

Quand vous configurez une image d’entité, il est important de reconnaître que le type d’images d’entité disponible dépend de la phase de l’étape enregistrée et du type d’opération. Par exemple :

• Vous ne pouvez pas avoir une Pre Image pour le message Create, car la table n’existe pas encore.
• Vous ne pouvez pas avoir une Post Image pour le message Delete, car la table n’existe plus.
• Vous ne pouvez avoir qu’une Post Image pour les étapes enregistrées à l’étape PostOperation du pipeline d’exécution, car il n’y a aucun moyen de savoir quelles seront les propriétés de la table tant que la transaction n’est pas terminée.
• Pour une opération Update qui est enregistrée à la phase PostOperation, vous pouvez avoir à la fois une pré-image et une post-image.

Ajouter une image d’entité

Utilisez l’extension Power Platform Tools pour Visual Studio pour ajouter une image d’entité à une étape de plug-in.

Vous pouvez également utiliser l’outil d’enregistrement de plug-in pour ajouter une image d’entité à une étape en suivant les instructions du Tutoriel : Mettre à jour un plug-in sous la rubrique Ajouter une image.

Ajouter une étape à une solution

Comme mentionné dans Ajouter votre assembly à une solution, les assemblys du plug-in sont des composants de solution qui peuvent être ajoutés à une solution non gérée. Les Étapes de traitement du message Sdk sont également des composants de solution et doivent également être ajoutées à une solution non gérée afin de pouvoir être distribuées.

La procédure pour ajouter une étape à une solution est similaire à l’ajout d’un assembly. Vous utiliserez la commande Ajouter pour la déplacer dans la solution non gérée souhaitée. La seule différence est que si vous essayez d’ajouter une étape mais que vous n’avez pas déjà ajouté l’assembly contenant la classe utilisée dans l’étape, vous serez invité à ajouter les composants requis manquants.

Si vous rencontrez ce cas de figure, vous devrez sélectionner OK pour intégrer l’assembly à la solution non gérée. Le seul moment où vous ne sélectionnez pas cette option est quand votre solution est conçue pour être installée dans un environnement où une autre solution contenant l’assembly est déjà installée.

De même, vous devez noter que la suppression de l’assembly de la solution ne supprimera aucune étape qui en dépend.

Définir l’emprunt d’identité de l’utilisateur pour une étape

Avec l’outil d’enregistrement de plug-in en cours d’exécution et connecté à l’environnement Dataverse cible, vous pouvez procéder à la définition ou à la modification d’un enregistrement d’étape de plug-in. Dans cette section, nous allons aborder le changement d’utilisateur pour le compte duquel le plug-in effectue ses opérations. C’est-à-dire l’utilisateur effectif qui exécute les opérations de données initiées par le plug-in. Par défaut, l’utilisateur appelant (l’utilisateur qui a invoqué une opération dans Dataverse) est le propriétaire desdites opérations. Cependant, un utilisateur différent peut être spécifié lors de l’enregistrement de l’étape. Vous devez disposer du rôle de sécurité Administrateur système ou Personnalisateur de système pour effectuer cette opération.

Pour définir le contexte utilisateur d’une étape de plug-in :

1. Développez le nœud d’assembly de plug-in cible dans la vue d’assembly jusqu’à ce que vous voyiez le nœud d’enregistrement (étape) souhaité.
2. Choisissez le nœud de l’étape, puis Mettre à jour dans le menu contextuel ou dans la barre d’outils.
3. Choisissez un utilisateur dans la liste déroulante des utilisateurs disponibles à côté de l’étiquette Exécuter dans le contexte de l’utilisateur.
4. Choisissez Étape de mise à jour.

Pour plus d’informations : Emprunter l’identité d’un utilisateur

Mettre à jour un assembly

Quand vous modifiez et reconstruisez l’assembly que vous avez précédemment enregistré, vous devez le mettre à jour. Consultez l’étape Mettre à jour l’enregistrement de l’assembly de plug-in dans le Didacticiel : Mettre à jour un plug-in pour en connaître la procédure.

Gestion des versions d’un assembly

Si vous apportez des modifications à un assembly de plug-in faisant partie d’une solution gérée déployée, vous devez prendre en compte l’impact de vos modifications au moment de la mise à jour de cette solution gérée. La version de l’assembly contrôlera le comportement.

Les assemblys de plug-in peuvent être versionnés à l’aide d’un format de version sémantique major.minor.build.revision défini dans le fichier Assembly.info du projet Microsoft Visual Studio. En fonction de la partie du numéro de version de l’assembly qui est modifiée dans une solution récente, le comportement suivant s’applique lorsqu’une solution existante est mise à jour via l’importation.

• Le numéro de version de la build ou de l’assembly de révision est modifié

  Ceci est considéré comme une mise à niveau sur place. La version antérieure de l’assembly est supprimée lorsque la solution contenant l’assembly mis à jour est importée. Toutes les étapes préexistantes de la solution antérieure sont automatiquement modifiées pour faire référence à la version la plus récente de l’assembly.

• Le numéro de version majeure ou mineure de l’assembly est modifié

  Quand une solution mise à jour contenant l’assembly modifié est importée, l’assembly est considéré comme un assembly différent de la version précédente de cet assembly dans la solution existante. Les étapes d’inscription du plug-in dans la solution existante continuent de faire référence à la version précédente de l’assembly. Si vous souhaitez que la procédure d’inscription existante du plug-in de l’assembly précédent pointe vers l’assembly modifié, vous devrez utiliser l’outil d’inscription des plug-ins pour modifier manuellement la configuration des étapes pour faire référence au type d’assembly révisé. L’opération doit être effectuée avant l’exportation de l’assembly mis à jour en une solution à des fins d’importation ultérieure.

Annuler l’enregistrement ou désactiver des composants et des plug-ins

Vous pouvez désenregistrer ou désactiver les plug-ins et leurs composants à l’aide de l’outil d’enregistrement de plug-in (PRT).

Important

Il n’est plus possible de désinscrire ou de désactiver les plug-ins et étapes système Microsoft ou prêts à l’emploi. Auparavant, vous pouviez désinscrire ou désactiver certains des plug-ins système Microsoft.* et autres prêts à l’emploi. Nous avons modifié ce comportement pour ne plus autoriser cela. La modification de la fonctionnalité a été apportée, car la désinscription ou la désactivation de ces plug-ins ou étapes peut empêcher les fonctionnalités du produit de fonctionner comme prévu. Si vous avez besoin de désinscrire ou de désactiver un tel plug-in ou une telle étape, déposez une demande d’assistance Microsoft.

Désactiver ou activer une étape de plug-in

Avec l’outil d’enregistrement des plug-ins en cours d’exécution et connecté à l’environnement Dataverse cible, vous pouvez procéder à la désactivation ou à l’activation d’une étape de plug-in. La désactivation d’une étape empêche effectivement le plug-in de s’exécuter lorsque Dataverse traite la combinaison d’entité et de message spécifiée dans l’enregistrement de l’étape.

Important

La désactivation d’un plug-in peut affecter négativement la fonctionnalité de votre application, d’une solution ou du système Dataverse. Avant de poursuivre, assurez-vous de bien comprendre les implications.

Pour désactiver ou activer une étape de plug-in enregistrée :

1. Développez le nœud d’assembly de plug-in cible dans la vue d’assembly jusqu’à ce que vous voyiez le nœud d’enregistrement (étape) souhaité.
2. Choisissez le nœud de l’étape, puis Activer ou Désactiver dans le menu contextuel ou dans la barre d’outils.

Vous pouvez également désactiver ou activer les étapes de l’interface utilisateur de l’explorateur de solutions Dataverse hérité à l’aide des commandes Activer et Désactiver.

Annuler l’enregistrement les composants

L’outil PRT fournit des commandes pour annuler l’enregistrement des assemblys, des types, des étapes et des images. Consultez les instructions permettant d’Annuler l’enregistrement d’un assembly, d’un plug-in et d’une étape dans le Didacticiel : Mettre à jour un plug-in pour obtenir la procédure complète.

Il s’agit des opérations de suppression sur les tables PluginAssembly, PluginType, SdkMessageProcessingStep et SdkMessageProcessingStepImage.

Vous pouvez également supprimer les assemblys du plug-in et les étapes de traitement du message SDK dans l’explorateur de solutions pour obtenir le même résultat. Dans la figure ci-dessous, une solution personnalisée nommée La solution par défaut Common Data Service s’affiche.

Notes

Vous ne pouvez supprimer (désinscrire) aucun assembly du plug-in si des étapes de traitement du message Sdk dépendent d’eux. Les images d’entité ne peuvent pas être supprimées séparément, mais elles seront supprimées lorsque les étapes qui les utilisent seront supprimées.

Étapes suivantes

Déboguer des plug-ins

Voir aussi

Écrire des plug-ins pour étendre les processus d’entreprise
Écrire un plug-in
Didacticiel : Entrez et enregistrez un plug-in
Didacticiel : Déboguer un plug-in
Didacticiel : Mettre à jour 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é).