dotnet-coverage 程式碼涵蓋範圍公用程式

  • 發行項

本文適用於： ✔️ .NET Core 3.1 SDK 與更新版本

概要

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

描述

dotnet-coverage 工具：

  • 啟用執行中流程程式碼涵蓋範圍資料的跨平台集合。
  • 提供程式碼涵蓋範圍報告的跨平台合併。

選項。

  • -h|--help

    顯示命令列說明。

  • --version

    顯示 dotnet-coverage 公用程式的版本。

安裝

若要安裝最新版本的 dotnet-coverageNuGet 套件，請使用 dotnet tool install 命令：

dotnet tool install --global dotnet-coverage

命令

Command
dotnet-coverage merge
dotnet-coverage collect
dotnet-coverage connect
dotnet-coverage snapshot
dotnet-coverage shutdown
dotnet-coverage instrument

dotnet-coverage merge

merge 命令可用來將數個程式碼涵蓋範圍報告合併成一個。 此命令可在所有平台上使用。 此命令支援下列程式碼涵蓋範圍報告格式：

  • coverage
  • cobertura
  • xml

概要

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>

引數

  • <files>

    輸入程式碼涵蓋範圍報告。

選項。

  • --remove-input-files

    移除所有已合併的輸入涵蓋範圍報告。

  • -r, --recursive

    .NET 7 SDK 和更舊的版本僅會搜尋子目錄中的涵蓋範圍報表。

  • -o|--output <output>

    設定程式碼涵蓋範圍報告輸出檔案。

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

    輸出檔案格式。 支援的值：coverage、xml 和 cobertura。 預設值 (coverage 可在 Visual Studio 中開啟的二進位格式)。

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

    設定記錄檔路徑 您提供目錄時 (結尾有路徑分隔符號)，就會為每個分析中的流程產生新的記錄檔。

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

    設定記錄層級。 支援的值：Error、Info 和 Verbose。

dotnet-coverage collect

collect 命令是用來收集任何 .NET 流程及其子流程的程式碼涵蓋範圍資料。 例如，您可以收集主控台應用程式或 Blazor 應用程式的程式碼涵蓋範圍資料。 此命令支援動態和靜態檢測。 靜態檢測可在所有平台上使用。 您可以使用 include-files 選項指定要以靜態方式檢測的檔案。 動態檢測適用於 Windows (x86、x64 和 Arm64)、Linux (x64)，以及 macOS (x64)。 此命令僅支援 .NET 模組。 不支援原生模組。

概要

collect命令能夠以兩種模式執行。

命令模式

collect 命令會收集 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>

伺服器模式

collect 命令會裝載用於程式碼涵蓋範圍收集的伺服器。 用戶端可以透過 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]

引數

  • <command>

    收集程式碼涵蓋範圍資料的命令。

  • <args>

    命令的命令列引數。

選項。

  • -s|--settings <settings>

    設定 XML 程式碼涵蓋範圍設定的路徑。

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

    指定程式碼涵蓋範圍工作階段識別碼。 如果未提供，此工具將會產生隨機 GUID。

  • -sv|--server-mode

    在伺服器模式中啟動收集器。 用戶端可以使用 connect 命令連線到伺服器。

  • -b|--background

    在新的背景處理程序中啟動程式碼涵蓋範圍收集伺服器。 用戶端可以使用 connect 命令連線到伺服器。

  • -t|--timeout

    用戶端與伺服器之間的處理程序間通訊逾時 (毫秒數)。

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

    指定要以靜態方式檢測的檔案清單。

  • -o|--output <output>

    設定程式碼涵蓋範圍報告輸出檔案。

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

    輸出檔案格式。 支援的值：coverage、xml 和 cobertura。 預設值 (coverage 可在 Visual Studio 中開啟的二進位格式)。

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

    設定記錄檔路徑 您提供目錄時 (結尾有路徑分隔符號)，就會為每個分析中的流程產生新的記錄檔。

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

    設定記錄層級。 支援的值：Error、Info 和 Verbose。

dotnet-coverage connect

connect 命令可用來與現有的伺服器連線，並收集任何 .NET 流程及其子流程的程式碼涵蓋範圍資料。 例如，您可以收集主控台應用程式或 Blazor 應用程式的程式碼涵蓋範圍資料。 此命令僅支援 .NET 模組。 不支援原生模組。

注意

命令會針對 Windows (x86、x64 和 Arm64)、Linux (x64) 和 macOS (x64) 上提供的所有子流程使用動態檢測。 如果您需要以靜態方式檢測任何 .NET 模組，請先 (藉由對應的工作階段識別碼選項) 使用 instrument 命令，再執行 connect 命令。

概要

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

引數

  • <session>

    collect 命令裝載的伺服器所用的工作階段識別碼。

  • <command>

    收集程式碼涵蓋範圍資料的命令。

  • <args>

    命令的命令列引數。

選項。

  • -b|--background

    在新的背景流程中啟動用戶端。

  • -t|--timeout

    用戶端與伺服器之間的處理程序間通訊逾時 (毫秒數)。* -l|--log-file <log-file>

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

    設定記錄檔路徑 您提供目錄時 (結尾有路徑分隔符號)，就會為每個分析中的流程產生新的記錄檔。

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

    設定記錄層級。 支援的值：Error、Info 和 Verbose。

dotnet-coverage snapshot

建立現有程式碼涵蓋範圍收集的涵蓋範圍檔案。

概要

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>

引數

  • <session>

    要產生涵蓋範圍檔案的集合所用的工作階段識別碼。

選項。

  • -r|--reset <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>

    設定記錄層級。 支援的值：Error、Info 和 Verbose。

dotnet-coverage shutdown

關閉現有的程式碼涵蓋範圍收集。

概要

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

引數

  • <session>

    要關閉的集合所用的工作階段識別碼。

選項。

  • -t|--timeout

    與伺服器進行處理序間通訊的逾時 (毫秒數)。

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

    設定記錄檔路徑 您提供目錄時 (結尾有路徑分隔符號)，就會為每個分析中的流程產生新的記錄檔。

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

    設定記錄層級。 支援的值：Error、Info 和 Verbose。

dotnet-coverage instrument

檢測命令可用來檢測磁碟上的二進位檔案。

概要

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>

引數

  • <input-file>

    輸入二進位檔案。

選項。

  • -s|--settings <settings>

    設定 XML 程式碼涵蓋範圍設定的路徑。

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

    指定程式碼涵蓋範圍工作階段識別碼。 如果未提供，此工具將會產生隨機 GUID。

  • -o|--output <output>

    設定輸出檔案二進位檔案的路徑。 如果未提供，則會就地執行檢測。

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

    設定記錄檔路徑 您提供目錄時 (結尾有路徑分隔符號)，就會為每個分析中的流程產生新的記錄檔。

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

    設定記錄層級。 支援的值：Error、Info 和 Verbose。

範例案例

收集程式碼涵蓋範圍

使用下列命令收集任何 .NET 應用程式的程式碼涵蓋範圍資料 (例如主控台或 Blazor)：

dotnet-coverage collect dotnet run

如果需要終止訊號的應用程式，您可以使用 Ctrl+C，這仍可讓您收集程式碼涵蓋範圍資料。 對於引數，您可以提供最終會啟動 .NET 應用程式的任何命令。 例如，這可以是 PowerShell 指令碼。

工作階段

您在只等候訊息並傳送回應的 .NET 伺服器上執行程式碼涵蓋範圍分析時，您需要一種方式來停止伺服器，以取得最終的程式碼涵蓋範圍結果。 您可以在本機使用 Ctrl+C，但無法在 Azure Pipelines 中使用。 在這些案例中，您可以使用工作階段。 您可以在啟動集合時指定工作階段識別碼，然後使用 shutdown 命令來停止收集和伺服器。

例如，假設您在 D:\serverexample\server 目錄中有伺服器，並且在 D:\serverexample\tests 目錄中有測試專案。 測試會透過網路與伺服器進行通訊。 您可以啟動伺服器的程式碼涵蓋範圍收集，如下所示：

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

工作階段識別碼已指定為 serverdemo。 然後，您可以執行測試，如下所示：

D:\serverexample\tests> dotnet test

工作階段 serverdemo 的程式碼涵蓋範圍檔案可以使用目前的涵蓋範圍產生，如下所示：

dotnet-coverage snapshot --output after_first_test.coverage serverdemo

此外，您也可以使用標記選項將快照集標記新增至涵蓋範圍檔案，如下所示：

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

最後，工作階段 serverdemo 和伺服器可以關閉，如下所示：

dotnet-coverage shutdown serverdemo

下列是伺服器端的完整輸出範例：

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>

伺服器和用戶端模式

程式碼涵蓋範圍收集也能夠以伺服器用戶端模式完成。 在此案例中，程式碼涵蓋範圍收集伺服器會啟動，而且多個用戶端可以與伺服器連線。 所有用戶端都會收集程式碼涵蓋範圍。

使用下列命令啟動程式碼涵蓋範圍伺服器：

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

在此範例中，工作階段識別碼已對於伺服器指定為 serverdemo。 用戶端可以使用下列命令，使用此工作階段識別碼連線到伺服器：

dotnet-coverage connect serverdemo dotnet run

最後，您可以使用下列命令來關閉工作階段 serverdemo 和伺服器：

dotnet-coverage shutdown serverdemo

伺服器流程會為所有用戶端和結束建立集體程式碼涵蓋範圍報告。

下列是伺服器端的完整輸出範例：

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>

下列是用戶端的完整輸出範例：

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>

您也可以在背景模式中啟動伺服器和用戶端。 另一個流程會在背景啟動，並將控制權傳回給使用者。

下列是背景伺服器用戶端模式中完整輸出的範例：

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>

受控組件的靜態程式碼涵蓋範圍

dotnet-coverage 工具可用來使用靜態檢測收集受控組件的程式碼涵蓋範圍。 您可以使用三種不同的方法。 為了示範，假設我們有簡單的 C# 主控台應用程式：

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

搭配包含檔案選項或設定使用收集命令

如果您不想使用 instrument 命令，可以使用 --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.

您也可以使用設定來指定要檢測的檔案，如下所示：

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

使用檢測和收集命令

在此情況下，必須先檢測第一個二進位檔案，如下所示：

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.

然後，您可以收集程式碼涵蓋範圍，如下所示：

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.

在伺服器模式中使用檢測並收集命令

在此情況下，您可以將涵蓋範圍收集與執行應用程式完全分開。 首先，檢測您的二進位檔案，如下所示：

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.

注意

此案例需要使用工作階段識別碼，以確保應用程式可以連線並提供資料給外部收集器。

在第二個步驟中，您必須啟動涵蓋範圍收集器，如下所示：

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

然後應用程式可以啟動，如下所示：

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

最後，收集器可以關閉，如下所示：

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.

設定

您使用 collect 命令時，可以指定具有設定的檔案。 設定檔可用來從程式碼涵蓋範圍分析中排除某些模組或方法。 格式與 runsettings 檔案內的資料收集器設定相同。 如需詳細資訊，請參閱自訂程式碼涵蓋範圍分析。 以下是範例：

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

合併程式碼涵蓋範圍報告

您可以合併 a.coverage 和 b.coverage 並且在 merged.coverage 中儲存資料，如下所示：

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

例如，如果您執行類似 dotnet test --collect "Code Coverage" 的命令，涵蓋範圍報告會儲存到名為隨機 GUID 的資料夾。 這類資料夾很難找到並合併。 使用此工具，您就可以使用萬用字元模式來合併所有專案的所有程式碼涵蓋範圍報告，如下所示：

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

上述命令會將目前目錄和所有子目錄中的所有涵蓋範圍報告合併，並將結果儲存到 cobertura 檔案中。 在 Azure Pipelines 中，您可以使用發佈程式碼涵蓋範圍結果工作發佈合併的 Cobertura 報告。

您可以使用 merge 命令，將程式碼涵蓋範圍報告轉換成另一種格式。 例如，下列命令會將二進位程式碼涵蓋範圍報告轉換成 XML 格式。

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

另請參閱