Déboguer un plug-in

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Les étapes suivantes montrent comment déboguer un plug-in s'exécutant sous Microsoft Dynamics 365 local. Pour déboguer un plug-in qui s’exécute dans le bac à sable sous Microsoft Dynamics 365 (Online), vous devez utiliser le traçage comme décrit plus loin dans cette rubrique.

Contenu de la rubrique

Debug a plug-in

Déboguer un plug-in placé dans le bac à sable

Enregistrement et traçage

Déboguer un plug-in

1. Inscrivez et déployez l’assembly de plug-in.

   S’il existe une autre copie de l’assembly au même emplacement et que vous ne pouvez pas remplacer cette copie car elle est verrouillée par Microsoft Dynamics 365, vous devrez redémarrer le processus de service qui exécute le plug-in. Reportez-vous au tableau ci-dessous pour identifier le processus de service approprié.Pour plus d'informations : Inscrire et déployer des plug-ins

2. Configurez le débogueur.

   Associez le débogueur au processus sur le serveur Microsoft Dynamics 365 qui exécutera votre plug-in. Consultez le tableau suivant pour identifier le processus.

   Configuration de l’inscription du plug-in	Processus de service
   en ligne	w3wp.exe
   hors connexion	Microsoft.Crm.Application.Hoster.exe
   plug-ins inscrits de manière asynchrone (ou assemblys de workflow personnalisés)	CrmAsyncService.exe
   bac à sable (mode d’isolation)	Microsoft.Crm.Sandbox.WorkerProcess.exe

   S’il existe plusieurs processus exécutant le même fichier exécutable, par exemple plusieurs processus w3wp.exe, associez le débogueur à toutes les instances du processus de fichier exécutable existant. Ensuite, définissez un ou plusieurs points d’arrêt dans votre code de plug-in.

3. Testez le plug-in.

   Exécutez l’application Microsoft Dynamics 365 ou toute autre application personnalisée qui utilise le Kit de développement logiciel, et effectuez les actions nécessaires pour exécuter le plug-in. Par exemple, si un plug-in est inscrit pour un événement de création de compte, créez un compte.

4. Déboguez le code de votre plug-in.

   Apportez les modifications nécessaires à votre code afin qu’il effectue ce que vous souhaitez. Si le code est modifié, compilez-le dans un assembly et répétez les étapes 1 à 4 de cette procédure, si nécessaire. Toutefois, si vous modifiez les numéros de version principale et secondaire de l’assembly de plug-in, vous devrez annuler l’inscription de la version antérieure de l’assembly et inscrire la nouvelle version.Pour plus d'informations : Inscrire et déployer des plug-ins

5. Inscrivez le plug-in dans la base de données.

   Après le cycle de modification/compilation/déploiement/test/débogage de votre plug-in, annulez l’inscription du plug-in (sur disque), puis réinscrivez-le dans la base de données Microsoft Dynamics 365.Pour plus d'informations : Inscrire et déployer des plug-ins

Pour plus d’informations sur le débogage d’un plug-in à l’aide de l’outil de profilage de plug-in, voir Analyser les performances des plug-ins.

Déboguer un plug-in placé dans le bac à sable

Il est important d’effectuer ces étapes avant la première exécution d’un plug-in placé dans le bac à sable. Si le plug-in a déjà été exécuté, vous pouvez soit modifier le code de l’assembly, provoquant le hachage de l’assembly pour sa modification sur le serveur, soit redémarrer le Service de traitement Bac à sable (sandbox) Microsoft Dynamics 365 sur le serveur bac à sable.

Configurer le serveur

Le processus hôte de bac à sable analyse le processus de travail du bac à sable qui exécute le plug-in. Le processus hôte vérifie si le plug-in cesse de répondre, s’il dépasse des seuils de mémoire, etc. Si le processus de travail ne répond pas pendant 30 secondes, il sera systématiquement arrêté. Pour déboguer un plug-in de bac à sable, vous devez désactiver cette fonctionnalité d’arrêt. Pour désactiver la fonctionnalité d’arrêt, définissez la clé de Registre suivante à 1 (DWORD) :

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM\SandboxDebugPlugins

Déboguer le plug-in

Procédez comme suit pour déboguer un plug-in placé dans le bac à sable.

1. Inscrivez le plug-in dans le bac à sable (mode d’isolation) et déployez-le dans la base de données du serveur Microsoft Dynamics 365.

2. Copiez le fichier symbole (.pdb) de l’assembly de plug-in compilé dans le dossier server\bin\assembly qui figure sur le serveur exécutant le processus de travail du bac à sable nommé Microsoft.Crm.Sandbox.WorkerProcess.exe. Il s’agit du serveur qui héberge le rôle Service de traitement Bac à sable (sandbox).

3. Suivez les instructions des étapes 2 à 4 présentées au début de cette rubrique.

Pour plus d’informations sur le débogage d’un plug-in à l’aide de l’outil de profilage de plug-in, voir Analyser les performances des plug-ins.

Enregistrement et traçage

Le traçage offre une solution alternative pour résoudre une exécution du plug-in ou une activité de workflow personnalisée (code personnalisé), par rapport au débogage dans Microsoft Visual Studio. Le traçage aide les développeurs en enregistrant les informations personnalisées de l'exécution pour diagnostiquer la cause des défaillances de code. Il est particulièrement utile pour résoudre les problèmes de code personnalisé Microsoft Dynamics 365 (Online) inscrit car il s'agit de la seule méthode de résolution des problèmes prise en charge pour ce scénario. Le traçage est pris en charge pour le code personnalisé inscrit exigeant une confiance totale ou en mode sandbox (confiance partielle) et lors de l'exécution synchrone ou asynchrone. Le traçage n'est pas pris en charge pour le code personnalisé qui s'exécute dans Microsoft Dynamics 365 pour Outlook ou dans un autre client mobile.

L'enregistrement des informations de traçage à l'exécution pour Microsoft Dynamics 365 est fourni par un service nommé ITracingService. Les informations fournies à ce service par le code personnalisé peuvent être enregistrées dans trois emplacements différents, comme identifié ici.

• Journal de suivi

  Les journaux de suivi du type PluginTraceLog sont situés dans l'application Web. Pour les trouver, accédez à Paramètres et choisissez la vignette Journal de suivi du plug-in. La vignette est visible uniquement si vous avez accès aux enregistrements d'entité des journaux de suivi dans le rôle de sécurité qui vous est attribué. L'écriture sur ces enregistrements est contrôlée par les paramètres de suivi indiqués dans la section suivante. Pour plus d'informations sur les privilèges requis pour l'entité PluginTraceLog, voir Privilèges pat entité.

  Notes

  La journalisation du suivi occupe de l'espace sur le stockage de l'organisation, surtout lorsque de nombreux suivis et exceptions sont générés. Vous devez activer la journalisation du suivi uniquement pour déboguer et résoudre les problèmes, et la désactiver une fois votre enquête terminée.

• Boîte de dialogue d'erreur

  Une exécution du plug-in inscrit synchrone ou une activité de workflow personnalisée qui renvoie une exception à la plateforme déclenche une boîte de dialogue d'erreur dans l'application Web qui s'affiche à l'utilisateur connecté. L'utilisateur peut sélectionner le bouton Fichier journal de téléchargement de la boîte de dialogue pour afficher le journal contenant l'exception et le résultat de suivi.

• Tâche système

  Pour l'exécution des plug-ins inscrits asynchrones ou les activités de workflow personnalisées qui renvoient une exception, les informations de suivi sont affichées dans la zone Détails du formulaire Tâche système de l'application Web.

Activer la journalisation du suivi

Pour activer la journalisation du suivi dans une organisation qui prend en charge cette fonctionnalité, dans l'application Web accédez à Paramètres > Administration > Paramètres système. Dans l'onglet Personnalisation, recherchez la liste déroulante nommée Activer la journalisation dans le journal de suivi des plug-ins et sélectionnez l'une des options disponibles.

Si le paramètre de journalisation du suivi est défini sur Exception et si votre code personnalisé renvoie une exception sur la plateforme, un enregistrement de journal de suivi est créé et les informations de suivi sont également entrées à un autre emplacement. Pour un code personnalisé qui s'exécute de façon synchrone, les informations sont présentées à l'utilisateur dans une boîte de dialogue d'erreur, sinon, pour un code asynchrone, les informations sont écrites dans la tâche système associée.

Par défaut, les rôles Administrateur système et Personnalisateur de système ont les privilèges requis pour modifier le paramètre de journalisation du suivi, qui est enregistré dans un enregistrement d'entité TraceSettings. Les paramètres de suivi s'appliquent dans l'étendue de l'organisation.

Écrire dans le service de suivi

Avant d'écrire dans le service de suivi, vous devez extraire l'objet de service de suivi du contexte d'exécution transmis. Ensuite, ajoutez simplement les appels Trace à votre code personnalisé, lorsqu'il est nécessaire de transmettre les informations de diagnostic appropriées dans cet appel de méthode.

//Extract the tracing service for use in debugging sandboxed plug-ins.
ITracingService tracingService =
    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

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

// For this sample, execute the plug-in code only while the client is online. 
tracingService.Trace("AdvancedPlugin: Verifying the client is not offline.");
if (context.IsExecutingOffline || context.IsOfflinePlayback)
    return;

// 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.
    tracingService.Trace
        ("AdvancedPlugin: Getting the target entity from Input Parameters.");
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the image entity from the Pre Entity Images.
    tracingService.Trace
        ("AdvancedPlugin: Getting image entity from PreEntityImages.");
    Entity image = (Entity)context.PreEntityImages["Target"];

Puis, créez et déployez l'exécution du plug-in ou l'activité de workflow personnalisée. Lors de l'exécution du code personnalisé, les informations fournies dans les appels de méthode Trace sont entrées dans les enregistrements d'entité des journaux de suivi par ITracingService, si ce dernier est pris en charge par votre organisation et s'il est activé. L'utilisateur y a aussi accès, dans une boîte de dialogue Web ou une tâche système, comme décrit dans la section précédente. Les informations de suivi entrées au journal de suivi sont configurées dans les paramètres de suivi. Pour plus d'informations, voir Activer la journalisation du suivi.

À propos du service de suivi

ITracingService traite par lots les informations fournies y via la méthode Trace. Les informations sont écrites dans un nouvel enregistrement PluginTraceLog lorsque code personnalisé s'exécute jusqu'à la fin ou qu'une exception est levée.

Les enregistrements PluginTraceLog ont un cycle de vie limité. Une tâche de suppression en bloc en arrière-plan s'exécute une fois par jour pour supprimer les enregistrements créés depuis plus de 24 heures. Si nécessaire, cette tâche peut être désactivée.

Voir aussi

Développement de plug-ins
Analyser les performances des plug-ins
Inscrire et déployer des plug-ins
Pipeline d’exécution des événements
Écrire un plug-in
Isolement, approbations et statistiques des plug-ins
Messages et méthodes de l'entité PluginTraceLog

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright