The merge command is used to merge several code coverage reports into one. This command is available on all platforms. This command supports the following code coverage report formats:
Removes all input coverage reports that were merged.
-r, --recursive
.NET 7 SDK and earlier versions only Search for coverage reports in subdirectories.
-o|--output
Sets the code coverage report output file.
-f|--output-format
The output file format. Supported values: coverage, xml, and cobertura. Default is coverage (binary format that can be opened in Visual Studio).
-l|--log-file
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
-ll|--log-level
Sets the log level. Supported values: Error, Info, and Verbose.
-dco|--disable-console-output
Disables console output.
--nologo
Do not display Code Coverage banner.
dotnet-coverage collect
The collect command is used to collect code coverage data for any .NET process and its subprocesses. For example, you can collect code coverage data for a console application or a Blazor application. This command supports dynamic and static instrumentation. Static instrumentation is available on all platforms. You can specify files to be statically instrumented using include-files option. Dynamic instrumentation is available on Windows (x86, x64 and Arm64), Linux (x64), and macOS (x64). The command supports only .NET modules. Native modules are not supported.
Synopsis
The collect command can run in two modes.
Command Mode
The collect command will collect code coverage for the given process executed by the command argument.
The command for which to collect code coverage data.
The command line arguments for the command.
Options
-s|--settings
Sets the path to the XML code coverage settings.
-id|--session-id
Specifies the code coverage session ID. If not provided, the tool will generate a random GUID.
-sv|--server-mode
Starts the collector in server mode. Clients can connect to the server with the connect command.
-b|--background
Starts code coverage collection server in a new background process. Clients can connect to the server with the connect command.
-t|--timeout
Timeout (in milliseconds) for interprocess communication between clients and the server.
-if|--include-files
Specifies list of files to be statically instrumented.
-o|--output
Sets the code coverage report output file.
-f|--output-format
The output file format. Supported values: coverage, xml, and cobertura. Default is coverage (binary format that can be opened in Visual Studio).
-l|--log-file
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
-ll|--log-level
Sets the log level. Supported values: Error, Info, and Verbose.
-dco|--disable-console-output
Disables console output.
--nologo
Do not display Code Coverage banner.
dotnet-coverage connect
The connect command is used to connect with the existing server and collects code coverage data for any .NET process and its subprocesses. For example, you can collect code coverage data for a console application or a Blazor application. The command supports only .NET modules. Native modules are not supported.
Note
Command will use dynamic instrumentation for all subprocesses which is available on Windows (x86, x64 and Arm64), Linux (x64), and macOS (x64). If you need to statically instrument any .NET module use instrument command (with corresponding session ID option) before executing connect command.
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
-ll|--log-level
Sets the log level. Supported values: Error, Info, and Verbose.
-dco|--disable-console-output
Disables console output.
--nologo
Do not display Code Coverage banner.
Sample scenarios
Collecting code coverage
Collect code coverage data for any .NET application (such as console or Blazor) by using the following command:
dotnet-coverage collect dotnet run
In case of an application that requires a signal to terminate, you can use Ctrl+C, which will still let you collect code coverage data. For the argument, you can provide any command that will eventually start a .NET app. For example, it can be a PowerShell script.
Sessions
When you're running code coverage analysis on a .NET server that just waits for messages and sends responses, you need a way to stop the server to get final code coverage results. You can use Ctrl+C locally, but not in Azure Pipelines. For these scenarios, you can use sessions. You can specify a session ID when starting collection, and then use the shutdown command to stop collection and the server.
For example, assume you have a server in the D:\serverexample\server directory and a test project in the D:\serverexample\tests directory. Tests are communicating with the server through the network. You can start code coverage collection for the server as follows:
Finally, session serverdemo and the server can be closed as follows:
dotnet-coverage shutdown serverdemo
Following is an example of full output on the server side:
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>
Server and client mode
Code coverage collection can be done in server-client mode as well. In this scenario, a code coverage collection server starts, and multiple clients can connect with the server. Code coverage is collected for all the clients collectively.
Start the code coverage server using the following command:
In this example, the session ID was specified as serverdemo for the server. A client can connect to the server using this session ID using the following command:
dotnet-coverage connect serverdemo dotnet run
Finally, you can close the session serverdemo and the server using the following command:
dotnet-coverage shutdown serverdemo
The server process creates a collective code coverage report for all clients and exits.
Following is an example of full output on the server side:
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>
Following is an example of full output on the client side:
The dotnet-coverage tool can be used to collect code coverage for managed assemblies using static instrumentation. There are three different methods available that you can use. To demonstrate, let's assume we have a simple C# console application:
D:\examples\ConsoleApp> dotnet run
Hello, World!
Use collect command with include files option or configuration
If you don't want to use the instrument command, then the files to be instrumented can be specified using --include-files option as follows:
You can specify a file with settings when you use the collect command. The settings file can be used to exclude some modules or methods from code coverage analysis. The format is the same as the data collector configuration inside a runsettings file. For more information, see Customize code coverage analysis. Here's an example:
C:\Users\User\Documents\Visual Studio 2012\Projects\ProjectX\bin\Debug\\mybuildshare\builds\ProjectX.*\.dll$.*\.exe$.*CPPUnitTestFramework.*C:\temp^Fabrikam\.UnitTest\..*^std::.*^ATL::.*.*::__GetTestMethodInfo.*^Microsoft::VisualStudio::CppCodeCoverageFramework::.*^Microsoft::VisualStudio::CppUnitTestFramework::.*^System\.Diagnostics\.DebuggerHiddenAttribute$^System\.Diagnostics\.DebuggerNonUserCodeAttribute$^System\.CodeDom\.Compiler\.GeneratedCodeAttribute$^System\.Diagnostics\.CodeAnalysis\.ExcludeFromCodeCoverageAttribute$.*\\atlmfc\\.*.*\\vctools\\.*.*\\public\\sdk\\.*.*\\microsoft sdks\\.*.*\\vc\\include\\.*.*microsoft.*^B77A5C561934E089$^B03F5F7F11D50A3A$^31BF3856AD364E35$^89845DCD8080CC91$^71E9BCE111E9429C$^8F50407C4E9E73B6$^E361AF139669C375$TrueTrue
Merge code coverage reports
You can merge a.coverage and b.coverage and store the data in merged.coverage as follows:
For example, if you run a command like dotnet test --collect "Code Coverage", the coverage report is stored into a folder that is named a random GUID. Such folders are hard to find and merge. Using this tool, you can merge all code coverage reports for all your projects using globbing patterns as follows:
The preceding command merges all coverage reports from the current directory and all subdirectories and stores the result into a cobertura file. In Azure Pipelines, you can use Publish Code Coverage Results task to publish a merged cobertura report.
You can use the merge command to convert a code coverage report to another format. For example, the following command converts a binary code coverage report into XML format.
dotnet-coverage merge -o output.xml -f xml input.coverage
Telemetry
Starting with version 18.10.0, the dotnet-coverage tool collects telemetry data to help Microsoft improve the code coverage tools. The data records which commands you run and which options you set when you run the tool. You can disable telemetry at any time. For more information about the data that's collected and how to opt out, see Microsoft.CodeCoverage.Console telemetry.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
