Démarrage rapide : créer un plug-in à l’aide de Power Platform Tools

  • Article

Cet article fournit des informations sur la création d’un plug-in à l’aide de l’extension Power Platform Tools pour Visual Studio.

Conditions préalables

Créer une solution avec une bibliothèque de plug-ins

Suivez ces instructions pour créer une solution pour la bibliothèque de plug-ins, connectez-vous à votre environnement Power Platform et inscrivez des assemblys de code personnalisés, des étapes, etc.

  1. Utilisez l’extension Power Platform Tools pour Visual Studio pour créer une solution avec une bibliothèque de plug-ins. Pour obtenir des instructions, accédez à l’article Créer un projet Power Platform Tools dans le guide du développeur de Power Platform.

    Si vous avez déjà une solution en place, suivez alors ces instructions dans Ajouter un nouveau projet à une solution Power Platformdans le guide du développeur Power Platform pour ajouter un projet de bibliothèque de plug-ins à la solution à l’aide du modèle Power Platform Tools.

  2. Dans le menu Tools, sélectionnez Se connecter à Dataverse.

  3. Sélectionnez les options souhaitées dans la boîte de dialogue et sélectionnez Connexion.

  4. Sélectionnez une solution existante ou la solution Par défaut. La solution contiendra votre plug-in enregistré et vos assemblys activité de workflow pour une distribution ultérieure vers d’autres environnements.

  5. Quand vous avez terminé, cliquez sur Terminé.

L’Explorateur Power Platform s’affiche, ou vous pouvez ouvrir cette vue à partir du menu Vue. Développez les nœuds pour voir les types de données d’environnement que vous pouvez afficher. Cliquez avec le bouton droit sur les nœuds pour voir quelles options sont disponibles.

Notes

La vue Explorateur Power Platform de l’extension Power Platform Tools peut faire davantage qu’inscrire des plug-ins et des activités de workflow. La documentation des fonctionnalités supplémentaires sera fournie dans une future version de la documentation. N’hésitez pas à les explorer en attendant.

Inscrire une étape de plug-in avec Dataverse

Suivez ces instructions pour inscrire une étape de plug-in (également appelée étape de traitement de message de SDK). L’étape identifie la table de données et l’événement qui entraînent l’exécution de votre plug-in. Pour plus d’informations : Infrastructure d’événements, Inscrire une étape de plug-in

  1. Sélectionnez Afficher > Explorateur Power Platform, développez votre nœud d’environnement et le sous-nœud Tables.

  2. Cliquez avec le bouton droit sur le type de table (par exemple, « Compte ») sur lequel l’étape doit être inscrite, puis sélectionnez Créer un plug-in.

    Créer un plug-in.

    Notes

    Vous pouvez également créer un plug-in en développant Catalogue d’événements ; cliquez avec le bouton droit sur un événement professionnel et choisissez Ajouter un plug-in.

  3. Renseignez les informations de la boîte de dialogue Inscrire une nouvelle étape et choisissez Inscrire une nouvelle étape lorsque vous avez terminé.

    Le nom de classe que vous spécifiez lors du remplissage des informations sur l’étape est utilisé pour nommer votre nouvelle classe de plug-in. La classe est placée dans la bibliothèque de projets de plug-in spécifiée par le champ de la boîte de dialogue Assembly de gestionnaire. S’il n’y a qu’un seul projet de bibliothèque de plug-ins dans la solution, le champ Assembly de gestionnaire est inactif.

Une nouvelle inscription d’étape a été ajoutée à la solution. Cependant, vous devrez créer et déployer votre bibliothèque de plug-ins avant que l’assembly de plug-in et l’étape ne soient ajoutés à l’environnement et à la solution Dataverse spécifiés.

Ajouter une autre classe de plug-in à la bibliothèque

Supposons que vous ayez suivi les étapes ci-dessus pour créer une classe de plug-in dans la bibliothèque du projet de plug-in et ajouté une étape. Vous souhaitez maintenant ajouter une autre classe de plug-in à cette même bibliothèque. Comment devez-vous procéder ? Vous avez deux options, les deux utilisent les menus contextuels de l’extension des Power Platform Tools.

  1. La première méthode consiste à procéder comme ci-dessus en développant le nœud Table dans la vue Explorateur Power Platform, en cliquant avec le bouton droit sur un type de table, puis en sélectionnant Créer un plug-in. Lors de l’enregistrement de l’étape, spécifiez la même bibliothèque de projet de plug-in dans l’Assembly de gestionnaire, et le nouveau nom de classe dans le champ de formulaire Nom de classe.

  2. Pour la deuxième méthode, supposons que vous ayez déjà généré et déployé l’assembly de bibliothèque de plug-ins sur l’environnement Dataverse. Dans ce cas, vous verrez l’assembly déployé et l’étape que vous avez créée après avoir actualisé la vue de l’explorateur et développé le nœud Assembly de plug-in. À ce stade, vous pouvez simplement cliquer avec le bouton droit sur le nœud d’assembly cible et sélectionner Ajouter un plug-in. Cela affichera le formulaire d’enregistrement des étapes que vous pouvez maintenant remplir pour votre nouvelle classe de plug-in.

Ensuite, créez et déployez le projet de bibliothèque de plug-ins pour mettre à jour l’environnement et la solution cibles.

Ajouter une étape de plug-in

Vous pouvez ajouter une étape pour un plug-in enregistré existant que vous possédez. Pour ce faire, développez le nœud d’assemby de plug-in cible dans la vue Explorateur Power Platform pour afficher le plug-in enregistré. Cliquez avec le bouton droit sur le nœud du plug-in et sélectionnez Ajouter une étape. Remplissez le formulaire Enregistrer une nouvelle étape.

Vous n’avez pas besoin de créer et de déployer le projet de plug-in pour que l’enregistrement de l’étape soit disponible dans l’environnement et la solution cibles.

La classe abstraite PluginBase

La classe PluginBaseest générée automatiquement à partir du modèle de bibliothèque de plug-ins. Votre classe de plug-in personnalisée doit dériver de cette classe de base. La classe de base implémente un code de plug-in commun qui vous aide à gagner plus vite en productivité. Jetez un œil au code de la classe PluginBase dans votre projet de plug-in pour voir ce qu’il fait.

Code de la classe de plug-in générée

Le modèle de bibliothèque de plug-ins fournit la classe abstraite PluginBase. Votre plug-in doit dériver de la classe PluginBase s’il doit fonctionner harmonieusement avec l’extension Power Platform Tools. Vous trouverez ci-dessous la classe dérivée générée lors de la création d’un plug-in à partir de l’Explorateur Power Platform. Vous devez généralement ajouter votre code là où se trouvent les commentaires TODO. Notez que la méthode Execute de l’interface Iplugin standard a été remplacée par ExecuteCdsPlugin dans le code du plug-in.

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

namespace PPTools_Sample_Solution.NotifyPlugin
{    
    public class NotifyAccountCreate: PluginBase
    {
        public NotifyAccountCreate(string unsecure, string secure)
            : base(typeof(NotifyAccountCreate))
        {
           // TODO: Implement your custom configuration handling.
        }

        protected override void ExecuteCdsPlugin(LocalPluginContext localContext)
        {
            if (localContext == null)
            {
                throw new InvalidPluginExecutionException(nameof(localContext));
            }           
            ITracingService tracingService = localContext.TracingService;

            try
            {  
                IPluginExecutionContext context = (IPluginExecutionContext)localContext.PluginExecutionContext;
 
                IOrganizationService service = localContext.OrganizationService;

                // TODO: Implement your custom Plug-in business logic.

            }
            catch (Exception ex)
            {
                tracingService?.Trace("An error occurred executing Plugin PPTools_Sample_Solution.NotifyPlugin.NotifyAccountCreate : {0}", ex.ToString());
                throw new InvalidPluginExecutionException("An error occurred executing Plugin PPTools_Sample_Solution.NotifyPlugin.NotifyAccountCreate .", ex);
            }
        }
    }
}

À ce stade, vous devez ajouter votre code de plug-in personnalisé à l’endroit indiqué par les commentaires de code TODO. Pour plus d’informations, lisez certaines des rubriques connexes : Transmettre des données de configuration à votre plug-in, Présentation du contexte d’exécution, et Suivi et journalisation.

Important

Nous vous encourageons à utiliser les menus contextuels des Power Platform Tools. Lorsque vous utilisez les menus contextuels de l’Explorateur Power Platform pour ajouter des plug-ins, les classes sont générées à l’aide des informations fournies et les entrées de déploiement dans le fichier RegisterFile.crmregister du projet CrmPackage sont conservées. Ce sont ces informations qui sont utilisées pour le déploiement des assemblys, des plug-ins et des étapes.

Signer l’assembly

Tous les assemblys de plug-in et de workflow personnalisés doivent être signés numériquement avant d’être chargés sur le serveur Dataverse. Pour signer l’assembly, procédez comme suit.

  1. Sélectionnez le plug-in ou le projet d’activité de workflow dans l’Explorateur de solution.

  2. Choisissez Projet > <project name> Propriétés pour modifier les propriétés du projet.

  3. Sur l’onglet Signature, cochez la case Signer l’assembly, puis spécifiez un fichier de clé de nom fort.

Déployer le plug-in dans la solution de l’environnement

Une fois que vous avez terminé de modifier le code et que vous êtes prêt à déployer l’assembly et les étapes de plug-in dans votre environnement, procédez comme suit.

  1. Créez la bibliothèque de plug-ins.

  2. Cliquez avec le bouton droit sur le projet de bibliothèque de plug-ins dans l’Explorateur de solutions.

  3. Sélectionnez Déployer dans le menu contextuel.

Conseil

Vous pouvez déployer tous les projets dans la solution Visual Studio en cliquant avec le bouton droit sur le projet CrmPackage et en choisissant Déployer.

Une fois le déploiement terminé, sélectionnez l’icône d’actualisation dans l’Explorateur Power Platform. Développez le sous-nœud Assemblys de plug-in de votre nœud d’environnement pour voir votre assembly inscrit. Cliquez avec le bouton droit sur l’assembly de plug-in et accédez à l’Explorateur Power Platform pour voir quelles opérations sont prises en charge. La sélection de Supprimer l’assembly annulera l’enregistrement de l’assembly et de ses étapes associées.

Ajouter une image d’entité

Les images d’entité sont des instantanés de données d’entité avant ou après l’opération principale (par exemple : une création ou une mise à jour). Vous pouvez (éventuellement) ajouter des images d’entité aux étapes du plug-in en utilisant la vue Explorateur Power Platform. Pour ajouter une image à une étape dans la vue Explorateur Power Platform, développez l’arborescence de nœuds Assemblys de plug-in pour afficher l’étape du plug-in cible, puis cliquez avec le bouton droit sur l’étape pour afficher le menu contextuel et choisissez Ajouter une image.

Ajouter un image à une étape.

Vous pouvez également ajouter une image dans la vue Explorateur Power Platform sous Catalogue d’événements sur une étape d’un plug-in d’événement.

Ajouter un image à une étape d’événement.

Après avoir sélectionné Ajouter une image dans le menu contextuel, remplissez le formulaire qui apparaît.

Définir une image d’entité.

Dans le formulaire, Avant image/Après image spécifie les données d’entité telles qu’elles existent avant ou après l’opération principale. Le champ Nom définit le nom logique de l’entité pour laquelle vous souhaitez obtenir les données. Alias d’entité est l’index nommé que vous utiliserez dans votre code pour identifier la ligne de la table image qui contient les données de l’entité cible. Paramètres est la liste des colonnes de données d’entité que vous souhaitez. Spécifiez uniquement les colonnes dont vous avez besoin, car les performances du plug-in seront réduites si vous spécifiez trop de colonnes.

Pour plus d’informations : Définir les images d’entité.

Étapes suivantes

En savoir plus sur le développement de plug-ins

Étape suivante

Fournir des commentaires sur l’outil

Vous pouvez envoyer des commentaires sur l’outil à Microsoft en utilisant l’icône de commentaires dans la vue de l’Explorateur Power Platform.

Fournir des commentaires.

Voir aussi

Power Platform Tools pour Visual Studio

Créer un projet Power Platform Tools

Didacticiel : Déboguer un plug-in

Infrastructure d’événement

Utiliser des plug-ins pour étendre les processus d’entreprise

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