nástroj dotnet-coverage code coverage utility

Tento článek se vztahuje na: ✔️ .NET Core 3.1 SDK a novější verze

Synopse

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

Popis

Nástroj dotnet-coverage :

• Umožňuje kolekci multiplatformních dat pokrytí kódu spuštěného procesu.
• Poskytuje sloučení sestav pokrytí kódu pro různé platformy.

Možnosti

• -h|--help

  Zobrazuje nápovědu k příkazovému řádku.

• --version

  Zobrazí verzi nástroje dotnet-coverage.

Instalace

Pokud chcete nainstalovat nejnovější verzi dotnet-coverage balíčku NuGet, použijte příkaz dotnet tool install :

dotnet tool install --global dotnet-coverage

Příkazy

dotnet-coverage merge

Příkaz merge slouží ke sloučení několika sestav pokrytí kódu do jednoho. Tento příkaz je k dispozici na všech platformách. Tento příkaz podporuje následující formáty sestav pokrytí kódu:

• coverage
• cobertura
• xml

Synopse

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>

Argumenty

• <files>

  Sestavy pokrytí vstupního kódu.

Možnosti

• --remove-input-files

  Odebere všechny sestavy pokrytí vstupu, které byly sloučeny.

• -r, --recursive

  Sada .NET 7 SDK a starší verze vyhledávají pouze sestavy pokrytí v podadresářích.

• -o|--output <output>

  Nastaví výstupní soubor sestavy pokrytí kódu.

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

  Formát výstupního souboru. Podporované hodnoty: coverage, xmla cobertura. Výchozí hodnota je coverage (binární formát, který lze otevřít v sadě Visual Studio).

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

  Nastaví cestu k souboru protokolu. Když zadáte adresář (s oddělovačem cest na konci), vygeneruje se pro každý proces v analýze nový soubor protokolu.

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

  Nastaví úroveň protokolu. Podporované hodnoty: Error, Infoa Verbose.

dotnet-coverage collect

Tento collect příkaz slouží ke shromažďování dat pokrytí kódu pro jakýkoli proces .NET a jeho podprocesy. Můžete například shromažďovat data pokrytí kódu pro konzolovou aplikaci nebo aplikaci Blazor. Tento příkaz podporuje dynamickou a statickou instrumentaci. Statické instrumentace je k dispozici na všech platformách. Pomocí možnosti můžete zadat soubory, které se mají staticky instrumentovat include-files . Dynamická instrumentace je dostupná ve Windows (x86, x64 a Arm64), Linuxu (x64) a macOS (x64). Příkaz podporuje pouze moduly .NET. Nativní moduly nejsou podporovány.

Synopse

Příkaz collect může běžet ve dvou režimech.

Režim příkazů

Příkaz collect shromáždí pokrytí kódu pro daný proces spuštěný argumentem 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>

Režim serveru

Příkaz collect hostuje server pro kolekci pokrytí kódu. Klienti se můžou připojit k serveru pomocí connect příkazu.

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]

Argumenty

• <command>

  Příkaz, pro který chcete shromažďovat data pokrytí kódu.

• <args>

  Argumenty příkazového řádku pro příkaz.

Možnosti

• -s|--settings <settings>

  Nastaví cestu k nastavení pokrytí kódu XML.

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

  Určuje ID relace pokrytí kódu. Pokud není zadaný, nástroj vygeneruje náhodný identifikátor GUID.

• -sv|--server-mode

  Spustí kolektor v režimu serveru. Klienti se můžou připojit k serveru pomocí connect příkazu.

• -b|--background

  Spustí server kolekce pokrytí kódu v novém procesu na pozadí. Klienti se můžou připojit k serveru pomocí connect příkazu.

• -t|--timeout

  Časový limit (v milisekundách) pro komunikaci mezi klienty a serverem

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

  Určuje seznam souborů, které se mají staticky instrumentovat.

• -o|--output <output>

  Nastaví výstupní soubor sestavy pokrytí kódu.

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

  Formát výstupního souboru. Podporované hodnoty: coverage, xmla cobertura. Výchozí hodnota je coverage (binární formát, který lze otevřít v sadě Visual Studio).

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

  Nastaví cestu k souboru protokolu. Když zadáte adresář (s oddělovačem cest na konci), vygeneruje se pro každý proces v analýze nový soubor protokolu.

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

  Nastaví úroveň protokolu. Podporované hodnoty: Error, Infoa Verbose.

dotnet-coverage connect

Tento connect příkaz slouží k připojení k existujícímu serveru a shromažďuje data pokrytí kódu pro všechny procesy .NET a jeho podprocesy. Můžete například shromažďovat data pokrytí kódu pro konzolovou aplikaci nebo aplikaci Blazor. Příkaz podporuje pouze moduly .NET. Nativní moduly nejsou podporovány.

Synopse

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

Argumenty

• <session>

  ID relace serveru hostovaného příkazem collect .

• <command>

  Příkaz, pro který chcete shromažďovat data pokrytí kódu.

• <args>

  Argumenty příkazového řádku pro příkaz.

Možnosti

• -b|--background

  Spustí klienta v novém procesu na pozadí.

• -t|--timeout

  Časový limit (v milisekundách) pro komunikaci mezi klientem a serverem.* -l|--log-file <log-file>

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

  Nastaví cestu k souboru protokolu. Když zadáte adresář (s oddělovačem cest na konci), vygeneruje se pro každý proces v analýze nový soubor protokolu.

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

  Nastaví úroveň protokolu. Podporované hodnoty: Error, Infoa Verbose.

dotnet-coverage snapshot

Vytvoří soubor pokrytí pro existující kolekci pokrytí kódu.

Synopse

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>

Argumenty

• <session>

  ID relace kolekce, pro kterou se má vygenerovat soubor pokrytí.

Možnosti

• -r|--reset <reset>

  Vymaže existující informace o pokrytí po vytvoření souboru pokrytí.

• -o|--output <output>

  Nastaví výstupní soubor sestavy pokrytí kódu. Pokud není zadaný, automaticky se vygeneruje s časovým razítkem.

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

  Vytvoří název značky snímku v souboru pokrytí s aktuálními informacemi o pokrytí. Název značky a identifikátor značky se vzájemně zahrnují.

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

  Vytvoří identifikátor značky snímku v souboru pokrytí s aktuálními informacemi o pokrytí. Název značky a identifikátor značky se vzájemně zahrnují.

• -t|--timeout

  Časový limit (v milisekundách) pro komunikaci mezi klientem a serverem

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

  Nastaví cestu k souboru protokolu. Když zadáte adresář (s oddělovačem cest na konci), vygeneruje se pro každý proces v analýze nový soubor protokolu.

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

  Nastaví úroveň protokolu. Podporované hodnoty: Error, Infoa Verbose.

dotnet-coverage shutdown

Zavře existující kolekci pokrytí kódu.

Synopse

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

Argumenty

• <session>

  ID relace kolekce, která se má zavřít.

Možnosti

• -t|--timeout

  Časový limit (v milisekundách) pro komunikaci mezi procesy se serverem

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

  Nastaví cestu k souboru protokolu. Když zadáte adresář (s oddělovačem cest na konci), vygeneruje se pro každý proces v analýze nový soubor protokolu.

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

  Nastaví úroveň protokolu. Podporované hodnoty: Error, Infoa Verbose.

nástroj dotnet-coverage

Příkaz instrumentu slouží k instrumentaci binárního souboru na disku.

Synopse

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>

Argumenty

• <input-file>

  Vstupní binární soubor.

Možnosti

• -s|--settings <settings>

  Nastaví cestu k nastavení pokrytí kódu XML.

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

  Určuje ID relace pokrytí kódu. Pokud není zadaný, nástroj vygeneruje náhodný identifikátor GUID.

• -o|--output <output>

  Nastaví cestu k binárnímu výstupnímu souboru. Pokud není k dispozici, provede se instrumentace na místě.

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

  Nastaví cestu k souboru protokolu. Když zadáte adresář (s oddělovačem cest na konci), vygeneruje se pro každý proces v analýze nový soubor protokolu.

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

  Nastaví úroveň protokolu. Podporované hodnoty: Error, Infoa Verbose.

Ukázkové scénáře

Shromažďování pokrytí kódu

Pomocí následujícího příkazu shromážděte data pokrytí kódu pro libovolnou aplikaci .NET (například konzolu nebo Blazor):

dotnet-coverage collect dotnet run

V případě aplikace, která vyžaduje ukončení signálu, můžete použít ctrl+C, což vám umožní shromažďovat data pokrytí kódu. Pro argument můžete zadat libovolný příkaz, který nakonec spustí aplikaci .NET. Může to být například skript PowerShellu.

Přednášky

Když spouštíte analýzu pokrytí kódu na serveru .NET, který jen čeká na zprávy a odesílá odpovědi, potřebujete způsob, jak zastavit server, abyste získali konečné výsledky pokrytí kódu. Můžete použít kombinaci kláves Ctrl+C místně, ale ne v Azure Pipelines. Pro tyto scénáře můžete použít relace. Při spuštění kolekce můžete zadat ID relace a pak pomocí shutdown příkazu zastavit shromažďování a server.

Předpokládejme například, že máte server v adresáři D:\serverexample\server a testovací projekt v adresáři D:\serverexample\tests . Testy komunikují se serverem přes síť. Kolekci pokrytí kódu pro server můžete spustit následujícím způsobem:

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

ID relace bylo zadáno jako serverdemo. Pak můžete testy spustit následujícím způsobem:

D:\serverexample\tests> dotnet test

Soubor pokrytí kódu pro relaci serverdemo lze vygenerovat s aktuálním pokrytím následujícím způsobem:

dotnet-coverage snapshot --output after_first_test.coverage serverdemo

Do souboru pokrytí je také možné přidat značku snímku pomocí možností značek následujícím způsobem:

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

Nakonec můžete relaci serverdemo a server zavřít následujícím způsobem:

dotnet-coverage shutdown serverdemo

Následuje příklad úplného výstupu na straně serveru:

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>

Režim serveru a klienta

Shromažďování pokrytí kódu lze provádět i v režimu klienta serveru. V tomto scénáři se spustí server kolekce pokrytí kódu a k serveru se může připojit více klientů. Pokrytí kódu se shromažďuje pro všechny klienty souhrnně.

Pomocí následujícího příkazu spusťte server pokrytí kódu:

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

V tomto příkladu bylo ID relace zadáno jako serverdemo pro server. Klient se může připojit k serveru pomocí tohoto ID relace pomocí následujícího příkazu:

dotnet-coverage connect serverdemo dotnet run

Nakonec můžete relaci serverdemo a server zavřít pomocí následujícího příkazu:

dotnet-coverage shutdown serverdemo

Proces serveru vytvoří sestavu pokrytí kolektivního kódu pro všechny klienty a ukončí se.

Následuje příklad úplného výstupu na straně serveru:

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>

Následuje příklad úplného výstupu na straně klienta:

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>

Můžete také spustit server i klienta v režimu na pozadí. Jiný proces se spustí na pozadí a vrátí řízení zpět uživateli.

Následuje příklad úplného výstupu v režimu klienta serveru na pozadí:

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>

Pokrytí statického kódu pro spravovaná sestavení

Nástroj dotnet-coverage lze použít ke shromažďování pokrytí kódu pro spravovaná sestavení pomocí statické instrumentace. K dispozici jsou tři různé metody, které můžete použít. Předpokládejme, že máme jednoduchou konzolovou aplikaci jazyka C#:

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

Použití příkazu Collect s možností zahrnout soubory nebo konfigurací

Pokud nechcete použít instrument příkaz, můžete soubory, které se mají instrumentovat, zadat následujícím způsobem --include-files :

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.

Můžete také určit soubory, které se mají instrumentovat pomocí konfigurace:

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

Použití instrumentace a shromažďování příkazů

V tomto případě musí být první binární soubor instrumentován následujícím způsobem:

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.

Pokrytí kódu pak můžete shromáždit následujícím způsobem:

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.

Použití nástroje a shromažďování příkazů v režimu serveru

V takovém případě můžete zcela oddělit kolekci pokrytí od spuštění aplikace. Nejprve instrumentujte binární soubor následujícím způsobem:

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.

V druhém kroku je potřeba spustit kolektor pokrytí následujícím způsobem:

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

Aplikaci pak můžete spustit následujícím způsobem:

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

Nakonec lze kolektor uzavřít takto:

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.

Nastavení

Soubor s nastavením můžete zadat při použití collect příkazu. Soubor nastavení lze použít k vyloučení některých modulů nebo metod z analýzy pokrytí kódu. Formát je stejný jako konfigurace kolektoru dat uvnitř souboru runsettings . Další informace naleznete v tématu Přizpůsobení analýzy pokrytí kódu. Tady je příklad:

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

Sloučení sestav pokrytí kódu

Data merged.coverage můžete sloučit a.coverage a b.coverage uložit takto:

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

Pokud například spustíte příkaz jako dotnet test --collect "Code Coverage", sestava pokrytí se uloží do složky s názvem náhodný identifikátor GUID. Tyto složky se obtížně hledají a slučují. Pomocí tohoto nástroje můžete sloučit všechny sestavy pokrytí kódu pro všechny projekty pomocí vzorů globbingu následujícím způsobem:

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

Předchozí příkaz sloučí všechny sestavy pokrytí z aktuálního adresáře a všech podadresářů a uloží výsledek do souboru cobertura. V Azure Pipelines můžete k publikování sloučené sestavy cobertura použít úlohu Publikovat výsledky pokrytí kódu.

Pomocí příkazu můžete merge převést sestavu pokrytí kódu do jiného formátu. Následující příkaz například převede sestavu pokrytí binárního kódu do formátu XML.

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

Viz také

• Přizpůsobení analýzy pokrytí kódu
• Publikování úlohy Výsledky pokrytí kódu