Didacticiel : Entrer et enregistrer un plug-in
Ce didacticiel est le premier d’une série qui vous montrera comment utiliser des plug-ins. C’est une condition préalable pour les didacticiels suivants :
Pour une explication détaillée des concepts correspondants et des détails techniques, voir :
- Utiliser des plug-ins pour étendre les processus d’entreprise
- Écrire un plug-in
- Enregistrer un plug-in
- Déboguer des plug-ins
Objectif
Créez un plug-in asynchrone enregistré dans le message Créer de la table Account. Le plug-in créera une activité de tâche qui rappellera 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.
Configuration requise
- Accès au niveau administrateur à un environnement Microsoft Dataverse
- Une application basée sur un modèle qui comprend les tables Account et Task.
- Si vous ne disposez pas d’une application basée sur un modèle contenant ces entités, consultez Générer votre première application basée sur un modèle entièrement pour connaître les étapes de la création d’une application en quelques minutes.
- Visual Studio 2017 (ou ultérieure)
- Des connaissances sur le langage de programmation Visual C#
- Téléchargez l’outil d’inscription de plug-in en suivant les instructions suivantes : Outils de développement Dataverse.
Créer un projet de plug-in
Vous devez utiliser Visual Studio pour entrer un plug-in. Utilisez les étapes suivantes pour entrer un plug-in de base. Alternativement, vous pouvez utiliser Power Platform CLI pour créer un projet à l’aide de la commande pac plugin init.
Vous pouvez aussi trouver les fichiers de solution de plug-in complets ici : Exemple : Créer un plug-in de base.
Créer un projet Visual Studio pour le plug-in
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 sera le nom de l’assembly. Ce didacticiel utilise le nom
BasicPlugin.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.
Sélectionnez Parcourir, recherchez
Microsoft.CrmSdk.CoreAssemblieset installez la dernière version.
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.Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le fichier
Class1.cset sélectionnez Renommer dans le menu contextuel.
Renommez le fichier
Class1.csenFollowupPlugin.cs.Lorsque vous y êtes invité, autorisez Visual Studio à renommer la classe pour correspondre au nom du fichier.
Modifier le fichier Class pour activer un plug-in
Ajoutez les instructions
usingsuivantes en haut du fichierFollowupPlugin.cs:using System.ServiceModel; using Microsoft.Xrm.Sdk;Implémentez l’interface IPlugin en modifiant la classe.
Notes
Si vous tapez simplement
: IPluginaprè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(); } }Remplacez le contenu de la méthode
Executepar 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 sera enregistré. Si la propriété Target est présente, le paramètre Entity transmis à la requête sera disponible.
- L’interface IOrganizationServiceFactory donne accès à une variable de service qui implémente l’interface IOrganizationService qui fournit les méthodes permettant d’interagir avec le service pour créer la tâche.
Ajouter une logique métier
Le plug-in créera une activité de tâche qui rappellera 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 ce qui suit :
// 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 cela 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. Il s’agit principalement d’une préférence personnelle, ces étapes n’ont donc pas été 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
regardingobjectidpour 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
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet BasicPlugin et sélectionnez Propriétés dans le menu contextuel.
Dans les propriétés du projet, sélectionnez l’onglet Signature, puis activez la case à cocher Signer l’assembly.
Dans le menu déroulant Choisir un fichier de clé de nom fort, sélectionnez <Nouveau…>.
Dans la boîte de dialogue Créer une clé de nom fort, entrez un nom de fichier et désactivez la case à cocher Protéger mon fichier de clé avec un mot de passe.
Cliquez sur OK pour fermer la boîte de dialogue Créer un fichier de clé de nom fort.
Dans l’onglet Créer des propriétés du projet, vérifiez que Configuration est défini sur Debug.
Appuyez sur F6 pour créer le plug-in à nouveau.
À 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 avez besoin du Plug-in Registration Tool
Connexion à l’aide de Plug-in Registration Tool
Après avoir téléchargé Plug-in Registration Tool, cliquez sur le fichier
PluginRegistration.exepour l’ouvrir.Cliquez sur Créer une nouvelle connexion pour vous connecter à votre instance.
Vérifiez que Office 365 est sélectionné.
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é.
Si votre compte Microsoft donne accès à plusieurs environnements, sélectionnez Afficher la liste des organisations disponibles.
Cliquez sur Connexion.
Si vous avec sélectionné Afficher la liste des organisations disponibles, sélectionnez l’organisation à laquelle se connecter et cliquez sur Connexion.
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
Dans le menu déroulant Inscrire, sélectionnez Nouveau assembly.
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.
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.
Cliquez sur Inscrire les plug-ins sélectionnés.
Une boîte de dialogue de confirmation Plug-ins inscrits s’affiche.
Cliquez sur OK pour fermer la boîte de dialogue, puis fermez la boîte de dialogue Inscrire un nouvel assembly.
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
Cliquez avec le bouton droit sur (Plug-in) BasicPlugin.FollowUpPlugin et sélectionnez Inscrire une nouvelle étape.
Dans la boîte de dialogue Inscrire une nouvelle étape, définissez les champs suivants :
Paramètre Value Message Créer Entité principale compte Phase d’exécution dans le pipeline d’événement PostOperation Mode d’exécution Asynchrone 
Cliquez sur Inscrire une nouvelle étape pour terminer l’inscription, puis fermez la boîte de dialogue Inscrire une nouvelle étape.
Vous pouvez maintenant 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. Consultez Ajouter votre assembly à une solution et Ajouter une étape à la solution pour plus d’informations.
Tester un plug-in
Ouvrez une application basée sur un modèle et créez une table Account.
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 il s’agit d’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, il 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.
Dans votre application basée sur un modèle, accédez à l’application
Dans l’application Dynamics 365 --custom, accédez à Paramètres > Système > Tâches système.
Lorsque vous affichez les tâches système, vous pourrez les filtrer par Table (Entité). Sélectionnez Compte.
Si la tâche a échoué, vous devez afficher un enregistrement avec le nom BasicPlugin.FollowupPlugin : Création du compte
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
Pour plus d’informations, consultez 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>
Pour plus d’informations, voir : Utiliser FetchXML avec FetchExpression
Afficher les journaux de suivi
L’exmple de code a écrit un message dans le journal de suivi. Les étapes ci-dessous 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.
Ouvrez l’application Dynamics 365 – custom.
Accédez à Paramètres > Système > Administration.
Dans Administration, sélectionnez Paramètres du système.
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.
Cliquez sur OK pour fermer la boîte de dialogue Paramètres système.
Répétez les étapes pour tester votre plug-in en créant un nouveau compte.
Dans l’application Dynamics 365 -- custom, accédez à Paramètres > Personnalisation > Journal de suivi du plug-in.
Un nouvel enregistrement de suivi du plug-in devrait avoir été créé.
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é.
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é
typenamepour filtrer les résultats dans la propriétémessageblocken 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'La syntaxe suivante devrait être retournée 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.
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é).
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour