Plugin Registration Tool : guide complet du développeur

Qu'est-ce que le Plugin Registration Tool ?

Le Plugin Registration Tool (PRT) est l'utilitaire officiel de Microsoft pour l'enregistrement et la gestion des plugins, des activités de workflow personnalisées, des fournisseurs de données de tables virtuelles, des webhooks et des endpoints de service dans les environnements Dynamics 365 et Dataverse.

Contrairement au déploiement de code sur des serveurs web traditionnels, les plugins Dynamics 365 doivent être enregistrés via PRT pour informer la plateforme de vos assemblies personnalisées et définir les conditions exactes dans lesquelles elles doivent s'exécuter. fondamentaux de l'enregistrement de plugins.

Installation et configuration

Le Plugin Registration Tool est distribué dans le package d'outils de développement Power Platform.

Méthodes d'installation :

• Power Platform CLI : Exécuter pac tool prt pour télécharger et lancer PRT
• Téléchargement direct : Télécharger les outils de développement depuis Microsoft et extraire PluginRegistration.exe
• Via XrmToolBox : Accéder à PRT comme plugin dans XrmToolBox pour un workflow intégré

Connexion à votre environnement

Cliquez sur « Créer Nouvelle Connexion » et fournissez l'URL de votre environnement Dynamics 365 et vos identifiants. L'outil prend en charge l'authentification Office 365, OAuth et Active Directory on-premises.

Enregistrement d'une assembly de plugin

Avant de pouvoir enregistrer des étapes de plugin individuelles, vous devez d'abord enregistrer l'assembly compilée (fichier DLL) contenant votre code de plugin.

Processus d'enregistrement :

1. Cliquez sur « Register » > « Register New Assembly »
2. Parcourez jusqu'à votre DLL de plugin compilée
3. Sélectionnez le mode d'isolation (Sandbox est recommandé pour les environnements cloud)
4. Choisissez l'emplacement de stockage (Database pour cloud, Disk pour on-premises)
5. Revoyez les classes de plugin détectées et cliquez « Register Selected Plugins »

Mise à jour des assemblies existantes

Quand vous modifiez le code de plugin, vous devez mettre à jour l'assembly enregistrée. Faites un clic droit sur l'assembly dans PRT et sélectionnez « Update ». Choisissez votre nouvelle DLL et tous les enregistrements d'étapes existants utiliseront automatiquement le code mis à jour.

Enregistrement des étapes de plugin

Une étape de plugin définit quand et comment votre plugin s'exécute. Chaque étape spécifie le message, l'entité, le stade d'exécution et le mode d'exécution pour votre plugin. le pipeline d'exécution des événements.

Paramètres de configuration d'étape

• Message : L'opération qui déclenche le plugin (Create, Update, Delete, Retrieve, Associate, etc.)
• Entité primaire : L'entité que le plugin surveille (laisser vide pour toutes les entités)
• Stade du pipeline d'événements : Quand le plugin s'exécute (PreValidation, PreOperation, PostOperation)
• Mode d'exécution : Synchrone (bloque l'action utilisateur) ou Asynchrone (s'exécute en arrière-plan)
• Attributs de filtrage : Pour les messages Update, spécifier quels changements de champs déclenchent le plugin
• Contexte utilisateur : Exécuter en tant qu'utilisateur appelant ou un utilisateur système spécifique

Attributs de filtrage pour la performance

Pour les plugins de message Update, spécifiez toujours les attributs de filtrage pour limiter les exécutions. Sans filtres, votre plugin s'exécute à chaque mise à jour de champ, causant un traitement inutile et une dégradation des performances.

Images d'étape : capture de snapshots de données

Les images d'étape permettent à votre plugin d'accéder aux données de l'enregistrement telles qu'elles existaient avant (PreImage) ou après (PostImage) l'opération. documentation des images d'entité.

Configuration des images

• PreImage : Capture l'état de l'enregistrement avant l'opération (disponible dans les stades PreOperation et PostOperation)
• PostImage : Capture l'état de l'enregistrement après l'opération (disponible uniquement dans le stade PostOperation)
• Alias d'image : Nom que vous utiliserez dans le code pour accéder à l'image (p. ex. « PreImage », « PostImage »)
• Attributs : Spécifier quels champs inclure (réduit la taille du payload et améliore la performance)

Webhooks : callbacks HTTP pour l'intégration externe

Les webhooks permettent à Dynamics 365 d'appeler des endpoints HTTP externes quand des événements spécifiques se produisent, permettant l'intégration avec des systèmes externes sans code de plugin personnalisé. capacités des webhooks.

Enregistrement d'un webhook

1. Cliquez sur « Register » > « Register New Webhook »
2. Fournissez le nom du webhook et l'URL de l'endpoint (doit être HTTPS)
3. Sélectionnez le type d'authentification (HttpHeader, WebhookKey, HttpQueryString)
4. Enregistrez une étape sur le webhook similaire à l'enregistrement d'étape de plugin

Activités de workflow personnalisées

Les activités de workflow personnalisées étendent les workflows Power Automate avec du code .NET. Elles apparaissent comme activités dans le designer de workflow après enregistrement.

Étapes d'enregistrement

• Développer l'activité de workflow héritant de CodeActivity
• Enregistrer l'assembly comme pour une assembly de plugin
• L'activité apparaît dans le designer de workflow sous les activités personnalisées
• Configurer les paramètres d'entrée/sortie via le designer de workflow

Plugin Profiler : débogage en action

Le Plugin Profiler capture le contexte d'exécution du plugin depuis votre environnement live et crée un profil local que vous pouvez rejouer dans Visual Studio pour le débogage.

Workflow de profilage

1. Sélectionnez l'étape de plugin à profiler dans PRT
2. Cliquez sur « Start Profiling » et choisissez le mode de profilage (Exception ou Persist to Entity)
3. Effectuez l'opération dans Dynamics 365 qui déclenche le plugin
4. Retournez à PRT et cliquez « Debug » pour télécharger le profil d'exécution
5. Ouvrez votre projet de plugin dans Visual Studio et attachez le profil
6. Définissez des breakpoints et parcourez le code avec le contexte capturé

Endpoints de service pour l'intégration Azure

Les endpoints de service permettent de poster les données d'événements Dynamics 365 vers les queues Azure Service Bus, topics ou Event Hubs pour le traitement en aval.

Configuration des endpoints de service

• Enregistrer l'endpoint de service avec la chaîne de connexion Azure
• Spécifier le format de message (JSON, XML, Binary)
• Enregistrer une étape sur l'endpoint de service (similaire aux étapes de plugin)
• Les messages sont automatiquement postés vers Azure quand l'étape s'exécute

Bonnes pratiques pour l'enregistrement de plugins

Sécurité et gouvernance

• Utiliser le développement conscient des solutions pour packager les plugins correctement
• Limiter l'accès aux environnements de production au personnel autorisé
• Documenter tous les plugins enregistrés et leur objectif métier
• Mettre en œuvre des processus de gestion des changements pour les mises à jour de plugins

Considérations de performance

• Toujours spécifier les attributs de filtrage pour les plugins de message Update
• Utiliser le mode asynchrone quand l'exécution en temps réel n'est pas requise
• Inclure uniquement les attributs nécessaires dans les images d'étape
• Surveiller les logs de trace de plugin pour l'analyse du temps d'exécution

Workflow de développement

• Utiliser les environnements de développement pour les tests initiaux de plugin
• Mettre en œuvre un versioning approprié pour les mises à jour d'assembly
• Activer le traçage pendant le développement, exception-only en production
• Nettoyer les enregistrements de plugins inutilisés pour réduire la complexité

Dépannage des problèmes courants

Timeouts du processus worker sandbox

Les plugins sandboxés ont une limite d'exécution de 2 minutes. Concevez les plugins pour qu'ils complètent rapidement et déchargez les opérations longues vers des processus async.

Conflits de mode d'isolation

Les modes d'isolation Sandbox et None ne peuvent pas coexister dans la même assembly. Séparez les plugins sandbox des plugins full-trust dans différentes assemblies.

Dépendances manquantes

Les assemblies de plugin doivent être autonomes. Utilisez ILMerge ou intégrez les dépendances comme ressources. Seules les assemblies SDK sont disponibles dans le sandbox.

Conclusion

Le Plugin Registration Tool est fondamental pour la personnalisation de Dynamics 365, servant de pont entre votre code .NET personnalisé et le framework d'événements de la plateforme. Maîtriser PRT est essentiel pour tout développeur Dynamics 365 construisant des solutions entreprise.

Comprendre les concepts d'enregistrement – assemblies, étapes, images et stades du pipeline d'exécution – vous permet de construire des plugins robustes et performants qui s'intègrent parfaitement avec la plateforme. Combiné avec les capacités de débogage comme le Plugin Profiler, PRT fournit tout ce qu'il faut pour le développement et la maintenance professionnels de plugins.