Ferramenta global Microsoft.DotNet.ApiCompat.Tool
A ferramenta Microsoft.DotNet.ApiCompat.Tool permite que você execute verificações de compatibilidade de API fora do MSBuild. A ferramenta tem dois modos:
- Comparar um pacote com um pacote de linha de base.
- Comparar um assembly com um assembly de linha de base.
Instalar
Para instalar a ferramenta, execute o comando a seguir.
dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool
Para obter mais informações sobre como instalar ferramentas globais, confira Instalar uma ferramenta global.
Uso
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 especificado, a ferramenta compara os assemblies.
<PACKAGE_FILE>
especifica o caminho para o arquivo do pacote.
Opções
Algumas opções se aplicam à validação do assembly e do pacote. Outros se aplicam somente a assemblies ou somente a pacotes.
Opções gerais
--version
Mostra informações de versão.
--generate-suppression-file
Gera um arquivo 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 depois 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 de leitura para um ou mais arquivos de supressão.
--suppression-output-file <FILE>
Especifica o caminho para um arquivo de supressão no qual gravar quando
--generate-suppression-file
for especificado. Se não for especificado, o primeiro--suppression-file
caminho será usado.--noWarn <NOWARN_STRING>
Especifica as IDs de diagnóstico a serem suprimidas. Por exemplo,
"$(NoWarn);PKV0001"
.--respect-internals
Verifica as APIs
internal
epublic
.--roslyn-assemblies-path <FILE>
Especifica o caminho para o diretório que contém os assemblies Microsoft.CodeAnalysis que você deseja usar. Você só precisará definir essa propriedade se quiser testar com um compilador mais recente do que o que está no SDK.
-v, --verbosity [high|low|normal]
Controla o detalhamento do nível de log. Os valores permitidos são
high
,normal
elow
. O padrão énormal
.--enable-rule-cannot-change-parameter-name
Habilita a regra que verifica se os nomes do parâmetro 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 do assembly
Essas opções só são aplicáveis quando os assemblies 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 os assemblies.
-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 os assemblies.
--strict-mode
Executa verificações de compatibilidade de API no modo estrito.
Opções específicas do pacote
Essas 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 o pacote atual.
--enable-strict-mode-for-compatible-tfms
Valida a compatibilidade da API no modo estrito para os assemblies de contrato e implementação para todas as estruturas de destino compatíveis. O padrão é
true
.--enable-strict-mode-for-compatible-frameworks-in-package
Valida a compatibilidade da API no modo estrito para os assemblies compatíveis com base na 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 seus diretórios subjacentes para uma estrutura de destino específica 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 uma estrutura de destino específica no pacote de linha de base. Separe vários valores com uma vírgula.
--baseline-package-frameworks-to-ignore
Especifica o conjunto de estruturas de destino a serem ignoradas no pacote de linha de 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 atuais e de linha de base 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 atuais 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 atuais 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 a aparência da saída se um nome de parâmetro tiver sido 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.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de