Utilitaire de couverture du code .NET
Cet article s’applique à : ✔️ SDK .NET Core 3.1 et versions ultérieures
Synopsis
dotnet-coverage [-h, --help] [--version] <command>
Description
L’outil dotnet-coverage
:
- Active la collecte multiplateforme des données de couverture du code d’un processus en cours d’exécution.
- Fournit la fusion multiplateforme des rapports de couverture du code.
Options
-h|--help
Affiche l’aide en ligne de commande.
--version
Affiche la version de l’utilitaire dotnet-coverage.
Installer
Pour installer la dernière version de version du dotnet-coverage
package NuGet, utilisez la commande d’installation de l’outil dotnet :
dotnet tool install --global dotnet-coverage
Commandes
Commande |
---|
fusion dotnet-coverage |
collecte de dotnet-coverage |
connexion de dotnet-coverage |
capture instantanée dotnet-coverage |
arrêt de dotnet-coverage |
instrument dotnet-coverage |
fusion dotnet-coverage
La commande merge
est utilisée pour fusionner plusieurs rapports de couverture de code en un seul. Cette commande est disponible sur toutes les plateformes. Cette commande prend en charge les formats de rapport de couverture du code suivants :
coverage
cobertura
xml
Synopsis
dotnet-coverage merge
[--remove-input-files]
[-o|--output <output>] [-f|--output-format <output-format>]
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
<files>
Arguments
<files>
Rapports de couverture du code d’entrée.
Options
--remove-input-files
Supprime tous les rapports de couverture d’entrée qui ont été fusionnés.
-r, --recursive
Le kit de développement logiciel (SDK) .NET 7 et les versions antérieures ne peuvent que rechercher des rapports de couverture dans les sous-répertoires.
-o|--output <output>
Définit le fichier de sortie du rapport de couverture du code.
-f|--output-format <output-format>
Format des fichiers de sortie. Les valeurs prises en charge sont :
coverage
,xml
etcobertura
. La valeur par défaut estcoverage
(format binaire qui peut être ouvert dans Visual Studio).-l|--log-file <log-file>
Définit le chemin d'accès du fichier journal. Quand vous fournissez un répertoire (avec un séparateur de chemin à la fin), un nouveau fichier journal est généré pour chaque processus analysé.
-ll|--log-level <log-level>
Définit le niveau de journalisation. Les valeurs prises en charge sont :
Error
,Info
etVerbose
.
collecte de dotnet-coverage
La commande collect
est utilisée pour collecter des données de couverture du code pour tout processus .NET et ses sous-processus. Par exemple, vous pouvez collecter des données de couverture du code pour une application console ou une application Blazor. Cette commande prend en charge l’instrumentation dynamique et statique. L’instrumentation statique est disponible sur toutes les plateformes. Vous pouvez spécifier des fichiers à instrumenter de manière statique à l’aide de l’option include-files
. L’instrumentation dynamique est disponible sur Windows (x86, x64 et Arm64), Linux (x64) et macOS (x64). La commande prend uniquement en charge les modules .NET. Les modules ne sont pas pris en charge.
Synopsis
La commande collect
peut s’exécuter sur deux modes.
Mode Commande
La commande collect
collecte la couverture du code pour le processus donné exécuté par l’argument command
.
dotnet-coverage collect
[-s|--settings <settings>] [-id|--session-id <session-id>]
[-if|--include-files <include-files>] [-o|--output <output>]
[-f|--output-format <output-format>] [-l|--log-file <log-file>]
[-ll|--log-level <log-level>] [-?|-h|--help]
<command> <args>
Mode serveur
La commande collect
héberge un serveur pour la collection de couverture du code. Les clients peuvent se connecter au serveur via une commande connect
.
dotnet-coverage collect
[-s|--settings <settings>] [-id|--session-id <session-id>]
[-sv|--server-mode] [-b|--background] [-t|--timeout]
[-if|--include-files <include-files>] [-o|--output <output>]
[-f|--output-format <output-format>] [-l|--log-file <log-file>]
[-ll|--log-level <log-level>] [-?|-h|--help]
Arguments
<command>
Commande pour laquelle collecter des données de couverture du code.
<args>
Arguments de ligne de commande pour la commande.
Options
-s|--settings <settings>
Définit le chemin d’accès aux paramètres de couverture du code XML.
-id|--session-id <session-id>
Spécifie l’ID de session de couverture du code. S’il n’est pas fourni, l’outil génère un GUID aléatoire.
-sv|--server-mode
Démarre le collecteur en mode serveur. Les clients peuvent se connecter au serveur via une commande
connect
.-b|--background
Démarre le serveur de collection de couverture du code dans un nouveau processus en arrière-plan. Les clients peuvent se connecter au serveur via une commande
connect
.-t|--timeout
Délai d’expiration (en millisecondes) pour la communication entre les clients et le serveur.
-if|--include-files <include-files>
Spécifie la liste des fichiers à instrumenter de manière statique.
-o|--output <output>
Définit le fichier de sortie du rapport de couverture du code.
-f|--output-format <output-format>
Format des fichiers de sortie. Les valeurs prises en charge sont :
coverage
,xml
etcobertura
. La valeur par défaut estcoverage
(format binaire qui peut être ouvert dans Visual Studio).-l|--log-file <log-file>
Définit le chemin d'accès du fichier journal. Quand vous fournissez un répertoire (avec un séparateur de chemin à la fin), un nouveau fichier journal est généré pour chaque processus analysé.
-ll|--log-level <log-level>
Définit le niveau de journalisation. Les valeurs prises en charge sont :
Error
,Info
etVerbose
.
connexion de dotnet-coverage
La commande connect
est utilisée pour se connecter au serveur existant et collecte les données de couverture du code pour tout processus .NET et ses sous-processus. Par exemple, vous pouvez collecter des données de couverture du code pour une application console ou une application Blazor. La commande prend uniquement en charge les modules .NET. Les modules ne sont pas pris en charge.
Notes
La commande utilise l’instrumentation dynamique pour tous les sous-processus disponibles sur Windows (x86, x64 et Arm64), Linux (x64) et macOS (x64). Si vous devez instrumenter statiquement un module .NET, utilisez la commande instrument
(avec l’option d’ID de session correspondante) avant d’exécuter la commande connect
.
Synopsis
dotnet-coverage connect
[-b|--background] [-t|--timeout]
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
<session>
<command> <args>
Arguments
<session>
ID de session du serveur hébergé par la commande
collect
.<command>
Commande pour laquelle collecter des données de couverture du code.
<args>
Arguments de ligne de commande pour la commande.
Options
-b|--background
Démarre le client dans un nouveau processus en arrière-plan.
-t|--timeout
Délai d’expiration (en millisecondes) pour la communication entre le client et le serveur.*
-l|--log-file <log-file>
-l|--log-file <log-file>
Définit le chemin d'accès du fichier journal. Quand vous fournissez un répertoire (avec un séparateur de chemin à la fin), un nouveau fichier journal est généré pour chaque processus analysé.
-ll|--log-level <log-level>
Définit le niveau de journalisation. Les valeurs prises en charge sont :
Error
,Info
etVerbose
.
capture instantanée dotnet-coverage
Crée un fichier de couverture pour la collection de couverture de code existante.
Synopsis
dotnet-coverage snapshot
[-r|--reset]
[-o|--output <output>]
[-tn|--tag-name <tag-name>] [-tid|--tag-identifier <tag-identifier>]
[-t|--timeout]
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
<session>
Arguments
<session>
ID de session de la collection pour laquelle un fichier de couverture doit être généré.
Options
-r|--reset <reset>
Efface les informations de couverture existantes après la création d’un fichier de couverture.
-o|--output <output>
Définit le fichier de sortie du rapport de couverture du code. S’il n’est pas fourni, il est généré automatiquement avec un timestamp.
-tn|--tag-name <tag-name>
Crée un nom de balise d’instantané dans le fichier de couverture avec les informations de couverture actuelles. Tag-name et tag-identifier sont mutuellement inclusifs.
-tid|--tag-identifier <tag-identifier>
Crée un identificateur de balise d’instantané dans le fichier de couverture avec les informations de couverture actuelles. Tag-name et tag-identifier sont mutuellement inclusifs.
-t|--timeout
Délai d’expiration (en millisecondes) pour la communication entre le client et le serveur.
-l|--log-file <log-file>
Définit le chemin d'accès du fichier journal. Quand vous fournissez un répertoire (avec un séparateur de chemin à la fin), un nouveau fichier journal est généré pour chaque processus analysé.
-ll|--log-level <log-level>
Définit le niveau de journalisation. Les valeurs prises en charge sont :
Error
,Info
etVerbose
.
arrêt de dotnet-coverage
Ferme la collection de couverture du code existante.
Synopsis
dotnet-coverage shutdown
[-t|--timeout]
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
<session>
Arguments
<session>
ID de session de la collection à fermer.
Options
-t|--timeout
Délai d’expiration (en millisecondes) pour la communication entre processus avec le serveur.
-l|--log-file <log-file>
Définit le chemin d'accès du fichier journal. Quand vous fournissez un répertoire (avec un séparateur de chemin à la fin), un nouveau fichier journal est généré pour chaque processus analysé.
-ll|--log-level <log-level>
Définit le niveau de journalisation. Les valeurs prises en charge sont :
Error
,Info
etVerbose
.
instrument dotnet-coverage
La commande d’instrument est utilisée pour instrumenter un fichier binaire sur le disque.
Synopsis
dotnet-coverage instrument
[-s|--settings <settings>] [-id|--session-id <session-id>]
[-o|--output <output>] [-l|--log-file <log-file>]
[-ll|--log-level <log-level>] [-?|-h|--help]
<input-file>
Arguments
<input-file>
Binaire d’entrée.
Options
-s|--settings <settings>
Définit le chemin d’accès aux paramètres de couverture du code XML.
-id|--session-id <session-id>
Spécifie l’ID de session de couverture du code. S’il n’est pas fourni, l’outil génère un GUID aléatoire.
-o|--output <output>
Définit le chemin d’accès au fichier binaire de sortie. S’il n’est pas fourni, l’instrumentation est effectuée sur place.
-l|--log-file <log-file>
Définit le chemin d’accès du fichier journal. Quand vous fournissez un répertoire (avec un séparateur de chemin à la fin), un nouveau fichier journal est généré pour chaque processus analysé.
-ll|--log-level <log-level>
Définit le niveau de journalisation. Les valeurs prises en charge sont :
Error
,Info
etVerbose
.
Exemples de scénarios
Collecte de la couverture du code
Collectez les données de couverture du code pour n’importe quelle application .NET (par exemple console ou Blazor) à l’aide de la commande suivante :
dotnet-coverage collect dotnet run
Dans le cas d’une application qui nécessite l’arrêt d’un signal, vous pouvez utiliser Ctrl+C, qui vous permettra de collecter des données de couverture du code. Pour l’argument, vous pouvez fournir n’importe quelle commande qui démarrera éventuellement une application .NET. Par exemple, il peut s’agir d’un script PowerShell.
Sessions
Lorsque vous exécutez une analyse de la couverture du code sur un serveur .NET qui attend simplement des messages et envoie des réponses, vous avez besoin d’un moyen d’arrêter le serveur pour obtenir les résultats finaux de couverture du code. Vous pouvez utiliser Ctrl+C localement, mais pas dans Azure Pipelines. Pour ces scénarios, vous pouvez utiliser des sessions. Vous pouvez spécifier un ID de session au démarrage d’une collection, puis utiliser la commande shutdown
pour arrêter la collection et le serveur.
Par exemple, supposons que vous avez un serveur dans le répertoire D:\serverexample\server et un projet de test dans le répertoire D:\serverexample\tests. Les tests communiquent avec le serveur via le réseau. Vous pouvez démarrer la collecte de couverture du code pour le serveur comme suit :
D:\serverexample\server> dotnet-coverage collect --session-id serverdemo "dotnet run"
L’ID de session a été spécifié en tant que serverdemo
. Vous pouvez ensuite exécuter des tests comme suit :
D:\serverexample\tests> dotnet test
Un fichier de couverture du code pour la session serverdemo
peut être généré avec la couverture actuelle comme suit :
dotnet-coverage snapshot --output after_first_test.coverage serverdemo
En outre, une balise d’instantané peut être ajoutée au fichier de couverture à l’aide des options de balise comme suit :
dotnet-coverage snapshot --tag-name after_first_test --tag-identifier after_first_test serverdemo
Enfin, la session serverdemo
et le serveur peuvent être fermés comme suit :
dotnet-coverage shutdown serverdemo
Voici un exemple de sortie complète côté serveur :
D:\serverexample\server> dotnet-coverage collect --session-id serverdemo "dotnet run"
SessionId: serverdemo
Waiting for a connection... Connected!
Received: Hello!
Sent: HELLO!
Waiting for a connection... Code coverage results: output.coverage.
D:\serverexample\server>
Mode serveur et client
La collecte de la couverture du code peut également être effectuée en mode serveur-client. Dans ce scénario, un serveur de collecte de couverture de code démarre et plusieurs clients peuvent se connecter au serveur. La couverture du code est collectée pour tous les clients collectivement.
Démarrez le serveur de couverture du code à l’aide de la commande suivante :
dotnet-coverage collect --session-id serverdemo --server-mode
Dans cet exemple, l’ID de session a été spécifié comme serverdemo
pour le serveur. Un client peut se connecter au serveur à l’aide de cet ID de session à l’aide de la commande suivante :
dotnet-coverage connect serverdemo dotnet run
Enfin, vous pouvez fermer la session serverdemo
et le serveur à l’aide de la commande suivante :
dotnet-coverage shutdown serverdemo
Le processus serveur crée un rapport de couverture du code collectif pour tous les clients et les sorties.
Voici un exemple de sortie complète côté serveur :
D:\serverexample\server> dotnet-coverage collect --session-id serverdemo --server-mode
SessionId: serverdemo
// Server will be in idle state and wait for connect and shutdown commands
Code coverage results: output.coverage.
D:\serverexample\server>
Voici un exemple de sortie complète côté client :
D:\serverexample\server> dotnet-coverage connect serverdemo ConsoleApplication.exe World
Hello World!!
D:\serverexample\server> dotnet-coverage connect serverdemo WpfApplication.exe
D:\serverexample\server> dotnet-coverage shutdown serverdemo
D:\serverexample\server>
Vous pouvez également démarrer le serveur et le client en mode arrière-plan. Un autre processus démarre en arrière-plan et retourne le contrôle à l’utilisateur.
Voici un exemple de sortie complète en mode client serveur en arrière-plan :
D:\serverexample\server> dotnet-coverage collect --session-id serverdemo --server-mode --background
D:\serverexample\server> dotnet-coverage connect --background serverdemo ConsoleApplication.exe World
D:\serverexample\server> dotnet-coverage connect --background serverdemo WpfApplication.exe
D:\serverexample\server> dotnet-coverage shutdown serverdemo
D:\serverexample\server>
Couverture du code statique pour les assemblys managés
L’outil dotnet-coverage peut être utilisé pour collecter la couverture du code pour les assemblys managés à l’aide de l’instrumentation statique. Vous pouvez utiliser trois méthodes différentes. Pour illustrer, supposons que nous avons une application console C# simple :
D:\examples\ConsoleApp> dotnet run
Hello, World!
Utiliser la commande de collection avec l’option ou la configuration Inclure des fichiers
Si vous ne souhaitez pas utiliser la commande instrument
, les fichiers à instrumenter peuvent être spécifiés à l’aide de l’option --include-files
comme suit :
D:\examples\ConsoleApp> dotnet-coverage collect --include-files .\bin\Debug\net7.0\*.dll dotnet run
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.
SessionId: 57862ec0-e512-49a5-8b66-2804174680fc
Hello, World!
Code coverage results: output.coverage.
Vous pouvez également spécifier les fichiers à instrumenter à l’aide de la configuration comme suit :
<ModulePaths>
<IncludeDirectories>
<Directory>D:\examples\ConsoleApp\bin\Debug\net7.0</Directory>
</IncludeDirectories>
</ModulePaths>
Utilisation des commandes d’instrument et de collection
Dans ce cas, le premier binaire doit être instrumenté comme suit :
D:\examples\ConsoleApp> dotnet-coverage instrument .\bin\Debug\net7.0\ConsoleApp.dll
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.
Input file successfully instrumented.
Vous pouvez ensuite collecter la couverture du code comme suit :
D:\examples\ConsoleApp> dotnet-coverage collect .\bin\Debug\net7.0\ConsoleApp.exe
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.
SessionId: a09e6bef-ff64-4b5f-8bb8-fc495ebb50ba
Hello, World!
Code coverage results: output.coverage.
Utiliser les commandes d’instrument et de collection en mode serveur
Dans ce cas, vous pouvez complètement séparer la collection de couverture de l’exécution de votre application. Tout d’abord, instrumentez votre binaire comme suit :
D:\examples\ConsoleApp> dotnet-coverage instrument --session-id 73c34ce5-501c-4369-a4cb-04d31427d1a4 .\bin\Debug\net7.0\ConsoleApp.dll
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.
Input file successfully instrumented.
Notes
L’ID de session doit être utilisé dans ce scénario pour s’assurer que l’application peut se connecter et fournir des données au collecteur externe.
Dans la deuxième étape, vous devez démarrer le collecteur de couverture comme suit :
D:\examples\ConsoleApp> dotnet-coverage collect --session-id 73c34ce5-501c-4369-a4cb-04d31427d1a4 --server-mode
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.
SessionId: 73c34ce5-501c-4369-a4cb-04d31427d1a4
Ensuite, l’application peut être démarrée comme suit :
D:\examples\ConsoleApp> .\bin\Debug\net7.0\ConsoleApp.exe
Hello, World!
Enfin, le collecteur peut être fermé comme suit :
D:\examples\ConsoleApp> dotnet-coverage shutdown 73c34ce5-501c-4369-a4cb-04d31427d1a4
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.
Paramètres
Vous pouvez spécifier un fichier avec des paramètres lorsque vous utilisez la commande collect
. Le fichier de paramètres peut être utilisé pour exclure certains modules ou méthodes de l’analyse de la couverture du code. Le format est identique à la configuration du collecteur de données à l’intérieur d’un fichier runsettings. Pour plus d’informations, consultez Personnaliser l’analyse de la couverture du code. Voici un exemple :
<?xml version="1.0" encoding="utf-8"?>
<Configuration>
<CodeCoverage>
<!--
Additional paths to search for .pdb (symbol) files. Symbols must be found for modules to be instrumented.
If .pdb files are in the same folder as the .dll or .exe files, they are automatically found. Otherwise, specify them here.
Note that searching for symbols increases code coverage run time. So keep this small and local.
-->
<SymbolSearchPaths>
<Path>C:\Users\User\Documents\Visual Studio 2012\Projects\ProjectX\bin\Debug</Path>
<Path>\\mybuildshare\builds\ProjectX</Path>
</SymbolSearchPaths>
<!--
About include/exclude lists:
Empty "Include" clauses imply all; empty "Exclude" clauses imply none.
Each element in the list is a regular expression (ECMAScript syntax). See /visualstudio/ide/using-regular-expressions-in-visual-studio.
An item must first match at least one entry in the include list to be included.
Included items must then not match any entries in the exclude list to remain included.
-->
<!-- Match assembly file paths: -->
<ModulePaths>
<Include>
<ModulePath>.*\.dll$</ModulePath>
<ModulePath>.*\.exe$</ModulePath>
</Include>
<Exclude>
<ModulePath>.*CPPUnitTestFramework.*</ModulePath>
</Exclude>
<!-- Additional directories from .NET assemblies should be statically instrumented: -->
<IncludeDirectories>
<Directory Recursive="true">C:\temp</Directory>
</IncludeDirectories>
</ModulePaths>
<!-- Match fully qualified names of functions: -->
<!-- (Use "\." to delimit namespaces in C# or Visual Basic, "::" in C++.) -->
<Functions>
<Exclude>
<Function>^Fabrikam\.UnitTest\..*</Function>
<Function>^std::.*</Function>
<Function>^ATL::.*</Function>
<Function>.*::__GetTestMethodInfo.*</Function>
<Function>^Microsoft::VisualStudio::CppCodeCoverageFramework::.*</Function>
<Function>^Microsoft::VisualStudio::CppUnitTestFramework::.*</Function>
</Exclude>
</Functions>
<!-- Match attributes on any code element: -->
<Attributes>
<Exclude>
<!-- Don't forget "Attribute" at the end of the name -->
<Attribute>^System\.Diagnostics\.DebuggerHiddenAttribute$</Attribute>
<Attribute>^System\.Diagnostics\.DebuggerNonUserCodeAttribute$</Attribute>
<Attribute>^System\.CodeDom\.Compiler\.GeneratedCodeAttribute$</Attribute>
<Attribute>^System\.Diagnostics\.CodeAnalysis\.ExcludeFromCodeCoverageAttribute$</Attribute>
</Exclude>
</Attributes>
<!-- Match the path of the source files in which each method is defined: -->
<Sources>
<Exclude>
<Source>.*\\atlmfc\\.*</Source>
<Source>.*\\vctools\\.*</Source>
<Source>.*\\public\\sdk\\.*</Source>
<Source>.*\\microsoft sdks\\.*</Source>
<Source>.*\\vc\\include\\.*</Source>
</Exclude>
</Sources>
<!-- Match the company name property in the assembly: -->
<CompanyNames>
<Exclude>
<CompanyName>.*microsoft.*</CompanyName>
</Exclude>
</CompanyNames>
<!-- Match the public key token of a signed assembly: -->
<PublicKeyTokens>
<!-- Exclude Visual Studio extensions: -->
<Exclude>
<PublicKeyToken>^B77A5C561934E089$</PublicKeyToken>
<PublicKeyToken>^B03F5F7F11D50A3A$</PublicKeyToken>
<PublicKeyToken>^31BF3856AD364E35$</PublicKeyToken>
<PublicKeyToken>^89845DCD8080CC91$</PublicKeyToken>
<PublicKeyToken>^71E9BCE111E9429C$</PublicKeyToken>
<PublicKeyToken>^8F50407C4E9E73B6$</PublicKeyToken>
<PublicKeyToken>^E361AF139669C375$</PublicKeyToken>
</Exclude>
</PublicKeyTokens>
<EnableStaticManagedInstrumentation>True</EnableStaticManagedInstrumentation>
<EnableDynamicManagedInstrumentation>True</EnableDynamicManagedInstrumentation>
</CodeCoverage>
</Configuration>
Fusionner des rapports de couverture du code
Vous pouvez fusionner a.coverage
et b.coverage
stocker les données dans merged.coverage
comme suit :
dotnet-coverage merge -o merged.coverage a.coverage b.coverage
Par exemple, si vous exécutez une commande comme dotnet test --collect "Code Coverage"
, le rapport de couverture est stocké dans un dossier nommé GUID aléatoire. Ces dossiers sont difficiles à trouver et à fusionner. Grâce à cet outil, vous pouvez fusionner tous les rapports de couverture de code pour l’ensemble de vos projets en utilisant des modèles d’utilisation des caractères génériques comme suit :
dotnet-coverage merge -o merged.cobertura.xml -f cobertura **\*.coverage
La commande précédente fusionne tous les rapports de couverture du répertoire actif et de tous les sous-répertoires et stocke le résultat dans un fichier cobertura. Dans Azure Pipelines, vous pouvez utiliser la tâche Publier les résultats de la couverture du code pour publier un rapport cobertura fusionné.
Vous pouvez utiliser la commande merge
pour convertir un rapport de couverture du code dans un autre format. Par exemple, la commande suivante convertit un rapport de couverture de code binaire au format XML.
dotnet-coverage merge -o output.xml -f xml input.coverage