Enregistrer un plug-in
Une fois qu’un plug-in est écrit et compilé, il doit être enregistré auprès du cadre d’événements pour s’exécuter lorsqu’une entité spécifique (ligne de table) et un message (opération) sont traités par Microsoft Dataverse. Pour enregistrer un plug-in avec Dataverse , il faut utiliser un outil - soit l’outil d’enregistrement de plug-in (PRT), soit l’extension Power Platform Outils pour Visual Studio.
Le PRT crée des enregistrements d’objet Dataverse et prend en charge la modification de ces enregistrements. Cet article décrit comment enregistrer un assemblage de plug-in et le traitement des messages étape, ajouter un assemblage à une solution et effectuer d’autres opérations courantes liées aux plug-ins à 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 accéder aux informations sur les assemblages et les étapes de plug-in enregistrés dans Power Apps et dans la vue d’assemblage PRT. Pour accéder aux informations sur les plug-ins dans Power Apps, choisissez Solutions dans le volet de navigation de gauche, puis choisissez une solution disponible dans la liste. Ensuite, choisissez Assemblages de plug-ins ou Étapes 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. Plus d’informations : Ajoutez étape à la solution
Enregistrement d’étape
L’enregistrement d’un traitement de message étape informe Dataverse dans quelles conditions votre plug-in doit s’exécuter, et comment l’exécuter. Par conditions, nous faisons référence à l’opération de table et de message en cours de traitement par Dataverse. D’autres options de configuration telles que l’exécution synchrone ou asynchrone, avant ou après l’opération principale, et plus encore peuvent être spécifiées lors de l’enregistrement étape. Ces options de configuration d’exécution sont détaillées dans la section suivante.
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.
Champs d’information sur la configuration générale
| Champ | Description |
|---|---|
| Message | Le message qui, lorsqu’il est traité par Dataverse , entraîne l’exécution du plug-in. Si une entité principale n’est pas spécifiée pour les messages principaux tels que |
| Entité principale | L’entité (table) qui, lorsqu’elle est traitée par Dataverse , entraîne l’exécution du plug-in. Les messages ont un |
| 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 | Pour les messages Update, OnExternalUpdated ou autres, lorsque vous définissez l’entité principale, le filtrage des attributs (colonnes) limite l’exécution du plug-in aux cas où les colonnes spécifié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 renseignée dans le PRT en fonction du nom de l’assembly et de la classe du plug-in. |
| Nom de l’étape | Le nom du traitement des messages é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 et le même message. Le numéro dans ce champ détermine l’ordre dans lequel les étapes sont appliquées au sein d’une étape, du plus bas au plus élevé. Vous devez définir ceci pour contrôler l’ordre dans lequel les plug-ins sont exécutés dans la même étape. 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, la même table et le même message) n’est pas garanti et peut être aléatoire. |
| Description | Une description pour le é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. Le préfixe "Pre" et "Post" fait référence à ce qui se passe avant ou après l’opération principale (core). Dataverse L’opération principale est l’étape au cours de laquelle la combinaison du message et de l’entité est traitée.
| 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 la file d’attente des tâches du système, qui s’exécutera quelque temps après la fin de l’opération principale. |
| 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ù les plug-ins enregistrés pour l’événement Mise à jour 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 principale. 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
Updatequi 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 :
- 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é.
- Choisissez le nœud de l’étape, puis Mettre à jour dans le menu contextuel ou dans la barre d’outils.
- Choisissez un utilisateur dans la liste déroulante des utilisateurs disponibles à côté de l’étiquette Exécuter dans le contexte de l’utilisateur.
- 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 :
- 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é.
- 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.
Dans Power Apps, désactivez ou activez les étapes du plug-in à l’aide des options "Désactiver" et "Activer" du étape choisi. Vous pouvez accéder aux options étape en accédant d’abord à Solutions, en choisissant une solution, puis dans le volet de gauche Objets en choisissant Étapes du plug-in.
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
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é).