Herramienta global Microsoft.DotNet.ApiCompat.Tool

La herramienta Microsoft.DotNet.ApiCompat.Tool le permite realizar comprobaciones de compatibilidad de API fuera de MSBuild. La herramienta tiene dos modos:

• Compare un paquete con un paquete de línea base.
• Compare un ensamblado con un ensamblado de línea base.

Instalación

Para instalar la herramienta, ejecute el siguiente comando.

dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool

Para obtener más información acerca de cómo instalar herramientas globales, consulte Instalación de una herramienta global.

Uso

Microsoft.DotNet.ApiCompat.Tool [command] [options]

o bien

apicompat [command] [options]

Comandos

• package | --package <PACKAGE_FILE>

  Validar la compatibilidad de los recursos de paquete. Si no se especifica, la herramienta compara los ensamblados. <PACKAGE_FILE> especifica la ruta de acceso al archivo de paquete.

Opciones

Algunas opciones se aplican a la validación del ensamblado y del paquete. Otros se aplican solo a ensamblados o paquetes.

Opciones generales

• --version

  Muestra información de versión.

• --generate-suppression-file

  Generar un archivo de supresión de compatibilidad.

• --preserve-unnecessary-suppressions

  Conserva las supresiones innecesarias al volver a generar el archivo de supresión.

  Cuando se vuelve a generar un archivo de supresión existente, se lee su contenido, se deserializa en un conjunto de supresiones y a continuación se almacena en una lista. Es posible que algunas de las supresiones ya no sean necesarias si se ha corregido la incompatibilidad. Cuando las supresiones se serializan de nuevo en el disco, puede optar por mantener todas las expresiones existentes (deserializadas) especificando esta opción.

• --permit-unnecessary-suppressions

  Permite supresiones innecesarias en el archivo de supresión.

• --suppression-file <FILE>

  Especifica la ruta de acceso a uno o varios archivos de supresión de los que se va a leer.

• --suppression-output-file <FILE>

  Especifica la ruta de acceso a un archivo de supresión en el que se va a escribir cuando se especifica --generate-suppression-file. Si no se especifica, se usa la primera ruta de acceso --suppression-file.

• --noWarn <NOWARN_STRING>

  Especifica los identificadores de diagnóstico que se van a suprimir. Por ejemplo, "$(NoWarn);PKV0001".

• --respect-internals

  Comprueba las API internal y public.

• --roslyn-assemblies-path <FILE>

  Especifica la ruta de acceso al directorio que contiene los ensamblados Microsoft.CodeAnalysis que desea usar. Solo tiene que establecer esta propiedad si desea probar con un compilador más reciente que lo que hay en el SDK.

• -v, --verbosity [high|low|normal]

  Controla el nivel de registro detallado. Los valores permitidos son high, normal, y low. El valor predeterminado es normal.

• --enable-rule-cannot-change-parameter-name

  Habilita la regla que comprueba si los nombres de parámetro han cambiado en métodos públicos.

• --enable-rule-attributes-must-match

  Habilita la regla que comprueba si coinciden los atributos.

• --exclude-attributes-file <FILE>

  Especifica la ruta de acceso a uno o varios archivos que contienen atributos que se van a excluir en formato DocId.

Opciones específicas del ensamblado

Estas opciones solo son aplicables cuando se comparan los ensamblados.

• -l, --left, --left-assembly <PATH>

  Especifica la ruta de acceso a uno o varios ensamblados que sirven como lado izquierdo para comparar. Esta opción es necesaria al comparar ensamblados.

• -r, --right, --right-assembly <PATH>

  Especifica la ruta de acceso a uno o varios ensamblados que actúan como el lado derecho que se va a comparar. Esta opción es necesaria al comparar ensamblados.

• --strict-mode

  Realiza comprobaciones de compatibilidad de API en modo estricto.

Opciones específicas del paquete

Estas opciones solo son aplicables cuando se comparan los paquetes.

• --baseline-package

  Especifica la ruta de acceso a un paquete de línea base para validar el paquete actual.

• --enable-strict-mode-for-compatible-tfms

  Valida la compatibilidad de API en modo estricto para los ensamblados de contrato e implementación para todos los marcos de destino compatibles. El valor predeterminado es true.

• --enable-strict-mode-for-compatible-frameworks-in-package

  Valida la compatibilidad de API en modo estricto para los ensamblados compatibles en función de su marco de destino.

• --enable-strict-mode-for-baseline-validation

  Valida la compatibilidad de API en modo estricto para las comprobaciones de línea base del paquete.

• --package-assembly-references

  Especifica las rutas de acceso a las referencias de ensamblado o a sus directorios subyacentes para un marco de destino específico del paquete. Separe los distintos valores con una coma.

• --baseline-package-assembly-references

  Especifica las rutas de acceso a las referencias de ensamblado o a sus directorios subyacentes para un marco de destino específico en el paquete de línea base. Separe los distintos valores con una coma.

• --baseline-package-frameworks-to-ignore

  Especifica el conjunto de marcos de destino que se omitirán desde el paquete de línea base. La cadena de marco debe coincidir exactamente con el nombre de carpeta del paquete de línea base.

Ejemplos

El comando siguiente compara las versiones actuales y de línea base de un ensamblado.

apicompat --left bin\Release\net8.0\LibApp5.dll --right bin\Release\net8.0\LibApp5-baseline.dll

El siguiente comando compara las versiones actuales y de línea base de un paquete.

apicompat package "bin\Release\LibApp5.1.0.0.nupkg" --baseline-package "bin\Release\LibApp5.2.0.0.nupkg"

En el ejemplo siguiente se muestra el comando para comparar las versiones actuales y de línea base de un ensamblado, incluida la comprobación de los cambios en el nombre del parámetro. En el ejemplo también se muestra el aspecto que podría tener la salida si ha cambiado un nombre de parámetro.

>apicompat -l LibApp5-baseline.dll -r LibApp5.dll --enable-rule-cannot-change-parameter-name
API compatibility errors between 'LibApp5-baseline.dll' (left) and 'LibApp5.dll' (right):
CP0017: Parameter name on member 'KitchenHelpers.ToastBreadAsync(int, int)'
changed from 'slices' to 'numSlices'.
API breaking changes found. If those are intentional, the APICompat
suppression file can be updated by specifying the '--generate-suppression-file' parameter.