Strumenti di compatibilità API
La compatibilità multipiattaforma è diventata un requisito fondamentale per gli autori di librerie .NET. Tuttavia, in mancanza di strumenti per convalidare assembly e pacchetti, potrebbero contenere modifiche che causano involontariamente un'interruzione. Chi ha il ruolo di autore di librerie si deve assicurare 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 binario .NET Standard 2.0 possa essere eseguito in base al binario .NET 6.
Si potrebbe pensare che una modifica sia sicura e compatibile se l'origine che la utilizza continua a compilare 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 possono causare questo tipo di problemi di compatibilità.
L'SDK .NET 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 che causano un'interruzione. Abilitare le attività MSBuild per convalidare gli assembly in fase di compilazione o i pacchetti quando si crea un 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 è riducibile a pacchetto. 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 in Microsoft.DotNet.ApiCompat.Task. Analogamente, è possibile anche aggiungere un riferimento a questo pacchetto quando si vogliono testare le funzionalità più recenti che non sono ancora disponibili nell'SDK .NET. Ad esempio, è possibile fare riferimento alla versione 9.0.100-anteprima del pacchetto Microsoft.DotNet.ApiCompat.Task utilizzando l'SDK .NET 8.
Per impostazione predefinita, la convalida esegue i controlli di compatibilità. Tuttavia, è anche possibile acconsentire esplicitamene alla modalità strict. In modalità strict, la convalida esegue controlli di uguaglianza. Uguaglianza significa che non sono state apportate aggiunte API o modifiche all'assembly, anche quelle eventualmente compatibili.
I casi d'uso per la modalità strict includono i seguenti:
- Manutenzione, in cui le aggiunte API sono in genere vietate.
- Monitoraggio delle modifiche API. La funzionalità di compatibilità 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 opzioni --enable-strict*
. Per abilitare la modalità strict per le attività MSBuild, aggiungere una o più delle proprietà MSBuild seguenti al file di progetto:
Feedback su .NET
.NET è un progetto di open source. Selezionare un collegamento per fornire feedback: