Débogage du code managé en utilisant le débogueur Windows

Article
10/16/2024

Vous pouvez utiliser les débogueurs Windows (WinDbg, CDB et NTSD) pour déboguer des applications cibles contenant du code géré. Pour déboguer du code géré, utilisez l'extension de débogage !SOS (sos.dll) et un composant d'accès aux données (mscordacwks.dll) en combinaison avec le moteur d'exécution CLR.

Les débogueurs Windows, tels que WinDbg, sont distincts du débogueur Visual Studio. Pour plus d'informations sur la distinction entre les débogueurs Windows et le débogueur Visual Studio, voir Outils de débogage pour Windows.

Cet article fournit des instructions sur l'utilisation des débogueurs Windows (WinDbg, CDB, NTSD) pour déboguer le code géré, y compris les applications .NET Framework, .NET Core et .NET 5+.

Remarque

Lorsque vous déboguez des applications .NET Framework, .NET Core et .NET 5+, assurez-vous que vous utilisez la dernière version des outils du débogueur Windows. En outre, envisagez d'utiliser Visual Studio ou Visual Studio Code pour une expérience de débogage plus intégrée. WinDbg est plus complexe, demande plus de travail de configuration et est généralement utilisé lorsque des informations de bas niveau supplémentaires sont nécessaires.

Introduction au code géré

Le code géré est exécuté avec le Microsoft .NET Common Language Runtime (CLR). Dans une application à code géré, le code binaire produit par le compilateur est en langage intermédiaire Microsoft (MSIL), qui est indépendant de la plate-forme.

Lorsque le code géré est exécuté, le moteur d'exécution produit du code natif qui est spécifique à la plate-forme. Le processus de génération de code natif à partir de MSIL est appelé compilation juste à temps (JIT). Une fois que le compilateur JIT a compilé le MSIL pour une méthode spécifique, le code natif de la méthode reste en mémoire. Lorsque cette méthode est appelée ultérieurement, le code natif s'exécute et le compilateur JIT n'a pas à intervenir.

Vous pouvez créer du code géré en utilisant plusieurs compilateurs fabriqués par divers producteurs de logiciels. En particulier, Microsoft Visual Studio peut construire du code géré à partir de plusieurs langages différents, notamment C#, Visual Basic, JScript et C++ avec des extensions gérées.

Le CLR n'est pas mis à jour à chaque fois que le framework .NET est mis à jour. Par exemple, les versions 2.0, 3.0 et 3.5 du framework .NET utilisent toutes la version 2.0 du CLR. Pour plus d'informations sur les versions de .NET, voir versions et dépendances du framework .NET. Pour plus d'informations sur la détermination de la version de .NET sur votre PC, voir Déterminer quelles versions de .NET Framework sont installées.

Débogage du code managé

Pour déboguer du code géré à l'aide de l'extension de débogage !SOS, le débogueur doit charger différents composants. L'extension de débogage !SOS et les composants requis qui sont utilisés diffèrent pour .NET Core et le framework .NET original. Dans les deux cas, le composant d'accès aux données (DAC) (mscordacwks.dll) est utilisé.

Le SDK .NET fournit des outils qui peuvent être utiles pour travailler sur le débogage des applications .NET. Pour plus d'informations, voir Qu'est-ce que le SDK .NET ?.

.NET Core

Pour .NET Core ou .NET 5+ et les versions ultérieures, la durée d'exécution est coreclr.dll. Pour plus d'informations, voir la présentation du Common Language Runtime (CLR).
Extension de débogage SOS .NET Core

Pour .NET Core, un outil CLI dotnet est disponible pour installer !sos.dll. Pour plus d'informations, voir le programme d'installation SOS (dotnet-sos).

Le framework .NET original.

Pour le framework .NET original, clr.dll est la durée d'exécution.
Extension de débogage SOS (sos.dll)

Obtenir l'extension de débogage SOS (sos.dll)

Les fichiers de l'extension de débogage SOS (sos.dll) ne sont pas inclus dans toutes les versions des outils de débogage pour Windows. Si sos.dll n'est pas disponible, consultez la section Installation de SOS sous Windows.

Chargement de l'extension de débogage SOS (sos.dll)

Pour déboguer les applications .NET Core et .NET 5+, vous devez charger la version appropriée de l'extension de débogage SOS.

Par exemple, pour une version de !SOS qui est incluse avec le débogueur et qui est incluse dans le chemin de recherche de l'extension actuelle, la commande .load serait utilisée.

0:000> .load sos.dll

Pour vérifier que l'extension de débogage SOS s'est chargée correctement, utilisez la commande .chain et examinez la chaîne de la DLL d'extension.

...
Extension DLL chain:
    C:\Windows\Microsoft.NET\Framework\v4.0.30319\SOS.dll: image 4.8.9275.0, API 1.0.0, built Wed Aug 28 14:43:27 2024
        [path: C:\Windows\Microsoft.NET\Framework\v4.0.30319\SOS.dll]
    C:\Program Files (x86)\dotnet\shared\Microsoft.NETCore.App\8.0.8\coreclr.dll: image 8,0,824,36612 @Commit: 08338fcaa5c9b9a8190abb99222fed12aaba956c, built Tue Jul 16 11:10:19 2024
        [path: C:\Program Files (x86)\dotnet\shared\Microsoft.NETCore.App\8.0.8\coreclr.dll]

Si la version du débogueur n'inclut pas le fichier sos.dll, vous devrez peut-être spécifier le chemin d'accès complet au fichier SOS.dll. Vous trouverez généralement le fichier SOS.dll dans le répertoire d'exécution de votre installation .NET Core ou .NET Framework.

0:000> .load C:\Windows\Microsoft.NET\Framework64\v4.0.30319\sos.dll

Chargement d'une version spécifique de sos.dll

Le chargement de sos.dll peut être complexe, car il existe une dépendance à l'égard des DLL supplémentaires utilisées par sos.dll pour communiquer avec .NET. En outre, la version de DLL requise dépend de la version .NET de l'application en cours de débogage, et plusieurs versions de .NET peuvent être présentes sur la machine.

Une stratégie pour charger la bonne version de la DLL dépendante consiste à demander au débogueur d'intervenir lorsque la première notification clr (CLRN) de .NET se produit à l'aide de la commande sx, sxd, sxe, sxi, sxn, sxr, sx- (Set Exceptions)[../debuggercmds/sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md]. Une fois que vous vous êtes attaché à l'application .NET cible, cette commande sera utilisée après la première interruption.

0:000> sxe CLRN

Reprenez ensuite l'exécution et attendez que l'interruption se produise.

0:000> g

Lorsque l'interruption se produit, désactivez la notification d'interruption de clr, car nous savons que clr.dll (ou coreclr.dll) a été chargé.

0:000> sxd CLRN

Avec le débogueur dans ce contexte, utilisez .loadby pour charger le !sos à partir du même répertoire « proche ».

0:000> .loadby sos clr

Une autre option consiste à utiliser la commande .cordll (Control CLR Debugging) pour charger les DLL de débogage du CLR en fournissant un chemin d'accès à l'emplacement du framework cible.

0:000> .cordll -ve -u -lp C:\Windows\Microsoft.NET\Framework\v4.0.30319\
CLRDLL: Loaded DLL C:\Windows\Microsoft.NET\Framework\v4.0.30319\mscordacwks.dll
Automatically loaded SOS Extension
CLR DLL status: Loaded DLL C:\Windows\Microsoft.NET\Framework\v4.0.30319\mscordacwks.dll

Utilisation de l'extension de débogage SOS

Pour vérifier que l'extension de débogage SOS a été correctement chargée, entrez la commande .chain.

0:000> .chain
Extension DLL search Path:
    C:\Program Files\Debugging Tools for Windows (x64);...
Extension DLL chain:
    C:\Windows\Microsoft.NET\Framework\v4.0.30319\SOS.dll: image 4.8.9275.0, API 1.0.0, built Wed Aug 28 14:43:27 2024
        [path: C:\Windows\Microsoft.NET\Framework\v4.0.30319\SOS.dll]
...

Fichiers de symboles .NET

Les fichiers de symboles sont essentiels pour le débogage. Pour les applications .NET Framework, .NET Core et .NET 5+, vous pouvez récupérer les fichiers de symboles nécessaires à partir du serveur de symboles public de Microsoft. Utilisez la commande suivante pour définir le chemin d'accès aux symboles et lancer le chargement des symboles.

.symfix

!sym noisy

.reload

Test de l'extension .NET Core !sos

Pour tester l'extension de débogage SOS, entrez !sos.help.

0:000> !sos.help
-------------------------------------------------------------------------------
SOS is a debugger extension DLL designed to aid in the debugging of managed
programs. Functions are listed by category, then roughly in order of
importance. Shortcut names for popular functions are listed in parenthesis.
Type "!help <functionname>" for detailed info on that function. 

Object Inspection                  Examining code and stacks
-----------------------------      -----------------------------
DumpObj (do)                       Threads
DumpArray (da)                     ThreadState
DumpStackObjects (dso)             IP2MD
DumpHeap                           U
DumpVC                             DumpStack
GCRoot                             EEStack
ObjSize                            CLRStack
FinalizeQueue                      GCInfo
PrintException (pe)                EHInfo
TraverseHeap                       BPMD 
                                   COMState

Essayez ensuite l'une des commandes fournies par l'extension de débogage SOS. Par exemple, vous pouvez essayer !sos.DumpDomain ou la commande !sos.Threads fournie par l'extension de débogage SOS .NET Core.

0:000> !sos.DumpDomain
--------------------------------------
System Domain:      7565d980
LowFrequencyHeap:   7565dca4
HighFrequencyHeap:  7565dcf0
StubHeap:           7565dd3c
Stage:              OPEN
Name:               None
--------------------------------------
Shared Domain:      7565d620
LowFrequencyHeap:   7565dca4
HighFrequencyHeap:  7565dcf0
StubHeap:           7565dd3c
Stage:              OPEN
Name:               None
Assembly:           00fa5e78 [C:\WINDOWS\Microsoft.Net\assembly\GAC_32\mscorlib\v4.0_4.0.0.0__b77a5c561934e089\mscorlib.dll]
ClassLoader:        00fa5f40
  Module Name
73571000    C:\WINDOWS\Microsoft.Net\assembly\GAC_32\mscorlib\v4.0_4.0.0.0__b77a5c561934e089\mscorlib.dll

0:000> !sos.Threads
ThreadCount:      2
UnstartedThread:  0
BackgroundThread: 2
PendingThread:    0
DeadThread:       0
Hosted Runtime:   no
                                                                         Lock  
       ID OSID ThreadOBJ    State GC Mode     GC Alloc Context  Domain   Count Apt Exception
   0    1 4538 00f91110     20220 Preemptive  02FE1238:00000000 00f58be0 1     Ukn 
   7    2 250c 00f9da88     21220 Cooperative 00000000:00000000 00f58be0 1     Ukn (Finalizer)

Test de l'extension .NET Framework !sos

Pour tester l'extension de débogage SOS, entrez !sos.help. Essayez ensuite l'une des commandes fournies par l'extension de débogage SOS. Par exemple, vous pouvez essayer !sos.sostatus ou la commande !sos.threads.

0:030> !soshelp
crashinfo                                 Displays the crash details that created the dump.
help, soshelp <command>                   Displays help for a command.
loadsymbols <url>                         Loads symbols for all modules.
logclose <path>                           Disables console file logging.
logging <path>                            Enables/disables internal diagnostic logging.
logopen <path>                            Enables console file logging.
maddress                                  Displays a breakdown of the virtual address space.
modules, lm                               Displays the native modules in the process.
registers, r                              Displays the thread's registers.
runtimes <id>                             Lists the runtimes in the target or changes the default runtime.
setclrpath <path>                         Sets the path to load coreclr DAC/DBI files.
setsymbolserver, SetSymbolServer <url>    Enables and sets symbol server support for symbols and module download.
sosflush                                  Resets the internal cached state.
sosstatus                                 Displays internal status.
threads, setthread <thread>               Lists the threads in the target or sets the current thread.

Notes

Il arrive qu'une application à code géré charge plus d'une version du CLR. Dans ce cas, vous devez spécifier la version du DAC à charger. Pour plus d'informations, voir .cordll et Clrver.exe (CLR Version Tool).

Partager via