Compartir vía

Utilidad de cobertura de código dotnet-coverage

  • Artículo

Este artículo se aplica a: ✔️ SDK de .NET Core 3.1 y versiones posteriores

Sinopsis

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

Descripción

La herramienta dotnet-coverage:

  • Habilita la colección multiplataforma de datos de cobertura de código de un proceso en ejecución.
  • Proporciona combinación multiplataforma de informes de cobertura de código.

Opciones

  • -h|--help

    Muestra la ayuda de la línea de comandos.

  • --version

    Muestra la versión de la utilidad dotnet-coverage.

Instalar

Para instalar la versión de lanzamiento más reciente del paquete NuGet de dotnet-coverage, use el comando dotnet tool install:

dotnet tool install --global dotnet-coverage

Comandos

Get-Help
dotnet-coverage merge
dotnet-coverage collect
dotnet-coverage connect
dotnet-coverage snapshot
dotnet-coverage shutdown
dotnet-coverage instrument

dotnet-coverage merge

El comando merge se usa para combinar varios informes de cobertura de código en uno. Este comando está disponible en todas las plataformas. Este comando admite los siguientes formatos de informe de cobertura de código:

  • coverage
  • cobertura
  • xml

Sinopsis

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>

Argumentos

  • <files>

    Informes de cobertura de código de entrada.

Opciones

  • --remove-input-files

    Quita todos los informes de cobertura de entrada que se combinaron.

  • -r, --recursive

    El SDK de .NET 7 y solo versiones anteriores. Busque informes de cobertura en subdirectorios.

  • -o|--output <output>

    Establece el archivo de salida del informe de cobertura de código.

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

    Formato del archivo de salida. Valores admitidos: coverage, xml y cobertura. El valor predeterminado es coverage (formato binario que se puede abrir en Visual Studio).

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

    Establece la ruta de archivo de registro. Cuando se proporciona un directorio (con separador de ruta de acceso al final), se genera un nuevo archivo de registro para cada proceso que se analiza.

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

    Establece el nivel de registro. Valores admitidos: Error, Info y Verbose.

dotnet-coverage collect

El comando collect se usa para recopilar datos de cobertura de código para cualquier proceso de .NET y sus subprocesos. Por ejemplo, puede recopilar datos de cobertura de código para una aplicación de consola o una aplicación Blazor. Este comando admite instrumentación dinámica y estática. La instrumentación estática está disponible en todas las plataformas. Puede especificar los archivos que se van a instrumentar estáticamente mediante la opción include-files. La instrumentación dinámica está disponible en Windows (x86, x64 y Arm64), Linux (x64) y macOS (x64). El comando solo admite módulos .NET. No se admiten módulos nativos.

Sinopsis

El comando collect se puede ejecutar en dos modos.

Modo comando

El comando collect recolectará la cobertura de código para el proceso especificado que el argumento command esté ejecutando.

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>

Modo de servidor

El comando collect hospeda un servidor para la recolección de información de cobertura de código. Los clientes pueden conectarse al servidor mediante el comando 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]

Argumentos

  • <command>

    Comando para el que se recopilan los datos de cobertura de código.

  • <args>

    Argumentos de la línea de comandos para el comando

Opciones

  • -s|--settings <settings>

    Establece la ruta de acceso a la configuración de cobertura de código XML.

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

    Especifica el identificador de sesión de cobertura de código. Si no se proporciona, la herramienta generará un GUID aleatorio.

  • -sv|--server-mode

    Permite iniciar el recolector en modo servidor. Los clientes pueden conectarse al servidor con el comando connect.

  • -b|--background

    Permite iniciar el servidor de recolección de información de cobertura de código en un nuevo proceso en segundo plano. Los clientes pueden conectarse al servidor con el comando connect.

  • -t|--timeout

    Tiempo de espera (en milisegundos) para la comunicación entre procesos que establecen los clientes y el servidor

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

    Especifica la lista de archivos que se van a instrumentar estáticamente.

  • -o|--output <output>

    Establece el archivo de salida del informe de cobertura de código.

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

    Formato del archivo de salida. Valores admitidos: coverage, xml y cobertura. El valor predeterminado es coverage (formato binario que se puede abrir en Visual Studio).

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

    Establece la ruta de archivo de registro. Cuando se proporciona un directorio (con separador de ruta de acceso al final), se genera un nuevo archivo de registro para cada proceso que se analiza.

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

    Establece el nivel de registro. Valores admitidos: Error, Info y Verbose.

dotnet-coverage connect

El comando connect se usa para conectarse con el servidor existente y recolecta datos de cobertura de código para cualquier proceso de .NET y sus subprocesos. Por ejemplo, puede recopilar datos de cobertura de código para una aplicación de consola o una aplicación Blazor. El comando solo admite módulos .NET. No se admiten módulos nativos.

Nota

El comando usará la instrumentación dinámica para todos los subprocesos que están disponibles en Windows (x86, x64 y Arm64), Linux (x64) y macOS (x64). Si necesita instrumentar estáticamente cualquier módulo de .NET use el comandoinstrument (con la opción id. de sesión correspondiente) antes de ejecutar el comando connect.

Sinopsis

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

Argumentos

  • <session>

    Id. de sesión del servidor que el comando collect hospeda.

  • <command>

    Comando para el que se recopilan los datos de cobertura de código.

  • <args>

    Argumentos de la línea de comandos para el comando

Opciones

  • -b|--background

    Permite iniciar el cliente en un nuevo proceso en segundo plano.

  • -t|--timeout

    Tiempo de espera (en milisegundos) para la comunicación entre procesos que establecen el cliente y el servidor* -l|--log-file <log-file>

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

    Establece la ruta de archivo de registro. Cuando se proporciona un directorio (con separador de ruta de acceso al final), se genera un nuevo archivo de registro para cada proceso que se analiza.

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

    Establece el nivel de registro. Valores admitidos: Error, Info y Verbose.

dotnet-coverage snapshot

Permite crear un archivo de cobertura para la recolección de información de cobertura de código actual.

Sinopsis

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>

Argumentos

  • <session>

    Id. de sesión de la recolección para la que se generará un archivo de cobertura.

Opciones

  • -r|--reset <reset>

    Permite borrar la información de cobertura actual después de crear un archivo de cobertura.

  • -o|--output <output>

    Establece el archivo de salida del informe de cobertura de código. Si no se proporciona, se genera automáticamente con una marca de tiempo.

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

    Crea un nombre de etiqueta de instantánea en el archivo de cobertura con información de cobertura actual. El nombre y el identificador de etiqueta se incluyen mutuamente.

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

    Crea un identificador de etiqueta de instantánea en el archivo de cobertura con información de cobertura actual. El nombre y el identificador de etiqueta se incluyen mutuamente.

  • -t|--timeout

    Tiempo de espera (en milisegundos) para la comunicación entre procesos que establecen el cliente y el servidor

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

    Establece la ruta de archivo de registro. Cuando se proporciona un directorio (con separador de ruta de acceso al final), se genera un nuevo archivo de registro para cada proceso que se analiza.

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

    Establece el nivel de registro. Valores admitidos: Error, Info y Verbose.

dotnet-coverage shutdown

Cierra la recolección de información de cobertura de código existente.

Sinopsis

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

Argumentos

  • <session>

    Identificador de sesión de la colección que se va a cerrar.

Opciones

  • -t|--timeout

    Tiempo de espera (en milisegundos) para la comunicación entre procesos que se establece con el servidor

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

    Establece la ruta de archivo de registro. Cuando se proporciona un directorio (con separador de ruta de acceso al final), se genera un nuevo archivo de registro para cada proceso que se analiza.

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

    Establece el nivel de registro. Valores admitidos: Error, Info y Verbose.

dotnet-coverage instrument

El comando instrument se usa para instrumentar binario en disco.

Sinopsis

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>

Argumentos

  • <input-file>

    El archivo binario de entrada.

Opciones

  • -s|--settings <settings>

    Establece la ruta de acceso a la configuración de cobertura de código XML.

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

    Especifica el identificador de sesión de cobertura de código. Si no se proporciona, la herramienta generará un GUID aleatorio.

  • -o|--output <output>

    Establece la ruta de acceso al archivo de salida binario. Si no se proporciona, la instrumentación se realizará en contexto.

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

    Establece la ruta de archivo de registro. Cuando se proporciona un directorio (con separador de ruta de acceso al final), se genera un nuevo archivo de registro para cada proceso que se analiza.

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

    Establece el nivel de registro. Valores admitidos: Error, Info y Verbose.

Escenarios de ejemplo

Recopilación de cobertura de código

Recopile datos de cobertura de código para cualquier aplicación .NET (como la consola o Blazor) mediante el comando siguiente:

dotnet-coverage collect dotnet run

En el caso de una aplicación que requiera una señal para finalizar, puede usar Ctrl+C, lo que todavía le permitirá recopilar datos de cobertura de código. Para el argumento, puede proporcionar cualquier comando que finalmente inicie una aplicación .NET. Por ejemplo, puede ser un script de PowerShell.

Sesiones

Cuando se ejecuta el análisis de cobertura de código en un servidor .NET que solo espera mensajes y envía respuestas, necesita una manera de detener dicho servidor para obtener los resultados finales de la cobertura de código. Puede usar Ctrl+C de forma local, pero no en Azure Pipelines. Para estos escenarios, puede usar sesiones. Puede especificar un identificador de sesión al iniciar la recopilación y, a continuación, usar el comando shutdown para detener la recopilación y el servidor.

Por ejemplo, suponga que tiene un servidor en el directorio D:\serverexample\server y un proyecto de prueba en el directorio D:\serverexample\tests. Las pruebas se comunican con el servidor a través de la red. Puede iniciar la recopilación de cobertura de código para el servidor de la siguiente manera:

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

El identificador de sesión se especificó como serverdemo. A continuación, puede ejecutar pruebas de la siguiente manera:

D:\serverexample\tests> dotnet test

Se puede generar un archivo de cobertura de código para la sesión serverdemo con la cobertura actual de la siguiente manera:

dotnet-coverage snapshot --output after_first_test.coverage serverdemo

Además, se puede agregar una etiqueta de instantánea al archivo de cobertura mediante las opciones de etiqueta de la siguiente manera:

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

Por último, la sesión serverdemo y el servidor se pueden cerrar de la manera siguiente:

dotnet-coverage shutdown serverdemo

A continuación, se muestra un ejemplo de salida completa en el lado servidor:

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>

Modo servidor y cliente

La recolección de cobertura de código también se puede llevar a cabo en el modo servidor-cliente. En este escenario, se inicia un servidor de recolección de cobertura de código, y varios clientes pueden conectar con el servidor. La cobertura de código se recolecta para todos los clientes en conjunto.

Inicie el servidor de cobertura de código con el comando siguiente:

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

En este ejemplo, el id. de sesión se ha especificado como serverdemo para el servidor. Un cliente puede conectarse al servidor mediante este id. de sesión con el comando siguiente:

dotnet-coverage connect serverdemo dotnet run

Por último, puede cerrar la sesión serverdemo y el servidor mediante el comando siguiente:

dotnet-coverage shutdown serverdemo

El proceso de servidor crea un informe de cobertura de código colectivo para todos los clientes y todas las salidas.

A continuación, se muestra un ejemplo de salida completa en el lado servidor:

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>

Este es un ejemplo de salida completa en el lado servidor:

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>

También puede iniciar el servidor y el cliente en modo segundo plano. Otro proceso se inicia en segundo plano y devuelve el control al usuario.

Este es un ejemplo de salida completa en el modo cliente de servidor en segundo plano:

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>

Cobertura de código estático para ensamblados administrados

La herramienta dotnet-coverage se puede usar para recopilar cobertura de código para ensamblados administrados mediante instrumentación estática. Hay tres métodos diferentes disponibles que puede usar. Para demostrarlo, supongamos que tenemos una sencilla aplicación de consola de C#:

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

Usar el comando collect con la opción o la configuración de archivos de inclusión

Si no desea usar el comando instrument, los archivos que se van a instrumentar se pueden especificar mediante la opción --include-files de la siguiente manera:

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.

También puede especificar los archivos que se van a instrumentar mediante la configuración de la siguiente manera:

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

Uso de instrumentación y recopilación de comandos

En este caso, el primer binario debe instrumentarse de la siguiente manera:

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.

Después, puede recopilar la cobertura de código de la siguiente manera:

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.

Usar el instrumento y recopilar comandos en modo de servidor

En este caso, puede separar completamente la recopilación de cobertura de la ejecución de la aplicación. En primer lugar, instrumente el binario de la siguiente manera:

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.

Nota

El identificador de sesión debe usarse en este escenario para asegurarse de que la aplicación puede conectarse y proporcionar datos al recopilador externo.

En el segundo paso, debe iniciar el recopilador de cobertura de la siguiente manera:

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

Después, la aplicación se puede iniciar de la siguiente forma:

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

Para terminar, el recopilador se puede cerrar de la siguiente manera:

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.

Configuración

Puede especificar un archivo con la configuración cuando use el comando collect. El archivo de configuración se puede usar para excluir algunos módulos o métodos del análisis de cobertura de código. El formato es el mismo que la configuración del recopilador de datos dentro de un archivo runsettings. Para obtener más información, vea Personalizar el análisis de cobertura de código. Este es un ejemplo:

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

Combinación de informes de cobertura de código

Puede combinar a.coverage y b.coverage y almacenar los datos en merged.coverage como se muestra a continuación:

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

Por ejemplo, si ejecuta un comando como dotnet test --collect "Code Coverage", el informe de cobertura se almacena en una carpeta que lleva por nombre un GUID aleatorio. Estas carpetas son difíciles de encontrar y combinar. Con esta herramienta, puede fusionar todos los informes de cobertura de código de todos sus proyectos utilizando patrones expansibles como se indica a continuación:

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

El comando anterior combina todos los informes de cobertura del directorio actual y todos los subdirectorios y almacena el resultado en un archivo de cobertura. En Azure Pipelines, puede usar la tarea Publicar resultados de cobertura de código para publicar un informe de cobertura combinado.

Puede usar el comando merge para convertir un informe de cobertura de código a otro formato. Por ejemplo, el comando siguiente convierte un informe de cobertura de código binario al formato XML.

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

Consulte también