Condividi tramite

Utilità di code coverage dotnet-coverage

  • Articolo

Questo articolo si applica a: ✔️ .NET Core 3.1 SDK e versioni successive

Riepilogo

dotnet-coverage [-h, --help] [--version] <command>

Descrizione

Lo strumento dotnet-coverage:

  • Abilita la raccolta multipiattaforma dei dati di code coverage di un processo in esecuzione.
  • Fornisce l'unione multipiattaforma dei report di code coverage.

Opzioni

  • -h|--help

    Mostra la Guida della riga di comando.

  • --version

    Visualizza la versione dell'utilità dotnet-coverage.

Installare

Per installare la versione più recente del dotnet-coveragepacchetto NuGet, usare il comando dotnet tool install:

dotnet tool install --global dotnet-coverage

Comandi

Comando
unione dotnet-coverage
raccolta dotnet-coverage
connessione dotnet-coverage
snapshot dotnet-coverage
arresto dotnet-coverage
strumento dotnet-coverage

unione dotnet-coverage

Il comando merge viene usato per unire più report di code coverage in uno. Questo comando è disponibile in tutte le piattaforme. Questo comando supporta i formati di report di code coverage seguenti:

  • coverage
  • cobertura
  • xml

Riepilogo

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>

Argomenti

  • <files>

    Report di code coverage di input.

Opzioni

  • --remove-input-files

    Rimuove tutti i report di copertura di input che sono stati uniti.

  • -r, --recursive

    .NET 7 SDK e versioni precedenti cercano solo report di copertura nelle sottodirectory.

  • -o|--output <output>

    Imposta il file di output del report code coverage.

  • -f|--output-format <output-format>

    Formato del file di output. Valori supportati: coverage, xml e cobertura. Il valore predefinito è coverage (formato binario che può essere aperto in Visual Studio).

  • -l|--log-file <log-file>

    Immettere il percorso del file log. Quando si specifica una directory (con un separatore di percorso alla fine), viene generato un nuovo file di log per ogni processo sottoposto ad analisi.

  • -ll|--log-level <log-level>

    Imposta il livello di log. Valori supportati: Error, Info e Verbose.

raccolta dotnet-coverage

Il comando collect viene usato per raccogliere i dati di code coverage per qualsiasi processo .NET e i relativi sottoprocessi. Ad esempio, è possibile raccogliere dati di code coverage per un'applicazione console o un'applicazione Blazor. Questo comando supporta la strumentazione dinamica e statica. La strumentazione statica è disponibile in tutte le piattaforme. È possibile specificare i file da instrumentare in modo statico usando l'opzione include-files. La strumentazione dinamica è disponibile in Windows (x86, x64 e Arm64), Linux (x64) e macOS (x64). Il comando supporta solo i moduli .NET. I moduli nativi non sono supportati.

Riepilogo

Il comando collect può essere eseguito in due modalità.

Modalità di comando

Il comando collect raccoglierà il code coverage per il processo specificato eseguito dall'argomento 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>

Modalità server

Il comando collect ospita un server per la raccolta di code coverage. I client possono connettersi al server tramite il comando 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]

Argomenti

  • <command>

    Comando per il quale raccogliere i dati di code coverage.

  • <args>

    Argomenti della riga di comando per il comando.

Opzioni

  • -s|--settings <settings>

    Imposta il percorso delle impostazioni di code coverage XML.

  • -id|--session-id <session-id>

    Specifica l'ID sessione di code coverage. Se non specificato, lo strumento genererà un GUID casuale.

  • -sv|--server-mode

    Avvia l'agente di raccolta in modalità server. I client possono connettersi al server con il comando connect.

  • -b|--background

    Avvia il server di raccolta code coverage in un nuovo processo in background. I client possono connettersi al server con il comando connect.

  • -t|--timeout

    Timeout (in millisecondi) per la comunicazione interprocesso tra client e server.

  • -if|--include-files <include-files>

    Specifica l'elenco di file da instrumentare in modo statico.

  • -o|--output <output>

    Imposta il file di output del report code coverage.

  • -f|--output-format <output-format>

    Formato del file di output. Valori supportati: coverage, xml e cobertura. Il valore predefinito è coverage (formato binario che può essere aperto in Visual Studio).

  • -l|--log-file <log-file>

    Immettere il percorso del file log. Quando si specifica una directory (con un separatore di percorso alla fine), viene generato un nuovo file di log per ogni processo sottoposto ad analisi.

  • -ll|--log-level <log-level>

    Imposta il livello di log. Valori supportati: Error, Info e Verbose.

connessione dotnet-coverage

Il comando connect viene usato per connettersi al server esistente e raccoglie i dati di code coverage per qualsiasi processo .NET e i relativi sottoprocessi. Ad esempio, è possibile raccogliere dati di code coverage per un'applicazione console o un'applicazione Blazor. Il comando supporta solo i moduli .NET. I moduli nativi non sono supportati.

Nota

Il comando userà la strumentazione dinamica per tutti i sottoprocessi disponibili in Windows (x86, x64 e Arm64), Linux (x64) e macOS (x64). Se è necessario instrumentare in modo statico qualsiasi modulo .NET, usare il comando instrument (con l'opzione ID sessione corrispondente) prima di eseguire il comando connect.

Riepilogo

dotnet-coverage connect
    [-b|--background] [-t|--timeout]
    [-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
    <session>
    <command> <args>

Argomenti

  • <session>

    ID sessione del server ospitato dal comando collect.

  • <command>

    Comando per il quale raccogliere i dati di code coverage.

  • <args>

    Argomenti della riga di comando per il comando.

Opzioni

  • -b|--background

    Avvia il client in un nuovo processo in background.

  • -t|--timeout

    Timeout (in millisecondi) per la comunicazione interprocesso tra il client e il server.* -l|--log-file <log-file>

  • -l|--log-file <log-file>

    Immettere il percorso del file log. Quando si specifica una directory (con un separatore di percorso alla fine), viene generato un nuovo file di log per ogni processo sottoposto ad analisi.

  • -ll|--log-level <log-level>

    Imposta il livello di log. Valori supportati: Error, Info e Verbose.

snapshot dotnet-coverage

Crea un file di copertura per la raccolta di code coverage esistente.

Riepilogo

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>

Argomenti

  • <session>

    ID sessione della raccolta per cui deve essere generato un file di copertura.

Opzioni

  • -r|--reset <reset>

    Cancella le informazioni di copertura esistenti dopo la creazione di un file di copertura.

  • -o|--output <output>

    Imposta il file di output del report code coverage. Se non specificato, viene generato automaticamente con un timestamp.

  • -tn|--tag-name <tag-name>

    Crea un nome di tag snapshot nel file di copertura con le informazioni di copertura correnti. Tag-name e tag-identifier sono inclusivi a vicenda.

  • -tid|--tag-identifier <tag-identifier>

    Crea un identificatore di tag snapshot nel file di copertura con le informazioni di copertura correnti. Tag-name e tag-identifier sono inclusivi a vicenda.

  • -t|--timeout

    Timeout (in millisecondi) per la comunicazione interprocesso tra il client e il server.

  • -l|--log-file <log-file>

    Immettere il percorso del file log. Quando si specifica una directory (con un separatore di percorso alla fine), viene generato un nuovo file di log per ogni processo sottoposto ad analisi.

  • -ll|--log-level <log-level>

    Imposta il livello di log. Valori supportati: Error, Info e Verbose.

arresto dotnet-coverage

Chiude la raccolta code coverage esistente.

Riepilogo

dotnet-coverage shutdown
    [-t|--timeout]
    [-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
    <session>

Argomenti

  • <session>

    ID sessione della raccolta da chiudere.

Opzioni

  • -t|--timeout

    Timeout (in millisecondi) per la comunicazione interprocesso con il server.

  • -l|--log-file <log-file>

    Immettere il percorso del file log. Quando si specifica una directory (con un separatore di percorso alla fine), viene generato un nuovo file di log per ogni processo sottoposto ad analisi.

  • -ll|--log-level <log-level>

    Imposta il livello di log. Valori supportati: Error, Info e Verbose.

strumento dotnet-coverage

Il comando strumento viene usato per instrumentare il file binario su disco.

Riepilogo

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>

Argomenti

  • <input-file>

    Binario di input.

Opzioni

  • -s|--settings <settings>

    Imposta il percorso delle impostazioni di code coverage XML.

  • -id|--session-id <session-id>

    Specifica l'ID sessione di code coverage. Se non specificato, lo strumento genererà un GUID casuale.

  • -o|--output <output>

    Imposta il percorso del file binario di output. Se non specificato, la strumentazione verrà eseguita sul posto.

  • -l|--log-file <log-file>

    Immettere il percorso del file log. Quando si specifica una directory (con un separatore di percorso alla fine), viene generato un nuovo file di log per ogni processo sottoposto ad analisi.

  • -ll|--log-level <log-level>

    Imposta il livello di log. Valori supportati: Error, Info e Verbose.

Scenari di esempio

Raccolta di code coverage

Raccogliere i dati di code coverage per qualsiasi applicazione .NET (ad esempio console o Blazor) usando il comando seguente:

dotnet-coverage collect dotnet run

Nel caso di un'applicazione che richiede un segnale da terminare, è possibile usare CTRL+C, che consente comunque di raccogliere i dati di code coverage. Per l'argomento, è possibile specificare qualsiasi comando che alla fine avvierà un'app .NET. Ad esempio, può essere uno script di PowerShell.

Sessioni

Quando si esegue l'analisi del code coverage in un server .NET che attende solo i messaggi e invia risposte, è necessario un modo per arrestare il server per ottenere i risultati finali del code coverage. È possibile usare CTRL+C in locale, ma non in Azure Pipelines. Per questi scenari, è possibile usare le sessioni. È possibile specificare un ID sessione all'avvio della raccolta e quindi usare il comando shutdown per arrestare la raccolta e il server.

Si supponga, ad esempio, di avere un server nella directory D:\serverexample\server e un progetto di test nella directory D:\serverexample\tests. I test comunicano con il server tramite la rete. È possibile avviare la raccolta di code coverage per il server come indicato di seguito:

D:\serverexample\server> dotnet-coverage collect --session-id serverdemo "dotnet run"

L'ID sessione è stato specificato come serverdemo. È quindi possibile eseguire i test come segue:

D:\serverexample\tests> dotnet test

È possibile generare un file di code coverage per serverdemo della sessione con copertura corrente come indicato di seguito:

dotnet-coverage snapshot --output after_first_test.coverage serverdemo

Inoltre, è possibile aggiungere un tag snapshot al file di copertura usando le opzioni tag come indicato di seguito:

dotnet-coverage snapshot --tag-name after_first_test --tag-identifier after_first_test serverdemo

Infine, serverdemo della sessione e il server possono essere chiusi nel modo seguente:

dotnet-coverage shutdown serverdemo

Di seguito è riportato un esempio di output completo sul lato server:

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>

Modalità server e client

La raccolta di code coverage può essere eseguita anche in modalità client server. In questo scenario viene avviato un server di raccolta code coverage e più client possono connettersi al server. Il code coverage viene raccolto per tutti i client collettivamente.

Avviare il server code coverage usando il comando seguente:

dotnet-coverage collect --session-id serverdemo --server-mode

In questo esempio l'ID sessione è stato specificato come serverdemo per il server. Un client può connettersi al server usando questo ID sessione usando il comando seguente:

dotnet-coverage connect serverdemo dotnet run

Infine, è possibile chiudere serverdemo della sessione e il server usando il comando seguente:

dotnet-coverage shutdown serverdemo

Il processo del server crea un report di code coverage collettivo per tutti i client e le uscite.

Di seguito è riportato un esempio di output completo sul lato server:

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>

Di seguito è riportato un esempio di output completo sul lato 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>

È anche possibile avviare sia il server che il client in modalità in background. Un altro processo viene avviato in background e restituisce il controllo all'utente.

Di seguito è riportato un esempio di output completo in modalità client del server in background:

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>

Code coverage statico per gli assembly gestiti

Lo strumento dotnet-coverage può essere usato per raccogliere code coverage per gli assembly gestiti usando la strumentazione statica. Sono disponibili tre metodi diversi che è possibile usare. Per dimostrare, si supponga di avere una semplice applicazione console C#:

D:\examples\ConsoleApp> dotnet run
Hello, World!

Usare il comando Collect con l'opzione includi file o la configurazione

Se non si vuole usare il comando instrument, è possibile specificare i file da instrumentare usando l'opzione --include-files come indicato di seguito:

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.

È anche possibile specificare i file da instrumentare usando la configurazione come indicato di seguito:

<ModulePaths>
  <IncludeDirectories>
    <Directory>D:\examples\ConsoleApp\bin\Debug\net7.0</Directory>
  </IncludeDirectories>
</ModulePaths>

Uso di strumento e raccolta di comandi

In questo caso, il primo file binario deve essere instrumentato come segue:

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.

È quindi possibile raccogliere il code coverage come segue:

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.

Usare lo strumento e raccogliere i comandi in modalità server

In questo caso, è possibile separare completamente la raccolta di copertura dall'esecuzione dell'applicazione. Prima di tutto, instrumentare il file binario come segue:

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.

Nota

L'ID sessione deve essere usato in questo scenario per assicurarsi che l'applicazione possa connettersi e fornire dati all'agente di raccolta esterno.

Nel secondo passaggio è necessario avviare l'agente di raccolta code coverage come indicato di seguito:

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

È quindi possibile avviare l'applicazione come segue:

D:\examples\ConsoleApp> .\bin\Debug\net7.0\ConsoleApp.exe
Hello, World!

Infine, l'agente di raccolta può essere chiuso nel modo seguente:

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.

Impostazione

È possibile specificare un file con le impostazioni quando si usa il comando collect. Il file di impostazioni può essere usato per escludere alcuni moduli o metodi dall'analisi del code coverage. Il formato corrisponde alla configurazione dell'agente di raccolta dati all'interno di un file runsettings. Per altre informazioni, vedere Personalizzare l'analisi code coverage. Ecco un esempio:

<?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>

Unire report di code coverage

È possibile unire a.coverage e b.coverage e archiviare i dati in merged.coverage come indicato di seguito:

dotnet-coverage merge -o merged.coverage a.coverage b.coverage

Ad esempio, se si esegue un comando come dotnet test --collect "Code Coverage", il report di copertura viene archiviato in una cartella denominata GUID casuale. Tali cartelle sono difficili da trovare e unire. Usando questo strumento, è possibile unire tutti i report di code coverage per tutti i progetti usando criteri GLOB come indicato di seguito:

dotnet-coverage merge -o merged.cobertura.xml -f cobertura **\*.coverage

Il comando precedente unisce tutti i report di copertura dalla directory corrente e tutte le sottodirectory e archivia il risultato in un file cobertura. In Azure Pipelines è possibile usare l'attività Pubblica risultati code coverage per pubblicare un report di cobertura unito.

È possibile usare il comando merge per convertire un report di code coverage in un altro formato. Ad esempio, il comando seguente converte un report di code coverage binario in formato XML.

dotnet-coverage merge -o output.xml -f xml input.coverage

Vedi anche