Les plug-ins constituent un moyen puissant d'étendre et de personnaliser Dynamics 365 (Dataverse) en injectant une logique personnalisée dans le pipeline d'événements standard. Que vous validiez des données lors de la création d'enregistrements ou que vous orchestraissiez une logique métier complexe lors des mises à jour, les plug-ins vous permettent d'aller au-delà des fonctionnalités prêtes à l'emploi. Cet article décrit les étapes essentielles pour créer un plug-in dans Visual Studio, comment le déployer et les bonnes pratiques pour la gestion et la journalisation des erreurs.
Cet article s'adresse principalement à un public technique, à moins que vous ne souhaitiez le lire pour vous faire une idée générale.
Événements clés pour le déclenchement des plugins dans Dynamics 365
Avant de pouvoir discuter de la configuration, voici un aperçu rapide des principaux événements sur lesquels vous pouvez attacher vos plugins.
- Create : lorsqu'un enregistrement est créé.
- Update : lorsqu'un enregistrement est mis à jour.
- Delete : lorsqu'un enregistrement est supprimé.
- Retrieve : lorsqu'un enregistrement est récupéré (lu).
- RetrieveMultiple : lorsqu'une requête renvoie plusieurs enregistrements
Les événements spécifiques incluent l'affectation, la fusion, la définition de l'état, la fermeture et la qualification du lead, qui sont moins fréquents. D'autres événements impliquent le partage, la sécurité, les relations telles que l'association et les événements personnalisés créés au sein de la plateforme. Plus d'informations sur Microsoft learn
Le pipeline d'exécution d'événements dans Microsoft Dataverse décompose le traitement des messages en quatre phases distinctes, ce qui permet aux développeurs d'insérer du code personnalisé à des points spécifiques du cycle de vie d'une opération. Phases du pipeline d'exécution des événements :
1. PreValidation : la pré-validation a lieu avant l'exécution, ce qui permet l'annulation avant les contrôles de sécurité.
2. PreOperation : la pré-opération permet de modifier les valeurs des entités, mais l'annulation risque d'entraîner des problèmes de restauration.
3. MainOperation : l'opération principale est interne, mais permet des données de table virtuelle personnalisées et des interventions sur les API.
4. PostOperation : la post-opération modifie les messages et enregistre les étapes asynchrones après l'exécution.
Le choix de la phase d'exécution dépend directement de l'objectif de l'extension. Si une exception est levée par le code dans une phase synchrone au sein de la transaction, elle entraînera une restauration complète de la transaction. Pour annuler une opération, il est recommandé d'intervenir pendant la phase de pré-validation en lançant une exception 2. PreOperation : la pré-opération permet de modifier les valeurs des entités, mais l'annulation risque d'entraîner des problèmes de restauration.
3. MainOperation : l'opération principale est interne, mais permet des données de table virtuelle personnalisées et des interventions sur les API.
4. PostOperation : la post-opération modifie les messages et enregistre les étapes asynchrones après l'exécution.
InvalidPluginExecutionException accompagnée d'un message explicatif. Plus d'informations sur la documentation Microsoft ).
1. Configuration de votre environnement de développement
Concentrons-nous maintenant sur les exigences pour la création d'un plugin.
Pour configurer votre environnement de développement, suivez les étapes ci-dessous :
1. Installer Visual Studio
2. Configurer votre projet
3. Organisation des dossiers et des espaces de noms
- Utilisez Visual Studio (Community, Professional ou Enterprise), et non Visual Studio Code.
- Vous devrez installer séparément la boîte à outils du développeur Dynamics 365 ou les outils du SDK Dynamics 365 (bien que la boîte à outils d'origine soit désormais obsolète, plusieurs versions communautaires sont disponibles).
2. Configurer votre projet
- Créez un nouveau projet de bibliothèque de classes (.NET Framework) dans Visual Studio.
- Ajoutez des références aux assemblys Dataverse nécessaires, par exemple,
Microsoft.Xrm.SdketMicrosoft.Crm.Sdk.Proxy.
3. Organisation des dossiers et des espaces de noms
- Conservez vos classes de plug-in dans une structure de dossier logique (par exemple,
Plugins/) et utilisez des conventions d'espace de noms cohérentes pour éviter toute confusion.
2. Exemple de modèle de plug-in
Vous trouverez ci-dessous un modèle de base pour un plug-in Dynamics 365 utilisant C#.
Cet exemple se déclenche lors de la création d'un enregistrement Contact. Il vérifie si le champ « description » est vide et le remplit automatiquement avec une valeur par défaut si nécessaire.
using System;
using Microsoft.Xrm.Sdk;
namespace MyDynamicsPlugins
{
public class CreateContactPlugin : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the tracing service
ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
// Obtain the plugin execution context
IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
// Obtain the organization service reference
IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService orgService = serviceFactory.CreateOrganizationService(context.UserId);
try
{
tracingService.Trace("CreateContactPlugin: Execution started...");
// Check if the plugin is triggered by 'Create' message
if (context.MessageName == "Create" && context.InputParameters.Contains("Target"))
{
// 'Target' is the entity to be created
Entity entity = (Entity)context.InputParameters["Target"];
// Make sure it's a Contact entity
if (entity.LogicalName == "contact")
{
// Implement your custom logic here
tracingService.Trace("CreateContactPlugin: Processing contact creation.");
// Example: Check if 'description' field is empty
if (!entity.Contains("description") || string.IsNullOrWhiteSpace(entity["description"].ToString()))
{
entity["description"] = "Auto-filled description by plugin";
tracingService.Trace("CreateContactPlugin: Description field auto-filled.");
}
}
}
tracingService.Trace("CreateContactPlugin: Execution completed successfully.");
}
catch (Exception ex)
{
// Trace the error
tracingService.Trace("CreateContactPlugin: {0}", ex.ToString());
// Raise an exception so it appears in the user interface or logs
throw new InvalidPluginExecutionException("An error occurred in the CreateContactPlugin.", ex);
}
}
}
}
3. Création et empaquetage de la DLL
Suivez les étapes ci-dessous :
1. Configurer les propriétés de l'assembly
- Accédez à Projet → Propriétés et assurez-vous que le nom de l'assembly et l'espace de noms par défaut correspondent à vos préférences.
- (Facultatif) Signez l'assembly avec un nom fort dans l'onglet Signature.
2. Créer le projet
- Sélectionnez le mode Version (bien que Débogage fonctionne également pour les tests).
- Cliquez avec le bouton droit sur votre projet dans l'Explorateur de solutions et choisissez Créer ou Reconstruire.
- Un fichier
.dllest généré dans le dossierbin/Releasede votre projet.
3. Valider les dépendances
- Assurez-vous que la DLL finale référence la version correcte des assemblys
Microsoft.Xrm.Sdk(qui correspond généralement à votre instance en ligne ou sur site).
4. Importation du plug-in dans Dynamics 365 (Cloud)
1. Utilisez l'outil d'enregistrement de plug-in
- Lancez l'outil d'enregistrement de plug-in (fourni dans les outils CRM SDK).
- Connectez-vous à votre instance Dynamics 365 (utilisez OAuth ou une autre méthode d'authentification prise en charge).
- Cliquez sur Enregistrer → Enregistrer un nouvel assemblage.
- Accédez à votre fichier .dll.
- Choisissez Base de données comme emplacement de stockage (recommandé pour Dynamics 365 Online).
- Une fois l'assemblage enregistré, développez-le dans l'outil et Enregistrer une nouvelle étape.
- Spécifiez le Message (par exemple, Créer), Entité principale (par exemple, contact) et l'étape de pipeline appropriée (par exemple, pré-opération ou post-opération).
- Ajustez les Attributs de filtrage si vous souhaitez que le plug-in ne se déclenche que pour certains champs.
- Après l'enregistrement, effectuez l'action (par exemple, créer un nouveau contact) dans Dynamics 365.
- Vérifiez que la logique de votre plug-in s'exécute comme prévu.
5. Gestion des erreurs et journalisation
La journalisation est essentielle lors du développement de plugins. Si le code ne fonctionne pas comme prévu, certaines opérations peuvent échouer. C'est pourquoi l'utilisation de
tracingService est cruciale. Les messages enregistrés via ce service sont capturés dans les journaux de suivi des plugins. Voici comment l'activer.A. Activation des journaux dans l'environnement
Pour activer les journaux de suivi des plug-ins dans Dynamics 365, cliquez sur l'icône des paramètres ⚙️ en haut à droite de l'écran et sélectionnez Paramètres avancés.
Une fois dans les paramètres avancés, accédez à Système → Administration, puis cliquez sur Personnalisation.
Dans la fenêtre des paramètres système, accédez à l'onglet Personnalisation et recherchez l'option Activer le suivi des plug-ins et la journalisation des activités personnalisées. Modifiez cette option sur Oui pour l'activer. Après avoir activé cette fonctionnalité, choisissez le niveau de journalisation sous Niveau de journalisation du suivi des plug-ins. Vous pouvez sélectionner Exception ou Tout pour enregistrer.
Une fois dans les paramètres avancés, accédez à Système → Administration, puis cliquez sur Personnalisation.
Dans la fenêtre des paramètres système, accédez à l'onglet Personnalisation et recherchez l'option Activer le suivi des plug-ins et la journalisation des activités personnalisées. Modifiez cette option sur Oui pour l'activer. Après avoir activé cette fonctionnalité, choisissez le niveau de journalisation sous Niveau de journalisation du suivi des plug-ins. Vous pouvez sélectionner Exception ou Tout pour enregistrer.
Ce journal capture les appels
tracingService.Trace(). Les administrateurs peuvent ensuite afficher la sortie sous Paramètres → Tâches système → Journal de suivi des plug-ins.Remarque : pour des raisons de performances, il est généralement recommandé de désactiver ou de limiter les journaux en production. Une journalisation excessive peut augmenter l'utilisation du stockage et affecter les performances.
B. Importance de
try-catch pour les opérations critiques- Envelopper vos opérations critiques dans des blocs
try-catchvous permet d'intercepter et de consigner les exceptions. - Utilisez
ITracingServicepour générer des traces pertinentes pour le débogage. - La relance des exceptions à l'aide de
throw new InvalidPluginExecutionException()fait apparaître les erreurs dans l'interface utilisateur ou les journaux Dynamics, ce qui permet aux administrateurs d'identifier plus rapidement les problèmes.
6. Récapitulatif des bonnes pratiques
1. Gardez les plugins concentrés Chaque étape de plugin doit gérer une responsabilité unique. Une logique complexe peut être divisée en plusieurs étapes ou flux secondaires (par exemple, Azure Functions ou Power Automate).
2. Exploitez le service de traçage Suivez toujours le début et la fin des opérations critiques, ainsi que les valeurs des variables pertinentes. Cela est inestimable pour le débogage.
3. Gérez les exceptions avec élégance L'approche
try-catch garantit que les erreurs sont enregistrées. Vous pouvez également les relancer ou les gérer en silence, selon votre scénario.4. Limiter les niveaux de journalisation en production Générer des journaux minimaux en production pour éviter les baisses de performances, mais les garder suffisamment détaillés pour résoudre les problèmes critiques.
5. Maintenir le contrôle des versions Stockez votre projet de plug-in dans un système de contrôle de source (par exemple, Git) pour suivre les modifications et collaborer efficacement.
Conclusion
Les plug-ins Dynamics 365 vous permettent d'injecter une logique métier personnalisée à des points clés du pipeline de traitement des données, offrant une flexibilité significative dans la façon dont vous contrôlez les données et les processus. En utilisant Visual Studio, en suivant une architecture de code propre et en implémentant une gestion des erreurs robuste via
try-catch et ITracingService, vous garantissez que vos plug-ins sont à la fois fiables et maintenables. N'oubliez pas de gérer soigneusement la journalisation, en particulier en production, pour maintenir des performances élevées tout en capturant les informations de diagnostic essentielles. En gardant ces bonnes pratiques à l'esprit, vous serez sur la bonne voie pour fournir des extensions de qualité professionnelle dans Dynamics 365.
English
Français