Didacticiel : Écrire et enregistrer un plug-in

Ce didacticiel vous guide tout au long de l’écriture d’un plug-in et de son enregistrement dans Microsoft Dataverse. Vous devez d’abord lire l’article Écrire un plug-in pour vous familiariser avec l’écriture d’un plug-in.

Vous trouverez les fichiers complets de la solution du plug-in pour ce didacticiel ici : Exemple : Créer un plug-in de base.

Objectif

Créez un plug-in asynchrone enregistré dans le message « Créer » de la table de compte. Le plug-in crée une activité de tâche qui rappelle au créateur du compte d’effectuer un suivi une semaine plus tard.

Conditions préalables

• Un compte d’utilisateur système avec le rôle Administrateur système ou Personnalisateur du système dans l’environnement Microsoft Dataverse cible.
• Une application basée sur un modèle qui comprend les tables Account et Task.
  • Si vous ne disposez pas d’une application pilotée par modèle contenant ces tables, consultez Générer votre première application pilotée par modèle entièrement pour connaître les étapes pour en créer une en quelques minutes.
• Visual Studio 2019 (ou une version ultérieure).
• Des connaissances sur le langage de programmation Visual C#.
• Plug-in Registration Tool installé sur l’ordinateur de développement. Consultez Outils de développement Dataverse.

Créer un projet de plug-in

Cet article montre comment utiliser Visual Studio pour écrire le plug-in et générer l’assembly. Cependant, vous pouvez utiliser votre éditeur favori pour le codage et utiliser MSBuild pour générer l’assembly. Dans les deux cas, vous devez utiliser Plug-in Registration Tool pour enregistrer le plug-in dans Dataverse.

Sinon, vous pouvez utiliser Power Platform CLI pour créer rapidement un nouveau projet avec un code de plug-in standard à l’aide de la commande pac plugin init. Vous utiliseriez toujours Plug-in Registration Tool pour enregistrer le plug-in dans Dataverse.

Une autre alternative consiste à utiliser l’extension Power Platform Tools comme décrit ici : Créer et enregistrer un package de plug-in à l’aide de Visual Studio. Dans ce cas, l’extension peut créer et enregistrer le plug-in afin que Plug-in Registration Tool ne soit pas nécessaire.

Créer un projet Visual Studio pour le plug-in

1. Ouvrez Visual Studio et ouvrez un nouveau projet Bibliothèque de classes (.NET Framework) à partir de .NET Framework 4.6.2

   

   Le nom utilisé pour le projet est également le nom de l’assembly. Ce didacticiel utilise le nom BasicPlugin.

2. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet et sélectionnez Gérer les packages NuGet... dans le menu contextuel.

   

3. Sélectionnez Parcourir, recherchez Microsoft.CrmSdk.CoreAssemblies et installez la dernière version.

   

4. Vous devez cliquer sur J’accepte dans la boîte de dialogue Acceptation de la licence.

   Notes

   L’ajout du package Microsoft.CrmSdk.CoreAssembliesNuGet inclura ces assemblys dans le dossier de génération de votre assembly, mais vous ne chargerez pas ces assemblys avec l’assembly qui inclut votre logique. Ces assemblys sont déjà présents dans l’environnement bac à sable d’exécution.

   N’incluez aucun autre package NuGet ou assembly dans le dossier de construction de votre projet. Vous ne pouvez pas inclure ces assemblys lorsque vous inscrivez l’assembly avec votre logique. Vous ne pouvez pas supposer que les assemblys autres que ceux inclus dans le package Microsoft.CrmSdk.CoreAssembliesNuGet package est présent sur le serveur et compatible avec votre code.

5. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le fichier Class1.cs et sélectionnez Renommer dans le menu contextuel.

   

6. Renommez le fichier Class1.cs en FollowupPlugin.cs.

7. Lorsque vous y êtes invité, autorisez Visual Studio à renommer la classe pour correspondre au nom du fichier.

   

Modifier le fichier de classe pour définir un plug-in

1. Ajoutez les instructions using suivantes en haut du fichier FollowupPlugin.cs.

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

2. Implémentez l’interface IPlugin en modifiant la classe.

   Notes

   Si vous tapez simplement : IPlugin après le nom de la classe, Visual Studio suggérera automatiquement d’implémenter un stub pour la méthode Execute.

   public class FollowupPlugin : IPlugin
   {
       public void Execute(IServiceProvider serviceProvider)
       {
           throw new NotImplementedException();
       }
   }
   

3. Remplacez le contenu de la méthode Execute par le code suivant.

// Obtain the tracing service
ITracingService tracingService =
(ITracingService)serviceProvider.GetService(typeof(ITracingService));

// Obtain the execution context from the service provider.  
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

// The InputParameters collection contains all the data passed in the message request.  
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the input parameters.  
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the IOrganizationService instance which you will need for  
    // web service calls.  
    IOrganizationServiceFactory serviceFactory =
        (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
    IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

    try
    {
        // Plug-in business logic goes here.  
    }

    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw new InvalidPluginExecutionException("An error occurred in FollowUpPlugin.", ex);
    }

    catch (Exception ex)
    {
        tracingService.Trace("FollowUpPlugin: {0}", ex.ToString());
        throw;
    }
}

À propos du code

• L’interface ITracingService permet d’écrire dans le journal de suivi. Vous trouverez un exemple dans le bloc catch final. Pour plus d’informations, voir : Utiliser le suivi
• L’interface IPluginExecutionContext donne accès au contexte pour l’événement qui a exécuté le plug-in. Pour plus d’informations : Comprendre le contexte d’exécution.
• Le code vérifie que le contexte InputParameters contient les paramètres attendus pour l’interface CreateRequest pour laquelle ce plug-in est enregistré. Si la propriété Target est présente, le paramètre Entity transmis à la requête est disponible.
• L’interface IOrganizationServiceFactory donne accès à une variable de service qui implémente l’interface IOrganizationService, qui fournit les méthodes que vous utiliserez pour interagir avec le service pour créer la tâche.

Ajouter une logique métier

Le plug-in crée une activité de tâche qui rappelle au créateur du compte d’effectuer un suivi une semaine plus tard.

Ajoutez le code suivant au bloc try. Remplacez le commentaire // Plug-in business logic goes here par le code suivant.

// Create a task activity to follow up with the account customer in 7 days. 
Entity followup = new Entity("task");

followup["subject"] = "Send e-mail to the new customer.";
followup["description"] =
    "Follow up with the customer. Check if there are any new issues that need resolution.";
followup["scheduledstart"] = DateTime.Now.AddDays(7);
followup["scheduledend"] = DateTime.Now.AddDays(7);
followup["category"] = context.PrimaryEntityName;

// Refer to the account in the task activity.
if (context.OutputParameters.Contains("id"))
{
    Guid regardingobjectid = new Guid(context.OutputParameters["id"].ToString());
    string regardingobjectidType = "account";

    followup["regardingobjectid"] =
    new EntityReference(regardingobjectidType, regardingobjectid);
}

// Create the task in Microsoft Dynamics CRM.
tracingService.Trace("FollowupPlugin: Creating the task activity.");
service.Create(followup);

À propos du code

• Ce code utilise le style à liaison tardive pour créer une tâche et l’associer au compte créé. Pour plus d’informations, voir : Créer des tables à l’aide du SDK pour .NET
• Les classes à liaison anticipée peuvent être utilisées, mais leur utilisation nécessite de générer les classes pour les tables et d’inclure le fichier définissant ces classes avec le projet d’assembly. L’utilisation de classes à liaison anticipée est essentiellement une préférence personnelle, ces étapes ne sont donc pas abordées dans ce didacticiel par souci de concision. Pour plus d’informations, voir : Programmation avec liaison tardive et anticipée à l’aide du SDK pour .NET
• L’Id du compte créé se trouve dans le contexte OutputParameters et est défini comme la colonne de recherche regardingobjectid pour la tâche.

Créer un plug-in

Dans Visual Studio, appuyez sur F6 pour créer l’assembly. Vérifiez qu’il est compilé sans erreur.

Se connecter au plug-in

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet BasicPlugin et sélectionnez Propriétés dans le menu contextuel.

   

2. Dans les propriétés du projet, sélectionnez l’onglet Signature, puis activez la case à cocher Signer l’assembly.

   

3. Dans le menu déroulant Choisir un fichier de clé de nom fort, sélectionnez <Nouveau…>.

4. Dans la boîte de dialogue Créer une clé de nom fort, entrez un nom de fichier de clé et décochez la case à cocher Protéger mon fichier de clé avec un mot de passe.

5. Sélectionnez OK pour fermer la boîte de dialogue Créer une clé de nom fort.

6. Dans l’onglet Créer des propriétés du projet, vérifiez que Configuration est défini sur Debug.

7. Appuyez sur F6 pour créer le plug-in à nouveau.

8. À l’aide de l’Explorateur Windows, recherchez le plug-in créé sous\bin\Debug\BasicPlugin.dll.

Inscrire un plug-in

Pour inscrire un plug-in, vous aurez besoin de Plug-in Registration Tool.

Connexion à l’aide de Plug-in Registration Tool

1. Après avoir téléchargé Plug-in Registration Tool, cliquez sur le fichier PluginRegistration.exe pour l’ouvrir.

2. Cliquez sur Créer une nouvelle connexion pour vous connecter à votre instance.

3. Vérifiez que Office 365 est sélectionné.

4. Si vous vous connectez à l’aide d’un compte Microsoft autre que celui que vous utilisez actuellement, cliquez sur Afficher les paramètres avancés et saisissez vos informations d’identification. Sinon, laissez Connectez-vous en tant qu’utilisateur actuel sélectionné.

5. Si votre compte Microsoft donne accès à plusieurs environnements, sélectionnez Afficher la liste des organisations disponibles.

   

6. Cliquez sur Connexion.

7. Si vous avec sélectionné Afficher la liste des organisations disponibles, sélectionnez l’organisation à laquelle se connecter et cliquez sur Connexion.

8. Une fois connecté, vous verrez tous les plug-ins enregistrés existants, les activités de workflow personnalisées et les fournisseurs de données.

   

Enregistrer votre assembly

1. Dans le menu déroulant Inscrire, sélectionnez Nouveau assembly.

   

2. Dans la boîte de dialogue Inscrire un nouvel assembly, sélectionnez les points de suspension (…) et accédez à l’assembly que vous avez créé dans l’étape précédente.

   

3. Pour les utilisateurs d’Microsoft 365, vérifiez que le mode d’isolation est Bac à sable et que l’emplacement de stockage de l’assembly est Base de données.

   Notes

   D’autres options pour le mode d’isolation et l’emplacement s’appliquent aux déploiements locaux de Dynamics 365. Pour l’emplacement, vous pouvez spécifier la base de données du serveur D365, le stockage local du serveur (disque), ou le GAC (Global Assembly Cache) du serveur. Pour plus d’informations, voir : Stockage du plug-in.

4. Cliquez sur Inscrire les plug-ins sélectionnés.

5. Vous verrez une boîte de dialogue de confirmation Plug-ins inscrits.

   

6. Sélectionnez OK pour fermer la boîte de dialogue, puis fermez la boîte de dialogue Inscrire un nouvel assembly.

7. Vous devriez maintenant voir l’assembly (Assembly) BasicPlugin, que vous pouvez développer pour afficher le plug-in (Plug-in) BasicPlugin.FollowUpPlugin.

   

Inscrire une nouvelle étape

1. Cliquez avec le bouton droit sur (Plug-in) BasicPlugin.FollowUpPlugin et sélectionnez Inscrire une nouvelle étape.

   

2. Dans la boîte de dialogue Inscrire une nouvelle étape, définissez les champs suivants.

   Paramètre	Valeur
   Message	Créer
   Entité principale	compte
   Phase d’exécution dans le pipeline d’événement	PostOperation
   Mode d’exécution	Asynchrone

   

3. Sélectionnez Inscrire une nouvelle étape pour terminer l’inscription et fermer la boîte de dialogue Inscrire une nouvelle étape.

4. Vous pouvez maintenant voir l’étape inscrite.

   

Tester un plug-in

1. Ouvrez une application basée sur un modèle et créez une table Account.

2. Peu de temps après, ouvrez le compte pour vérifier que la tâche a été créée.

   

Que se passe-t-il si la tâche n’a pas été créée ?

Comme nous travaillons avec un plug-in asynchrone, l’opération de création de la tâche se produit après la création du compte. Généralement, la création de la tâche se produit immédiatement, mais si ce n’est pas le cas, vous pouvez toujours afficher la tâche système dans la file d’attente en attendant qu’elle soit appliquée. Cet enregistrement de l’étape a utilisé l’option Supprimer AsyncOperation si StatusCode = Réussi, qui est la méthode recommandée. Cela signifie que dès que la tâche système se termine correctement, vous ne pourrez pas afficher les données de la tâche système à moins d’enregistrer à nouveau le plug-in avec l’option Supprimer AsyncOperation si StatusCode = Réussi désélectionnée.

Toutefois, si une erreur s’est produite, vous pouvez afficher la tâche système pour voir le message d’erreur.

Afficher les tâches système

Utilisez l’application Dynamics 365 --custom pour afficher les tâches système.

1. Dans votre application pilotée par modèle, accédez à l’application.

   

2. Dans l’application Dynamics 365 --custom, accédez à Paramètres > Système > Tâches système.

   

3. Lorsque vous affichez les tâches système, vous pourrez les filtrer par Table (Entité). Sélectionnez Compte.

   

4. Si la tâche a échoué, vous devriez voir un enregistrement avec le nom BasicPlugin.FollowupPlugin : Création du compte.

   

5. Si vous ouvrez la tâche système, vous pouvez développer la section Détails pour afficher les informations écrites dans le journal de suivi ainsi que les détails de l’erreur.

   

Rechercher des tâches système

Vous pouvez utiliser la requête de l’API web suivante pour retourner les tâches système ayant échoué pour les plug-ins asynchrones.

GET <your org uri>/api/data/v9.0/asyncoperations?$filter=operationtype eq 1 and statuscode eq 31&$select=name,message

Plus d’informations : Interroger les données à l’aide de l’API Web

Ou, utilisez la syntaxe FetchXml suivante :

<fetch top='50' >
  <entity name='asyncoperation' >
    <attribute name='message' />
    <attribute name='name' />
    <filter type='and' >
      <condition attribute='operationtype' operator='eq' value='1' />
      <condition attribute='statuscode' operator='eq' value='31' />
    </filter>
  </entity>
</fetch>

Plus d’informations : Utiliser FetchXML avec FetchExpression

Afficher les journaux de suivi

L’exmple de code a écrit un message dans le journal de suivi. Ces étapes suivantes décrivent comment afficher les journaux.

Par défaut, les journaux de suivi du plug-in ne sont pas activés.

Suivez les étapes ci-après pour les activer dans une application basée sur un modèle.

1. Ouvrez l’application Dynamics 365 – custom.

   

2. Accédez à Paramètres > Système > Administration.

   

3. Dans Administration, sélectionnez Paramètres du système.

4. Dans la boîte de dialogue Paramètres du système, sous l’onglet Personnalisation, définissez Autoriser l’enregistrement dans le journal de suivi du plug-in sur Tous.

   

   Notes

   Vous devez désactiver la journalisation lorsque vous avez fini de tester votre plug-in, ou au moins définissez-le sur Exception au lieu de Tous.

5. Sélectionnez OK pour fermer la boîte de dialogue Paramètres système.

6. Répétez les étapes pour tester votre plug-in en créant un nouveau compte.

7. Dans l’application Dynamics 365 -- custom, accédez à Paramètres > Personnalisation > Journal de suivi du plug-in.

8. Vous devriez voir qu’un nouvel enregistrement de suivi du plug-in est créé.

   

9. Si vous ouvrez l’enregistrement, il devrait contenir les informations que vous avez définies dans votre journal de suivi, mais ce n’est pas le cas. Il vérifie uniquement que le suivi a été effectué.

10. Pour afficher les détails, il est plus facile de rechercher ces données à l’aide de l’API web dans votre navigateur en utilisant la requête suivante avec plugintracelog EntityType, qui utilise la propriété typename pour filtrer les résultats dans la propriété messageblock en fonction du nom de la classe de plug-in.

    GET <your org uri>/api/data/v9.0/plugintracelogs?$select=messageblock&$filter=typename eq 'BasicPlugin.FollowUpPlugin'

11. Vous devriez voir ces informations au format JSON renvoyées avec la requête de l’API web.

    {
        "@odata.context": "<your org uri>/api/data/v9.0/$metadata#plugintracelogs(messageblock)",
        "value": [{
            "messageblock": "FollowupPlugin: Creating the task activity.",
            "plugintracelogid": "f0c221d1-7f84-4f89-acdb-bbf8f7ce9f6c"
        }]
    }
    

Étapes suivantes

Dans ce didacticiel, vous avez créé un plug-in simple et l’avez enregistré. Utilisez le Didacticiel : Déboguer un plug-in pour apprendre à déboguer ce plug-in.

Voir aussi

Didacticiel : Mettre à jour un plug-in
Écrire un plug-in
Enregistrer un plug-in
Déboguer des plug-ins.