diff --git a/cSpell.json b/cSpell.json index b0e36610b5925..d702e0a9dde19 100644 --- a/cSpell.json +++ b/cSpell.json @@ -51,6 +51,7 @@ "assistive", "Asynchronicity", "Asynchrony", + "atlmfc", "attributelist", "attributename", "Authenticode", @@ -109,6 +110,7 @@ "cnabs", "CNCF", "coalescer", + "cobertura", "coclass", "Coclasses", "codebases", @@ -949,6 +951,7 @@ "vbcr", "vbcrlf", "vbruntime", + "vctools", "vectorized", "verifiably", "versionnumber", diff --git a/docs/core/additional-tools/dotnet-coverage.md b/docs/core/additional-tools/dotnet-coverage.md index af8bb9d603d34..ac409ad97e19f 100644 --- a/docs/core/additional-tools/dotnet-coverage.md +++ b/docs/core/additional-tools/dotnet-coverage.md @@ -8,14 +8,6 @@ ms.topic: reference **This article applies to:** ✔️ .NET Core 3.1 SDK and later versions -## Install - -To install the latest release version of the `dotnet-coverage` [NuGet package](https://www.nuget.org/packages/dotnet-coverage), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: - -```dotnetcli -dotnet tool install --global dotnet-coverage -``` - ## Synopsis ```console @@ -31,24 +23,82 @@ The `dotnet-coverage` tool: ## Options -- **`-h|--help`** +* **`-h|--help`** Shows command-line help. -- **`--version`** +* **`--version`** Displays the version of the dotnet-coverage utility. +## Install + +To install the latest release version of the `dotnet-coverage` [NuGet package](https://www.nuget.org/packages/dotnet-coverage), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: + +```dotnetcli +dotnet tool install --global dotnet-coverage +``` + ## Commands | Command | |-----------------------------------------------------------| +| [dotnet-coverage merge](#dotnet-coverage-merge) | | [dotnet-coverage collect](#dotnet-coverage-collect) | | [dotnet-coverage connect](#dotnet-coverage-connect) | -| [dotnet-coverage merge](#dotnet-coverage-merge) | | [dotnet-coverage snapshot](#dotnet-coverage-snapshot) | | [dotnet-coverage shutdown](#dotnet-coverage-shutdown) | +## dotnet-coverage merge + +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: + +* `coverage` +* `cobertura` +* `xml` + +### Synopsis + +```console +dotnet-coverage merge + [--remove-input-files] [-r|--recursive] + [-o|--output ] [-f|--output-format ] + [-l|--log-file ] [-ll|--log-level ] [-?|-h|--help] + +``` + +### Arguments + +* **``** + + The input code coverage reports. + +### Options + +* **`--remove-input-files`** + + Removes all input coverage reports that were merged. + +* **`-r, --recursive`** + + 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`. + ## 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 is available on Windows (x86 and x64), Linux (x64), and macOS (x64). The command supports only .NET modules. Native modules are not supported. @@ -62,10 +112,11 @@ The `collect` command can run in two modes. The `collect` command will collect code coverage for the given process executed by the `command` argument. ```console -dotnet-coverage collect [-?|-h|--help] [-l|--log-file ] [-ll|--log-level ] - [-o|--output ] [-f|--output-format ] +dotnet-coverage collect [-s|--settings ] [-id|--session-id ] - + [-o|--output ] [-f|--output-format ] + [-l|--log-file ] [-ll|--log-level ] [-?|-h|--help] + ``` #### Server Mode @@ -73,128 +124,104 @@ dotnet-coverage collect [-?|-h|--help] [-l|--log-file ] [-ll|--log-lev The `collect` command hosts a server for code coverage collection. Clients can connect to the server via `connect` command. ```console -dotnet-coverage collect [-?|-h|--help] [-l|--log-file ] [-ll|--log-level ] - [-o|--output ] [-f|--output-format ] +dotnet-coverage collect [-s|--settings ] [-id|--session-id ] - [-sv|--server-mode] + [-sv|--server-mode] [-b|--background] [-t|--timeout] + [-o|--output ] [-f|--output-format ] + [-l|--log-file ] [-ll|--log-level ] [-?|-h|--help] ``` ### Arguments -- **``** +* **``** The command for which to collect code coverage data. -### Options +* **``** -- **`-l|--log-file `** + The command line arguments for the 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`. - -- **`-o|--output `** - - Sets the code coverage report output file. +### Options -- **`-f|--output-format `** +* **`-s|--settings `** - The output file format. Supported values: `coverage`, `xml`, and `cobertura`. Default is `coverage` (binary format that can be opened in Visual Studio). + Sets the path to the XML code coverage settings. -- **`-id|--session-id `** +* **`-id|--session-id `** Specifies the code coverage session ID. If not provided, the tool will generate a random GUID. -- **`-s|--settings `** +* **`-sv|--server-mode`** - Sets the path to the XML code coverage settings. + Starts the collector in server mode. Clients can connect to the server with the `connect` command. -- **`-sv|--server-mode`** +* **`-b|--background`** - Starts the collector in server mode. Clients can connect to the server with `connect` command. + Starts code coverage collection server in a new background process. Clients can connect to the server with the `connect` command. -## dotnet-coverage connect +* **`-t|--timeout`** -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. This command is available on Windows (x86 and x64), Linux (x64), and macOS (x64). The command supports only .NET modules. Native modules are not supported. + Timeout (in milliseconds) for interprocess communication between clients and the server. -### Synopsis +* **`-o|--output `** -```console -dotnet-coverage connect [-?|-h|--help] [-l|--log-file ] [-ll|--log-level ] - - -``` - -### Arguments - -- **``** - - The session ID of the server hosted by the `collect` command. - -- **``** + Sets the code coverage report output file. - The command for which to collect code coverage data. +* **`-f|--output-format `** -### Options + 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 `** +* **`-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 `** +* **`-ll|--log-level `** Sets the log level. Supported values: `Error`, `Info`, and `Verbose`. -## dotnet-coverage merge - -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: +## dotnet-coverage connect -- `coverage` -- `cobertura` -- `xml` +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. This command is available on Windows (x86 and x64), Linux (x64), and macOS (x64). The command supports only .NET modules. Native modules are not supported. ### Synopsis ```console -dotnet-coverage merge [-?|-h|--help] [-l|--log-file ] [-ll|--log-level ] - [-o|--output ] [-f|--output-format ] - [-r|--recursive] [--remove-input-files] - +dotnet-coverage connect + [-b|--background] [-t|--timeout] + [-l|--log-file ] [-ll|--log-level ] [-?|-h|--help] + + ``` ### Arguments -- **``** - - The input code coverage reports. +* **``** -### Options + The session ID of the server hosted by the `collect` command. -- **`-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. + The command for which to collect code coverage data. -- **`-ll|--log-level `** +* **``** - Sets the log level. Supported values: `Error`, `Info`, and `Verbose`. + The command line arguments for the command. -- **`-o|--output `** +### Options - Sets the code coverage report output file. +* **`-b|--background`** -- **`-f|--output-format `** + Starts the client in a new background process. - The output file format. Supported values: `coverage`, `xml`, and `cobertura`. Default is `coverage` (binary format that can be opened in Visual Studio). +* **`-t|--timeout`** -- **`-r, --recursive`** + Timeout (in milliseconds) for interprocess communication between the client and the server.* **`-l|--log-file `** - Search for coverage reports in subdirectories. + 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. -- **`--remove-input-files`** +* **`-ll|--log-level `** - Removes all input coverage reports that were merged. + Sets the log level. Supported values: `Error`, `Info`, and `Verbose`. ## dotnet-coverage snapshot @@ -203,33 +230,39 @@ Creates a coverage file for existing code coverage collection. ### Synopsis ```console -dotnet-coverage snapshot [-?|-h|--help] [-l|--log-file ] [-ll|--log-level ] - [-o|--output ] [-r|--reset] +dotnet-coverage snapshot + [-r|--reset] [-o|--output ] [-t|--timeout] + [-l|--log-file ] [-ll|--log-level ] [-?|-h|--help] + ``` ### Arguments -- **``** +* **``** The session ID of the collection for which a coverage file is to be generated. ### Options -- **`-l|--log-file `** +* **`-r|--reset `** - 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. + Clears existing coverage information after a coverage file is created. -- **`-ll|--log-level `** +* **`-o|--output `** - Sets the log level. Supported values: `Error`, `Info`, and `Verbose`. + Sets the code coverage report output file. If not provided, it's generated automatically with a timestamp. -- **`-o|--output `** +* **`-t|--timeout`** - Sets the code coverage report output file. If not provided, it's generated automatically with a timestamp. + Timeout (in milliseconds) for interprocess communication between the client and the server. -- **`-r|--reset `** +* **`-l|--log-file `** - Clears existing coverage information after a coverage file is created. + 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`. ## dotnet-coverage shutdown @@ -238,31 +271,40 @@ Closes existing code coverage collection. ### Synopsis ```console -dotnet-coverage shutdown [-?|-h|--help] [-l|--log-file ] [-ll|--log-level ] +dotnet-coverage shutdown + [-t|--timeout] + [-l|--log-file ] [-ll|--log-level ] [-?|-h|--help] + ``` ### Arguments -- **``** +* **``** The session ID of the collection to be closed. ### Options -- **`-l|--log-file `** +* **`-t|--timeout`** + + Timeout (in milliseconds) for interprocess communication with the server. + +* **`-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 `** +* **`-ll|--log-level `** Sets the log level. Supported values: `Error`, `Info`, and `Verbose`. +## Sample scenarios + ## Collecting code coverage Collect code coverage data for any .NET application (such as console or Blazor) by using the following command: ```console -dotnet-coverage collect "dotnet run" +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. @@ -307,11 +349,67 @@ 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: + +```condole +dotnet-coverage collect --session-id serverdemo --server-mode +``` + +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: + +```condole +dotnet-coverage connect serverdemo dotnet run +``` + +Finally, you can close the session `serverdemo` and the server using the following command: + +```console +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: + +```console +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: + +```console +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> +``` + +You can also start both server and client in background mode. Another process starts in the background and returns control back to the user. + +Following is an example of full output in background server client mode: + +```console +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> +``` + ### Settings 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](/visualstudio/test/customizing-code-coverage-analysis). Here's an example: -``` +```xml @@ -428,5 +526,5 @@ dotnet-coverage merge -o output.xml -f xml input.coverage ## See also -- [Customize code coverage analysis](/visualstudio/test/customizing-code-coverage-analysis) -- [Publish Code Coverage Results task](/azure/devops/pipelines/tasks/test/publish-code-coverage-results) +* [Customize code coverage analysis](/visualstudio/test/customizing-code-coverage-analysis) +* [Publish Code Coverage Results task](/azure/devops/pipelines/tasks/test/publish-code-coverage-results)