Strumento globale Microsoft.DotNet.ApiCompat.Tool

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 assemblaggio con un assemblaggio di riferimento.

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.

Uso

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 assemblaggi. <PACKAGE_FILE> specifica il percorso del file del pacchetto.

Opzioni

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

Opzioni generali

• --version

  Mostra le informazioni sulla versione.

• --generate-suppression-file

  Genera un file di soppressione della compatibilità.

• --preserve-unnecessary-suppressions

  Mantiene le soppressioni non necessarie durante la rigenerazione del file di soppressione.

  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 soppressione da leggere.

• --suppression-output-file <FILE>

  Specifica il percorso di un file di eliminazione in cui scrivere quando --generate-suppression-file viene specificato. Se non specificato, il primo percorso --suppression-file è usato.

• --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 che contiene 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 la verbosità del livello di log. I valori consentiti sono high, normale 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 in 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 per uno o più assembly che fungono da parte destra per il confronto. 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 confrontare e convalidare il pacchetto corrente.

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

  Convalida la compatibilità dell'API in modalità rigorosa 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à rigorosa per gli assembly che sono compatibili in base al loro framework di destinazione.

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

  Convalida la compatibilità dell'API in modalità rigorosa per i controlli della base del pacchetto.

• --package-assembly-references

  Specifica i percorsi dei riferimenti all'assembly o delle relative directory sottostanti per un framework di destinazione specifico nel pacchetto. Separare più valori con una virgola.

• --baseline-package-assembly-references

  Specifica i percorsi dei riferimenti all'assembly o le relative directory sottostanti per un framework di destinazione specifico, nel pacchetto di base. Separare più valori con una virgola.

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

  Specifica l'insieme di framework di destinazione da ignorare dal pacchetto di riferimento. 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.