Strumento globale Microsoft.DotNet.ApiCompat.Tool

Articolo
04/10/2024

Lo strumento Microsoft.DotNet.ApiCompat.Tool consente di eseguire controlli di compatibilità api all'esterno di MSBuild. Lo strumento ha due modalità:

Confrontare un pacchetto con un pacchetto di base.
Confrontare un assembly con un assembly di base.

Installare

Per installare lo strumento, eseguire il comando seguente.

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

Per altre informazioni sull'installazione degli strumenti globali, vedere Installare uno strumento globale.

Utilizzo

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

oppure

apicompat [command] [options]

Comandi

package | --package <PACKAGE_FILE>

Convalida la compatibilità degli asset del pacchetto. Se non specificato, lo strumento confronta gli assembly. <PACKAGE_FILE> specifica il percorso al file di pacchetto.

Opzioni

Alcune opzioni si applicano sia alla convalida dell'assembly che del pacchetto. Altri si applicano solo agli assembly o solo ai pacchetti.

Opzioni generali

--version

Mostra le informazioni sulla versione.
--generate-suppression-file

Genera un file di eliminazione della compatibilità.
--preserve-unnecessary-suppressions

Mantiene eliminazioni non necessarie durante la rigenerazione del file di eliminazione.

Quando un file di eliminazione esistente viene rigenerato, il relativo contenuto viene letto, deserializzato in un set di eliminazioni e quindi archiviato in un elenco. Alcune delle eliminazioni potrebbero non essere più necessarie se l'incompatibilità è stata risolta. Quando le eliminazioni vengono serializzate su disco, è possibile scegliere di mantenere tutte le espressioni esistenti (deserializzate) specificando questa opzione.
--permit-unnecessary-suppressions

Consente eliminazioni non necessarie nel file di eliminazione.
--suppression-file <FILE>

Specifica il percorso di uno o più file di eliminazione da cui leggere.
--suppression-output-file <FILE>

Specifica il percorso di un file di eliminazione in cui scrivere quando viene specificato --generate-suppression-file. Se non specificato, viene utilizzato il primo elemento --suppression-file.
--noWarn <NOWARN_STRING>

Specifica gli ID di diagnostica da eliminare. Ad esempio, "$(NoWarn);PKV0001".
--respect-internals

Controlla sia le API internal che public.
--roslyn-assemblies-path <FILE>

Specifica il percorso della directory contenente gli assembly Microsoft.CodeAnalysis che si desidera utilizzare. È necessario impostare questa proprietà solo se si vuole eseguire il test con un compilatore più recente rispetto a quello presente nell'SDK.
-v, --verbosity [high|low|normal]

Controlla il livello di dettaglio dei log. I valori consentiti sono high, normal e low. Il valore predefinito è normal.
--enable-rule-cannot-change-parameter-name

Abilita la regola che controlla se i nomi dei parametri sono stati modificati nei metodi pubblici.
--enable-rule-attributes-must-match

Abilita la regola che controlla se gli attributi corrispondono.
--exclude-attributes-file <FILE>

Specifica il percorso di uno o più file che contengono attributi da escludere nel formato DocId.

Opzioni specifiche dell'assembly

Queste opzioni sono applicabili solo quando vengono confrontati gli assembly.

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

Specifica il percorso di uno o più assembly che fungono da lato sinistro da confrontare. Questa opzione è necessaria durante il confronto degli assembly.
-r, --right, --right-assembly <PATH>

Specifica il percorso di uno o più assembly che fungono da lato destro da confrontare. Questa opzione è necessaria durante il confronto degli assembly.
--strict-mode

Esegue i controlli di compatibilità delle API in modalità strict.

Opzioni specifiche del pacchetto

Queste opzioni sono applicabili solo quando vengono confrontati i pacchetti.

--baseline-package

Specifica il percorso di un pacchetto di base per convalidare il pacchetto corrente.
--enable-strict-mode-for-compatible-tfms

Convalida la compatibilità dell'API in modalità strict per gli assembly di contratto e implementazione per tutti i framework di destinazione compatibili. Il valore predefinito è true.
--enable-strict-mode-for-compatible-frameworks-in-package

Convalida la compatibilità dell'API in modalità strict per gli assembly compatibili in base al framework di destinazione.
--enable-strict-mode-for-baseline-validation

Convalida la compatibilità dell'API in modalità strict per i controlli della baseline del pacchetto.
--package-assembly-references

Specifica i percorsi dei riferimenti all'assembly o le relative directory sottostanti per un framework di destinazione specifico nel pacchetto. Se si specificano più valori, separarli con virgole.
--baseline-package-assembly-references

Specifica i percorsi dei riferimenti all'assembly o le relative directory sottostanti per un framework di destinazione specifico nel pacchetto baseline. Se si specificano più valori, separarli con virgole.
--baseline-package-frameworks-to-ignore

Specifica il set di framework di destinazione da ignorare dal pacchetto di base. La stringa del framework deve corrispondere esattamente al nome della cartella nel pacchetto di base.

Esempi

Il comando seguente confronta le versioni correnti e di base di un assembly.

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

Il comando seguente confronta le versioni correnti e di base di un pacchetto.

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

Nell'esempio seguente viene illustrato il comando per confrontare le versioni correnti e di base di un assembly, incluso il controllo delle modifiche al nome del parametro. L'esempio mostra anche l'aspetto dell'output se un nome di parametro è stato modificato.

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

Condividi tramite