Partage via

Didacticiel : Écrire et enregistrer un plug-in

  • Article

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.

Notes

Cet objectif peut être facilement atteint en utilisant un workflow sans écrire de code. Nous utilisons cet exemple simple afin de nous concentrer sur le processus de création et de déploiement d’un plug-in.

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

    Ouvrir un nouveau projet Bibliothèque de classes (.NET Framework) à l’aide 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.

    Gérer les packages NuGet.

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

    Installez le package Microsoft.CrmSdk.CoreAssemblies NuGet.

  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.

    Renommer la classe.

  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.

    Boîte de dialogue de confirmation de l’attribution d’un nouveau nom.

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

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.

    Ouvrir les propriétés du projet.

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

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

Notes

Créez l’assembly à l’aide de la configuration Debug, car vous utiliserez le profileur de plug-in pour le déboguer dans un didacticiel ultérieur. Avant d’inclure un plug-in dans votre solution, vous devez le créer à l’aide de la configuration Release.

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.

    Connexion avec Plug-in Registration Tool.

  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.

    Afficher les plug-ins existants et les activités de workflow personnalisées.

Enregistrer votre assembly

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

    Inscrire un nouvel 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.

    Boîte de dialogue Inscrire un nouvel assembly.

  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.

    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.

    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.

    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

    Saisie des données d’étape pertinentes.

  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.

    Voir l’étape inscrite.

Notes

À ce stade, l’assembly et les étapes font partie du système Solution par défaut. Lors de la création d’un plug-in de production, vous les ajouterez à la solution non gérée que vous distribuerez. Ces étapes ne sont pas décrites dans le présent didacticiel. Pour plus d’informations, voir Ajouter votre assemblage à une solution et Ajouter étape à la solution .

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.

    Enregistrement de table de compte avec création de l’activité de tâche associée par plug-in.

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.

    vue de l’application Dynamics 365 – custom.

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

    accéder aux tâches système.

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

    Filtrer sur les comptes.

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

    Échec de la tâche système.

  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.

    détails de la tâche système.

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.

Conseil

Si vous préférez modifier ce paramètre dans le code : ce paramètre se trouve dans la colonne PluginTraceLogSetting de la table Organization.

Les valeurs valides sont :

valeur Étiquette
0 Désactivée
1 Exception
2 Tout

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.

    Ouvrez l’application Dynamics 365 – custom.

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

    accéder à 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.

    Onglet Personnalisation des paramètres du système.

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

    Enregistrement du journal de suivi du plug-in.

  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.

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