API di anteprima
La piattaforma .NET prende seriamente in considerazione la compatibilità. Di conseguenza, l'ecosistema di librerie tende a evitare di apportare modifiche di rilievo, soprattutto per quanto riguarda l'API.
Tuttavia, quando si progettano API, è importante essere in grado di raccogliere feedback dagli utenti e apportare modifiche all'API in base a tale feedback, se necessario. Per evitare sorprese, è necessario comprendere quali API usate sono considerate stabili e quali sono ancora in fase di sviluppo attivo e potrebbero cambiare.
Esistono diversi modi in cui un'API può esprimere che è in formato di anteprima:
L'intero componente viene considerato come una versione preliminare se viene reso pubblico.
- In una versione di anteprima del runtime .NET.
- In un pacchetto NuGet in fase di anteprima.
Un componente altrimenti stabile contrassegna api specifiche come anteprima con gli attributi seguenti:
Questo articolo illustra il funzionamento di ogni opzione e, per gli sviluppatori di librerie, come scegliere tra queste opzioni.
Versioni di anteprima del runtime .NET
Ad eccezione dei candidati alla versione (RCS) con una licenza go-live, le versioni di anteprima del runtime .NET e dell'SDK non sono supportate.
Di conseguenza, tutte le API aggiunte come parte di un'anteprima .NET vengono considerate soggette a modifiche, in base al feedback ricevuto dalle anteprime. Per usare un'anteprima del runtime .NET, è necessario specificare in modo esplicito una versione del framework più recente nel progetto. In questo modo, si esprime in modo implicito il consenso all'uso delle API che potrebbero cambiare.
Pacchetti NuGet in fase di pre-rilascio
I pacchetti NuGet possono essere stabili o versione preliminare. I pacchetti non definitivi vengono contrassegnati come tali con un suffisso di prerelease sulla loro versione. Ad esempio, System.Text.Json 9.0.0-preview.2.24128.5 ha un suffisso di prerelease di preview.2.24128.5.
I pacchetti di versione preliminare vengono comunemente usati come mezzo per raccogliere feedback dagli early adopter. In genere non sono supportati dal loro autore.
Quando si installa un pacchetto, tramite l'interfaccia della riga di comando o l'interfaccia utente, è necessario indicare in modo esplicito se si vuole installare una versione non definitiva. In questo modo, si esprime in modo implicito il consenso all'uso delle API che potrebbero cambiare.
RequiresPreviewFeaturesAttribute
L'attributo RequiresPreviewFeaturesAttribute viene usato per le API che richiedono comportamenti di anteprima nello stack, tra cui il runtime, il compilatore C# e le librerie. Quando si utilizzano API contrassegnate con questo attributo, si riceverà un errore di compilazione a meno che il file di progetto non includa la proprietà <EnablePreviewFeatures>true</EnablePreviewFeatures>. L'impostazione di tale proprietà su true imposta anche <LangVersion>Preview</LangVersion>, che consente l'uso delle funzionalità del linguaggio di anteprima.
Ad esempio, in .NET 6 la libreria matematica generica è stata contrassegnata con RequiresPreviewFeaturesAttribute perché richiedeva membri dell'interfaccia statica, che erano in anteprima al momento.
ExperimentalAttribute
.NET 8 ha aggiunto ExperimentalAttribute, che non richiede alcuna funzionalità di runtime o anteprima del linguaggio e indica semplicemente che una determinata API non è ancora stabile.
Quando si compila con un'API sperimentale, il compilatore genera un errore. Ogni funzionalità contrassegnata come sperimentale ha un PROPRIO ID di diagnostica separato. Per esprimere il consenso all'uso di un'API sperimentale, eliminare la diagnostica specifica. È possibile farlo tramite uno qualsiasi dei mezzi per eliminare la diagnostica, ma il modo consigliato consiste nell'aggiungere la diagnostica alla proprietà <NoWarn> del progetto.
Poiché ogni funzionalità sperimentale ha un ID separato, il consenso all'uso di una funzionalità sperimentale non consente l'uso di un'altra funzionalità.
Per altre informazioni, vedere Funzionalità sperimentali e l'articolo della guida di C# su attributi generali.
Linee guida per sviluppatori di librerie
Gli sviluppatori di librerie devono in genere esprimere che un'API è in anteprima in uno dei due modi seguenti:
- Per le nuove API introdotte in una versione non definitiva del pacchetto, non è necessario eseguire alcuna operazione; il pacchetto esprime già la qualità di anteprima.
- Se si vuole distribuire un pacchetto stabile che contiene alcune API di qualità di anteprima, è necessario contrassegnare tali API usando
[Experimental]. Assicurarsi di usare il proprio ID di diagnostica e renderlo specifico per tali funzionalità. Se si dispone di più funzionalità indipendenti, prendere in considerazione l'uso di più ID.
L'attributo [RequiresPreviewFeatures] è destinato solo ai componenti della piattaforma .NET stessa. Anche in questo caso, viene usato solo per le API che richiedono funzionalità di anteprima del runtime e del linguaggio. Se si tratta solo di un'API in anteprima, la piattaforma .NET usa l'attributo [Experimental].
L'eccezione a questa regola è se si sta creando una libreria stabile e si vogliono esporre determinate funzionalità che a loro volta dipendono dai comportamenti di anteprima del runtime o del linguaggio. In tal caso, è consigliabile 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, che le espone a tutti i comportamenti di runtime, libreria e anteprima del linguaggio.
