dotnet-coverage コード カバレッジ ユーティリティ

この記事の対象: ✔️ .NET Core 3.1 SDK 以降のバージョン

構文

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

説明

dotnet-coverage ツール:

• 実行中のプロセスのコード カバレッジ データのクロス プラットフォーム収集を有効にします。
• コード カバレッジ レポートのクロスプラットフォームでのマージを提供します。

[オプション]

• -h|--help

  コマンド ライン ヘルプを表示します。

• --version

  dotnet-coverage ユーティリティのバージョンを表示します。

インストール

dotnet-coverage NuGet パッケージの最新のリリース バージョンをインストールするには、次のように dotnet tool install コマンドを使用します。

dotnet tool install --global dotnet-coverage

コマンド

コマンド
dotnet-coverage merge
dotnet-coverage collect
dotnet-coverage connect
dotnet-coverage スナップショット
dotnet-coverage shutdown
dotnet-coverage instrument

dotnet-coverage merge

merge コマンドを使用して、複数のコード カバレッジ レポートを 1 つのレポートにマージします。 このコマンドは、すべてのプラットフォームで使用できます。 このコマンドでは、次のコード カバレッジ レポート形式がサポートされます。

• 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 コマンドは、2 つのモードで実行できます。

コマンド モード

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>

  コード カバレッジのセッション 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 モジュールのみがサポートされます。 ネイティブ モジュールはサポートされません。

Note

コマンドは、Windows (x86、x64、Arm64)、Linux (x64)、macOS (x64) で使用できるすべてのサブプロセスに動的インストルメンテーションを使用します。 connect コマンドを実行する前に、.NET モジュールは instrument コマンドを使用して (対応するセッション ID オプションを使用) を静的にインストルメント化する必要がある場合。

構文

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

引数

• <session>

  collect コマンドでホストされるサーバーのセッション ID。

• <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 スナップショット

既存のコード カバレッジ コレクションに対してカバレッジ ファイルを作成します。

構文

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>

  カバレッジ ファイルの生成対象となるコレクションのセッション ID。

[オプション]

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

  終了する収集のセッション ID。

[オプション]

• -t|--timeout

  サーバーとのプロセス間通信のタイムアウト (ミリ秒単位)。

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

  ログ ファイルのパスを設定します。 ディレクトリを指定すると (末尾にパス区切り文字を付けます)、分析対象のプロセスごとに新しいログ ファイルが生成されます。

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

  ログ レベルを設定します。 サポートされる値: Error、Info、Verbose。

dotnet-coverage instrument

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>

  コード カバレッジのセッション 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 では使用できません。 これらのシナリオでは、セッションを使用できます。 収集を開始するときにセッション ID を指定し、shutdown コマンドを使用して収集とサーバーを停止できます。

たとえば、サーバーが D:\serverexample\server ディレクトリ内にあり、テスト プロジェクトが D:\serverexample\tests ディレクトリ内にあるとします。 テストは、ネットワークを経由してサーバーと通信しています。 次のように入力して、サーバーのコード カバレッジ収集を開始することができます。

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

セッション ID として 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

この例では、サーバー用のセッション ID が serverdemo として指定されています。 クライアントは、次のコマンドを使用して、このセッション ID を使用してサーバーに接続できます。

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 ツールを使用すると、静的インストルメンテーションを使用してマネージド アセンブリのコード カバレッジを収集できます。 使用できる方法は 3 つあります。 デモを行うために、単純な C# コンソール アプリケーションがあるとします:

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

インクルード ファイル オプションまたは構成で collect コマンドを使用する

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.

Note

アプリケーションを接続して外部コレクターにデータを提供できるようにするには、このシナリオでセッション ID を使用する必要があります。

2 番目の手順では、次のようにカバレッジ コレクターを開始する必要があります。

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 コマンドを使用する場合、設定を含むファイルを指定できます。 settings ファイルを使用すると、一部のモジュールまたはメソッドをコード カバレッジ分析から除外できます。 形式は、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 で名前付けされたフォルダーに保存されます。 このようなフォルダーを見つけてマージするのは困難です。 このツールを使用すると、次のように glob パターンを使用して、すべてのプロジェクトのすべてのコード カバレッジ レポートをマージすることができます。

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

関連項目

• コード カバレッジ分析のカスタマイズ
• コード カバレッジ結果の公開タスク