API di anteprima

La piattaforma .NET prende seriamente la compatibilità, pertanto l'ecosistema delle librerie tende a evitare di apportare modifiche che causano un'interruzione, soprattutto rispetto alle API.

Tuttavia, nell'ambito della progettazione delle API, è importante raccogliere feedback dagli utenti e cambiare le API in base a tale feedback, se necessario. Per evitare sorprese, è importante che gli utenti comprendano quali API siano considerate stabili e quali siano ancora in fase di sviluppo attivo e potrebbero cambiare.

È possibile attribuire la forma di anteprima a un'API in molti modi:

• Tutto il componente viene considerato in anteprima:

  • Esposto in una versione di anteprima del runtime .NET
  • Esposto in una versione preliminare di un pacchetto NuGet

• Un componente altrimenti stabile contrassegna specificatamente determinate API come di anteprima:

  • Contrassegnata con RequiresPreviewFeaturesAttribute
  • Contrassegnata con ExperimentalAttribute

Questo articolo spiega come scegliere tra queste opzioni e come funziona ognuna di esse.

Anteprime runtime .NET

Ad eccezione delle versioni finali candidate (RC) con una licenza attiva, le versioni di anteprima del runtime .NET e SDK non sono supportate.

Di conseguenza, tutte le API aggiunte nell'ambito di un'anteprima di .NET sono soggette a modifiche, in base al feedback ricevuto dalle anteprime. Per usare un'anteprima del runtime .NET, è necessario fare riferimento esplicitamente a una versione del framework più recente. In questo modo, si esprime in modo implicito il consenso a consumare le API che potrebbero cambiare.

Versione preliminare di pacchetti NuGet

I pacchetti NuGet possono essere stabili o contrassegnati come versioni preliminari, ovvero quando il pacchetto ha un suffisso di versione preliminare. Ad esempio, System.Text.Json 9.0.0-preview.2.24128.5 ha un suffisso di versione preliminare di preview.2.24128.5.

Gli autori dei pacchetti in genere non supportano i pacchetti di versioni preliminari e li usano come mezzo per raccogliere feedback dagli early adopter.

Quando si installano i pacchetti tramite interfaccia della riga di comando o interfaccia utente, in genere è necessario indicare esplicitamente se si desidera installare la versione preliminare, dietro consenso implicito al consumo delle API che potrebbero cambiare.

RequiresPreviewFeaturesAttribute

Da .NET 6, la piattaforma include l'attributo RequiresPreviewFeaturesAttribute.

Questo attributo viene usato per le API che richiedono comportamenti di anteprima nello stack, tra cui runtime, compilatore C# e librerie. Quando si consumano le API contrassegnate con questo attributo, si riceverà un errore di compilazione, a meno che il progetto imposti <EnablePreviewFeatures>true</EnablePreviewFeatures>. Impostando tale proprietà su true si imposterà anche <LangVersion>Preview</LangVersion>, consentendo l'utilizzo delle funzionalità del linguaggio di anteprima.

Il team .NET ha usato l'attributo RequiresPreviewFeaturesAttribute in .NET 6 per testare operazioni matematiche generiche, perché ha richiesto membri dell'interfaccia statici in anteprima in quel momento.

ExperimentalAttribute

.NET 8 ha aggiunto ExperimentalAttribute, che non richiede alcun runtime o funzionalità di anteprima del linguaggio e semplicemente indica che una determinata API non è ancora stabile.

Quando si effettua una compilazione rispetto a un'API sperimentale, il compilatore produrrà un errore. Ogni funzionalità contrassegnata come sperimentale ha il proprio ID di diagnostica separato. Per esprimere il consenso al loro utilizzo, si elimina la diagnostica specifica. È possibile utilizzare qualsiasi mezzo di eliminazione della diagnostica, ma si consiglia di procedere aggiungendo la diagnostica alla proprietà <NoWarn> del progetto.

Considerando che ogni funzionalità sperimentale ha un ID separato, il consenso all'utilizzo di una funzionalità sperimentale non vale per le altre funzionalità.

Scegliere tra le opzioni

Gli sviluppatori delle librerie dovrebbero usare solo le versioni preliminari dei pacchetti NuGet o contrassegnare le API con [Experimental]:

• Per le nuove API introdotte in una versione preliminare del pacchetto, non è necessario effettuare alcuna azione; il pacchetto esprime già la qualità di anteprima.

• Se si desidera offrire un pacchetto stabile che contenga alcune API di qualità di anteprima, sarebbe necessario contrassegnare tali API con [Experimental]. Verificare di usare il proprio ID di diagnostica e renderlo specifico per tali funzionalità. In presenza di più funzionalità indipendenti, valutare l'utilizzo di più ID.

L'attributo [RequiresPreviewFeatures] si riferisce solo ai componenti della piattaforma .NET stessa. E anche in quel caso viene usato unicamente per le API che richiedono funzionalità di anteprima del runtime e del linguaggio. Se è presente solo un'API in anteprima, la piattaforma .NET usa l'attributo [Experimental].

Si verifica un'eccezione a questa regola se si crea una libreria stabile e si desidera esporre determinate funzionalità che a loro volta dipendono da comportamenti di anteprima del runtime o del linguaggio. In tal caso, sarebbe necessario usare [RequiresPreviewFeatures] per i punti di ingresso di tale funzionalità. Tuttavia, è necessario considerare che gli utenti di tali API devono attivare anche le funzionalità di anteprima, operazione che le espone a tutti i comportamenti di anteprima del runtime, della libreria e del linguaggio.