Condividi tramite

Strumenti di compatibilità api

  • Articolo

La compatibilità multipiattaforma è diventata un requisito mainstream per gli autori di librerie .NET. Tuttavia, senza strumenti per convalidare assembly e pacchetti, potrebbero contenere modifiche non intenzionali. In qualità di autore della libreria, è necessario assicurarsi che gli assembly con più destinazioni siano compatibili. Ad esempio, per un pacchetto con più destinazioni per .NET 6 e .NET Standard 2.0, è necessario assicurarsi che il codice compilato in base al file binario .NET Standard 2.0 possa essere eseguito sul file binario .NET 6.

Si potrebbe pensare che una modifica sia sicura e compatibile se l'utilizzo di origine di tale modifica continua a essere compilato senza modifiche. Tuttavia, le modifiche possono comunque causare problemi in fase di esecuzione se il consumer non è stato ricompilato. Ad esempio, l'aggiunta di un parametro facoltativo a un metodo o la modifica del valore di una costante può causare questi tipi di problemi di compatibilità.

.NET SDK offre diversi modi per confrontare le versioni compilate per framework di destinazione diversi. È anche possibile convalidare una versione più recente rispetto a una versione di base per assicurarsi che non siano state introdotte modifiche di rilievo. Abilitare le attività di MSBuild per convalidare gli assembly in fase di compilazione o i pacchetti quando si esegue il pacchetto. In alternativa, usare lo strumento globale Microsoft.DotNet.ApiCompat.Tool per convalidare all'esterno di MSBuild.

Per altre informazioni sulla convalida dei pacchetti, vedere Convalida dei pacchetti. La convalida dell'assembly deve essere usata quando l'app non è comprimibile. Per altre informazioni sulla convalida degli assembly, vedere Convalida dell'assembly.

Nota

Per eseguire la convalida dell'assembly come attività MSBuild, è necessario aggiungere un riferimento al pacchetto a Microsoft.DotNet.ApiCompat.Task. Analogamente, è anche possibile aggiungere un riferimento a questo pacchetto quando si vogliono testare le funzionalità più recenti che non sono ancora disponibili in .NET SDK. Ad esempio, è possibile fare riferimento alla versione 9.0.100-preview del pacchetto Microsoft.DotNet.ApiCompat.Task usando .NET 8 SDK.

Modalità strict

Per impostazione predefinita, la convalida esegue controlli di compatibilità . Tuttavia, è anche possibile acconsentire esplicitamente alla modalità strict. In modalità strict, la convalida esegue controlli di uguaglianza . L'uguaglianza significa che non sono state apportate aggiunte API o modifiche agli assembly, anche quelle compatibili.

I casi d'uso per la modalità strict includono quanto segue:

  • Manutenzione, in cui le aggiunte api sono in genere vietate.
  • Per tenere traccia delle modifiche dell'API. La funzionalità di compatibilità dell'API registra tutte le differenze di compatibilità nel file di eliminazione se si imposta ApiCompatGenerateSuppressionFile su true.

Per abilitare la modalità strict per lo strumento da riga di comando, specificare l'opzione --strict-mode o una delle --enable-strict* opzioni. Per abilitare la modalità strict per le attività di MSBuild, aggiungere una o più delle proprietà MSBuild seguenti al file di progetto: