Exercice : écrire votre premier plug-in

  • 30 minutes

Dans ce scénario, une organisation doit s’assurer que les données de numéro de téléphone sont saisies dans un format cohérent. Pour atteindre cet objectif, vous allez créer un plug-in à exécuter lors de la création/mise à jour qui supprime tous les caractères non numériques d’un numéro de téléphone avant de l’enregistrer dans Dataverse. Vous allez ensuite créer un autre plug-in qui s’exécutera sur Contact retrieve/retrievemultiple pour remettre en forme le numéro de téléphone afin d’y inclure des parenthèses et des tirets, si les données existent. 

Exercice 1 : créer/mettre à jour un plug-in

Dans cet exercice, vous allez créer un plug-in qui s’exécutera lors de la création et de la mise à jour. Ce plug-in supprime tous les caractères non numériques d’un numéro de téléphone.

Chaque exercice se compose d’un scénario et d’objectifs d’apprentissage. Le scénario décrit l’objectif des exercices, tandis que les objectifs sont répertoriés sous la forme d’une liste à puces.

Remarque

Si vous ne disposez pas des outils de Kit de développement logiciel (SDK) Dynamics 365, consultez Téléchargement d’outils à partir de NuGet pour les télécharger.

Tâche 1 : créer un plug-in

  1. Démarrez Visual Studio 2022.

  2. Cliquez sur Fichier > Nouveau > Projet.

  3. Sélectionnez Bibliothèque de classes (.NET Framework) et cliquez sur Suivant.

    Capture d’écran de la bibliothèque de classes.

  4. Saisissez D365PackageProject pour Nom du projet, sélectionnez un emplacement pour enregistrer le projet, sélectionnez .NET Framework 4.6.2 pour Infrastructure, puis cliquez sur Créer.

    Capture d’écran de la fenêtre Configurer votre nouveau projet.

  5. Cliquez avec le bouton droit sur le projet et sélectionnez Gérer les packages NuGet.

    Capture d’écran de l’option Gérer les packages NuGet sélectionnée.

  6. Cliquez sur l’onglet Parcourir, recherchez et sélectionnez microsoft.crmsdk.coreassemblies, puis cliquez sur Installer.

    Capture d’écran du bouton Installer.

  7. Lisez les termes du contrat de licence, puis cliquez sur J’accepte si vous êtes d’accord.

  8. Fermez le gestionnaire de packages NuGet.

  9. Cliquez avec le bouton droit sur Class1.cs et sélectionnez Supprimer.

  10. Cliquez avec le bouton droit sur le projet et sélectionnez Ajouter > Classe.

  11. Nommez la nouvelle classe PreOperationFormatPhoneCreateUpdate et cliquez sur Ajouter.

    Capture d’écran du nom de la nouvelle classe.

  12. Ajoutez les instructions d’utilisation à la nouvelle classe comme suit :

     using Microsoft.Xrm.Sdk;

 using System.Text.RegularExpressions;

  13. Rendez la classe publique et implémentez l’interface IPlugin.

    Capture d’écran de la classe notée comme publique et de l’interface iplugin.

  14. Implémentez le membre d’interface.

    Capture d’écran du membre d’interface implémenté.

    Votre classe devrait maintenant ressembler à l’image suivante :

    Capture d’écran de l’exemple de classe.

Tâche 2 : mettre en forme un numéro de téléphone

  1. Obtenez le contexte d’exécution auprès du prestataire de services. Remplacez l’exception dans la méthode Execute par l’extrait de code suivant.

     IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

  2. Vérifiez le paramètre d’entrée pour Cible. Ajoutez l’extrait de code suivant à la fin de la méthode Execute.

     if (!context.InputParameters.ContainsKey("Target"))

 throw new InvalidPluginExecutionException("No target found");

  3. Ajoutez l’extrait de code suivant à la fin de la méthode Execute. Cet extrait de code récupère l’entité cible à partir du paramètre d’entrée, puis vérifie si ses attributs comportent telephone1 (téléphone professionnel pour les contacts, téléphone pour les comptes).

     var entity = context.InputParameters["Target"] as Entity;

 if (!entity.Attributes.Contains("telephone1"))

 return;

  4. Ajoutez l’extrait de code suivant à la fin de la fonction Execute. Cet extrait de code supprime tous les caractères non numériques du numéro de téléphone fourni par l’utilisateur.

     string phoneNumber = (string)entity["telephone1"];

 var formattedNumber = Regex.Replace(phoneNumber, @"[^\d]", "");

  5. Définissez telephone1 sur le numéro de téléphone mis en forme. Ajoutez l’extrait de code suivant à la fin de la méthode Execute.

     entity["telephone1"] = formattedNumber;

    La méthode Execute devrait maintenant ressembler à l’image suivante :

    Capture d’écran de la méthode execute.

  6. Cliquez avec le bouton droit sur le projet et sélectionnez Propriétés.

    Capture d’écran des propriétés.

  7. Cliquez sur l’onglet Signature, cochez la case intitulée Signer l’assembly et cliquez sur Nouveau fichier de clé.

    Capture d’écran du nouveau fichier de clé.

  8. Saisissez contoso.snk dans le champ Nom du fichier de clé, décochez la case Protéger mon fichier de clé par un mot de passe, puis cliquez sur OK.

    Capture d’écran du champ Nom du fichier de clé.

  9. Fermez l’onglet Propriétés.

  10. Créez le projet et assurez-vous que la création réussit.

Tâche 3 : enregistrer un plug-in et procédure

Remarque

Si vous ne disposez pas des outils de Kit de développement logiciel (SDK) Dynamics 365, consultez Téléchargement d’outils à partir de NuGet pour les télécharger.

  1. Démarrez l’application Plugin Registration Tool.

  2. Cliquez sur Créer une connexion.

    Capture d’écran du bouton Créer une connexion.

  3. Sélectionnez Office 365, cochez la case Afficher les options avancées, fournissez vos informations d’identification, puis cliquez sur Connexion.

    Capture d’écran des détails de connexion.

  4. Cliquez sur Enregistrer, puis sur Enregistrer un nouvel assembly.

    Capture d’écran du bouton Enregistrer un nouvel assembly.

  5. Cliquez sur Parcourir.

    Capture d’écran du bouton Parcourir.

  6. Accédez au dossier Bin > Debug dans la bibliothèque de classes que vous avez créée, sélectionnez D365PackageProject.dll, puis cliquez sur Ouvrir.

    Capture d’écran de la bibliothèque de classes sélectionnée avec le bouton Ouvrir.

  7. Cliquez sur Enregistrer les plug-ins sélectionnés.

    Capture d’écran du bouton Enregistrer les plug-ins sélectionnés.

  8. Cliquez sur OK.

  9. Développez l’assembly nouvellement enregistré.

    Capture d’écran de l’assembly développé.

  10. Cliquez avec le bouton droit sur le plug-in et sélectionnez Enregistrer une nouvelle étape.

    Capture d’écran de l’option Enregistrer une nouvelle étape.

  11. Sélectionnez Créer pour Message et contact pour Entité principale.

    Capture d’écran de l’option contact définie comme Entité principale.

  12. Sélectionnez PreOperation pour Phase d’exécution du pipeline d’événements, puis cliquez sur Enregistrer une nouvelle étape.

    Capture d’écran du champ Phase d’exécution du pipeline d’événements défini sur PreOperation.

  13. Cliquez sur Fermer.

  14. Cliquez avec le bouton droit sur le plug-in et sélectionnez de nouveau Enregistrer une nouvelle étape.

    Capture d’écran de l’option Enregistrer une nouvelle étape à nouveau.

  15. Sélectionnez Mettre à jour pour Message, contact pour Entité principale, puis la recherche Attributs.

    Capture d’écran de la recherche Attributs.

  16. Décochez la case Sélectionner tout, cochez la case Téléphone professionnel, puis cliquez sur OK.

    Capture d’écran de la vue de sélection des attributs.

  17. Sélectionnez PreOperation pour Phase d’exécution du pipeline d’événements, puis cliquez sur Enregistrer une nouvelle étape.

Tâche 4 : tester le plug-in

  1. Accédez à Maker Portal et vérifiez que l’environnement approprié est sélectionné.

  2. Cliquez sur Applications et lancez l’application Collecte de fonds.

    Capture d’écran de l’application Collecte de fonds sélectionnée.

  3. Cliquez sur Tableau de bord, puis ouvrez l’un des contacts.

    Capture d’écran du tableau de bord.

  4. Cliquez sur + Nouveau.

    Capture d’écran du bouton + Nouveau permettant de créer un contact.

  5. Saisissez Test pour Prénom, Contact pour Nom et (123)-555-0100 pour Téléphone professionnel, puis cliquez sur Enregistrer.

    Capture d’écran du bouton Enregistrer permettant d’enregistrer un contact.

    L’enregistrement devrait être enregistré et le champ Téléphone professionnel devrait afficher uniquement les valeurs numériques.

    Capture d’écran du numéro de téléphone professionnel.

  6. Redéfinissez le champ Téléphone professionnel sur 001-123-555-0100 et attendez quelques secondes.

    L’enregistrement devrait être mis à jour et le champ Téléphone professionnel devrait afficher uniquement les valeurs numériques.

    Capture d’écran des valeurs numériques du champ Téléphone professionnel.

Exercice 2 : créer/récupérer plusieurs plug-ins

Dans cet exercice, vous allez créer un plug-in qui s’exécutera sur retrieve et retrieve multiple. Ce plug-in ajoute des parenthèses et des tirets aux numéros de téléphone.

Chaque exercice se compose d’un scénario et d’objectifs d’apprentissage. Le scénario décrit l’objectif des exercices, tandis que les objectifs sont répertoriés sous la forme d’une liste à puces.

Tâche 1 : créer un plug-in

  1. Démarrez Visual Studio.

  2. Ouvrez le projet que vous avez créé dans l’exercice 1.

  3. Cliquez avec le bouton droit sur le projet et sélectionnez Ajouter > Classe.

    Capture d’écran du menu Ajouter avec l’option Classe sélectionnée.

  4. Dans le champ Nom, saisissez PostOperationFormatPhoneOnRetrieveMultiple pour la classe, puis cliquez sur Ajouter.

  5. Ajoutez les instructions d’utilisation à la nouvelle classe comme suit :

     using Microsoft.Xrm.Sdk;

  6. Rendez la classe publique et implémentez l’interface IPlugin.

  7. Implémentez le membre d’interface. Votre classe devrait maintenant ressembler à l’image suivante :

    Capture d’écran de la classe avec le membre d’interface implémenté.

Tâche 2 : mettre en forme le numéro de téléphone à récupérer

  1. Obtenez le contexte d’exécution auprès du prestataire de services. Remplacez l’exception dans la méthode Execute par l’extrait de code suivant.

     IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

  2. Vérifiez si le nom du message est Retrieve ou RetrieveMultiple. Ajoutez l’extrait de code suivant à la fin de la méthode Execute.

     if (context.MessageName.Equals("Retrieve"))	
 {

 }	
 else if(context.MessageName.Equals("RetrieveMultiple"))	
 {

 }

  3. Vérifiez que les paramètres de sortie comportent une entité commerciale et qu’il s’agit d’un type d’entité. Collez l’extrait de code suivant dans la condition if retrieve.

     if (!context.OutputParameters.Contains("BusinessEntity") && context.OutputParameters["BusinessEntity"] is Entity)
 throw new InvalidPluginExecutionException("No business entity found");

  4. Obtenez l’entité et vérifiez si elle contient le champ telephone1. Ajoutez l’extrait de code suivant dans la condition if retrieve.

     var entity = (Entity)context.OutputParameters["BusinessEntity"];

 if (!entity.Attributes.Contains("telephone1"))	
     return;

  5. Ajoutez l’extrait de code suivant à la condition if retrieve. Cet extrait de code tente d’analyser telephone1 comme long et reviendra si l’analyse ne réussit pas.

     if (!long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))

 return;

  6. Mettez en forme le numéro de téléphone en ajoutant des parenthèses et des tirets. Ajoutez l’extrait de code suivant dans la condition if retrieve.

     var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
 entity["telephone1"] = formattedNumber;

La partie retrieve de la méthode Execute devrait maintenant ressembler à l’image suivante :

Capture d’écran de la partie retrieve de la méthode Execute.

Tâche 3 : mettre en forme le numéro de téléphone pour retrieve multiple

  1. Ajoutez l’extrait de code suivant dans la condition retrieve multiple. Cet extrait de code vérifiera si les paramètres de sortie comportent BusinessEntityCollection et s’ils sont du type EntityCollection.

     if(!context.OutputParameters.Contains("BusinessEntityCollection") && context.OutputParameters ["BusinessEntityCollection"] is EntityCollection)
     throw new InvalidPluginExecutionException("No business entity collection found");

  2. Obtenez la collection d’entités à partir des paramètres de sortie. Ajoutez l’extrait de code suivant dans la condition retrieve multiple.

     var entityCollection = (EntityCollection)context.OutputParameters["BusinessEntityCollection"];

  3. Parcourez chaque entité de la collection d’entités.

     foreach (var entity in entityCollection.Entities)	
 {

 }

  4. Ajoutez l’extrait de code suivant dans la condition foreach. Cet extrait de code aura la même fonction que la condition retrieve.

     if (entity.Attributes.Contains("telephone1") && entity["telephone1"] != null)
 {
    if (long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
    {
        var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
        entity["telephone1"] = formattedNumber;
    }
 }

    La partie retrieve multiple de la méthode Execute devrait maintenant ressembler à l’image suivante :

    Capture d’écran de l’extrait de code de la condition de récupération multiple terminée.

  5. Recréez le projet et assurez-vous que la création réussit.

Tâche 4 : mettre à jour un assembly de plug-in et enregistrer les étapes

  1. Démarrez Plug-in Registration Tool et cliquez sur Créer une connexion.

    Capture d’écran du bouton Créer une connexion.

  2. Sélectionnez Office 365, cliquez sur Afficher les options avancées, fournissez vos informations d’identification, puis cliquez sur Connexion.

  3. Sélectionnez l’assembly que vous avez enregistré dans l’exercice 1, puis cliquez sur Mettre à jour.

    Capture d’écran du bouton Mettre à jour.

  4. Cliquez sur Parcourir.

  5. Accédez au dossier debug de votre projet, sélectionnez D365PackageProject.dll, puis cliquez sur Ouvrir.

    Capture d’écran du fichier d’assembly sélectionné.

  6. Sélectionnez les plug-ins, puis cliquez sur Mettre à jour les plug-ins sélectionnés.

    Capture d’écran du bouton Mettre à jour les plug-ins sélectionnés.

  7. Cliquez sur OK.

  8. Cliquez avec le bouton droit sur le nouveau plug-in et sélectionnez Enregistrer une nouvelle étape.

  9. Sélectionnez Retrieve pour Message, contact pour Entité principale, puis PostOperation pour Phase d’exécution du pipeline d’événements. Assurez-vous que Synchrone est sélectionné pour Mode d’exécution, puis cliquez sur Enregistrer une nouvelle étape.

    Capture d’écran du mode d’exécution.

  10. Cliquez avec le bouton droit sur le plug-in et sélectionnez de nouveau Enregistrer une nouvelle étape.

  11. Sélectionnez RetrieveMultiple pour Message, contact pour Entité principale, puis PostOperation pour Phase d’exécution du pipeline d’événements. Assurez-vous que Synchrone est sélectionné pour Mode d’exécution, puis cliquez sur Enregistrer une nouvelle étape.

Tâche 5 : tester le plug-in

  1. Accédez à Maker Portal et vérifiez que vous vous trouvez dans l’environnement approprié.

  2. Cliquez sur Applications. Ensuite, sélectionnez l’application Collecte de fonds, puis cliquez sur Modifier. Vous allez ajouter la table Contact à l’application.

    Capture d’écran du bouton Modifier.

  3. Cliquez sur le bouton + Nouvelle page.

  4. Sélectionnez Table Dataverse, puis cliquez sur Suivant.

  5. Sélectionnez Table existante. Ensuite, sélectionnez la table Contact, puis cliquez sur Ajouter.

    Capture d’écran du bouton Nouvelle page.

  6. Cliquez sur Lire.

    Capture d’écran du bouton Lire.

  7. Cliquez sur Enregistrer et continuer.

  8. Recliquez sur Lire.

  9. Cliquez sur Contacts.

  10. Les enregistrements existants non enregistrés avec le nouveau format ne changeront pas. Cliquez sur + Nouveau.

    Capture d’écran des contacts avec la colonne Téléphone professionnel mise en évidence.

  11. Fournissez les informations suivantes, puis cliquez sur Enregistrer. L’enregistrement devrait être enregistré et le plug-in devrait appliquer le nouveau format.

  12. Recliquez sur Contacts. L’enregistrement que vous avez créé devrait respecter le nouveau format.

    Capture d’écran de l’enregistrement avec le nouveau format.

  13. Cliquez sur l’un des contacts existants pour l’ouvrir.

    Capture d’écran de l’ouverture d’un contact existant.

  14. Modifiez le champ Téléphone professionnel comme suit :

    Capture d’écran de l’étape de modification du champ Téléphone professionnel.

  15. Cliquez sur Enregistrer. Le nouveau format devrait être appliqué. Recliquez encore une fois sur Contacts.

    Capture d’écran des contacts.

Le numéro de téléphone modifié devrait respecter le nouveau format.

Capture d’écran du numéro de téléphone modifié avec le nouveau format.