Partilhar via

Ferramenta de compatibilidade da API Microsoft.DotNet.ApiCompat.Tool

A ferramenta Microsoft.DotNet.ApiCompat.Tool permite executar verificações de compatibilidade de API fora do MSBuild. A ferramenta tem dois modos:

  • Compare um pacote com o pacote de referência.
  • Compare um conjunto com um conjunto de referência.

Instalar

Para instalar a ferramenta, execute o seguinte comando.

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

Para obter mais informações sobre como instalar ferramentas globais, consulte Instalar uma ferramenta global.

Utilização

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

-ou-

apicompat [command] [options]

Comandos

  • package | --package <PACKAGE_FILE>

    Valida a compatibilidade dos ativos do pacote. Se não for especificado, a ferramenta compara as assemblies. <PACKAGE_FILE> Especifica o caminho para o arquivo de pacote.

Opções

Algumas opções aplicam-se tanto à validação de pacote como à de montagem. Outros aplicam-se apenas a montagens ou apenas a pacotes.

Opções gerais

  • --version

    Mostra informações de versão.

  • --generate-suppression-file

    Gera um ficheiro de supressão de compatibilidade.

  • --preserve-unnecessary-suppressions

    Preserva supressões desnecessárias ao regenerar o arquivo de supressão.

    Quando um arquivo de supressão existente é regenerado, seu conteúdo é lido, desserializado em um conjunto de supressões e, em seguida, armazenado em uma lista. Algumas das supressões podem não ser mais necessárias se a incompatibilidade tiver sido corrigida. Quando as supressões são serializadas de volta ao disco, você pode optar por manter todas as expressões existentes (desserializadas) especificando essa opção.

  • --permit-unnecessary-suppressions

    Permite supressões desnecessárias no arquivo de supressão.

  • --suppression-file <FILE>

    Especifica o caminho para um ou mais arquivos de supressão a serem lidos.

  • --suppression-output-file <FILE>

    Especifica o caminho para um ficheiro de supressão para gravar quando --generate-suppression-file for especificado. Se não for especificado, o primeiro --suppression-file caminho será usado.

  • --noWarn <NOWARN_STRING>

    Especifica os IDs de diagnóstico a serem suprimidas. Por exemplo, "$(NoWarn);PKV0001".

  • --respect-internals

    Verifica ambas as APIs internal e public.

  • --roslyn-assemblies-path <FILE>

    Especifica o caminho para o diretório que contém os assemblies Microsoft.CodeAnalysis que você deseja usar. Você só precisa definir essa propriedade se quiser testar com um compilador mais recente do que o que está no SDK.

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

    Controla a verbosidade no nível de log. Os valores permitidos são high, normale low. A predefinição é normal.

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

    Habilita a regra que verifica se os nomes dos parâmetros foram alterados em métodos públicos.

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

    Habilita a regra que verifica se os atributos correspondem.

  • --exclude-attributes-file <FILE>

    Especifica o caminho para um ou mais arquivos que contêm atributos a serem excluídos no formato DocId .

Opções específicas de montagem

Essas opções só são aplicáveis quando conjuntos são comparados.

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

    Especifica o caminho para um ou mais assemblies que servem como o lado esquerdo para comparação. Essa opção é necessária ao comparar montagens.

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

    Especifica o caminho para um ou mais assemblies que servem como o lado direito para comparação. Essa opção é necessária ao comparar montagens.

  • --strict-mode

    Executa verificações de compatibilidade de API no modo estrito.

Opções específicas do pacote

Estas opções só são aplicáveis quando os pacotes são comparados.

  • --baseline-package

    Especifica o caminho para um pacote de linha de base para validar em relação ao pacote atual.

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

    Valida a compatibilidade de API no modo estrito para assemblies de contrato e implementação para todas as estruturas de destino compatíveis. A predefinição é true.

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

    Valida a compatibilidade de API no modo estrito para assemblies que são compatíveis com base em sua estrutura de destino.

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

    Valida a compatibilidade da API no modo estrito para verificações de linha de base do pacote.

  • --package-assembly-references

    Especifica os caminhos para referências de assembly ou os diretórios subjacentes delas para um framework de destino específico no pacote. Separe vários valores com uma vírgula.

  • --baseline-package-assembly-references

    Especifica os caminhos para referências de assembly ou seus diretórios subjacentes para um framework de destino específico no pacote baseline. Separe vários valores com uma vírgula.

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

    Especifica o conjunto de frameworks de destino a ignorar no pacote base. A cadeia de caracteres da estrutura deve corresponder exatamente ao nome da pasta no pacote de linha de base.

Exemplos

O comando a seguir compara as versões atual e de referência de um assembly.

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

O comando a seguir compara as versões atual e de linha de base de um pacote.

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

O exemplo a seguir mostra o comando para comparar as versões atual e de linha de base de um assembly, incluindo a verificação de alterações no nome do parâmetro. O exemplo também mostra como a saída pode parecer se um nome de parâmetro for alterado.

>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.
  • Last updated on