APIs de pré-visualização
A plataforma .NET leva a compatibilidade a sério. Como tal, o ecossistema de bibliotecas tende a evitar fazer alterações disruptivas, especialmente no que diz respeito à API.
No entanto, ao projetar APIs, é importante ser capaz de coletar feedback dos usuários e fazer alterações na API com base nesse feedback, se necessário. Para evitar surpresas, você deve entender quais APIs você usa são consideradas estáveis e quais ainda estão em desenvolvimento ativo e podem mudar.
Há várias maneiras pelas quais uma API pode expressar que está no formato de visualização:
Todo o componente é considerado em pré-visualização se estiver exposto:
- Numa versão de pré-visualização do runtime do .NET.
- Em um pacote NuGet de pré-lançamento.
Um componente que de outro modo é estável marca APIs específicas como visualização com os seguintes atributos:
Este artigo explica como cada opção funciona e, para desenvolvedores de bibliotecas, como escolher entre essas opções.
Visualizações de tempo de execução do .NET
Com exceção dos candidatos a lançamento (RCs) com uma licença go-live, as versões de visualização do tempo de execução do .NET e do SDK não são suportadas.
Como tal, todas as APIs adicionadas como parte de uma visualização do .NET são consideradas sujeitas a alterações, com base nos comentários que as visualizações recebem. Para usar uma visualização de tempo de execução do .NET, você precisa direcionar explicitamente uma versão mais recente da estrutura em seu projeto. Ao fazer isso, você expressa implicitamente consentimento para consumir APIs que podem mudar.
Pacotes NuGet de pré-lançamento
Os pacotes NuGet podem ser estáveis ou pré-lançamento. Os pacotes de pré-lançamento são marcados como tal com um sufixo de pré-lançamento em sua versão. Por exemplo, System.Text.Json 9.0.0-preview.2.24128.5 tem um sufixo de pré-lançamento de preview.2.24128.5.
Os pacotes de pré-lançamento são comumente usados como um meio de coletar feedback dos primeiros usuários. Geralmente não são apoiados pelo seu autor.
Ao instalar um pacote, seja por meio da CLI ou da interface do usuário, você deve indicar explicitamente se deseja instalar uma versão de pré-lançamento. Ao fazer isso, você expressa implicitamente consentimento para consumir APIs que podem mudar.
RequiresPreviewFeaturesAttribute
O atributo RequiresPreviewFeaturesAttribute é usado para APIs que requerem comportamentos de visualização em toda a pilha, incluindo o tempo de execução, o compilador C# e as bibliotecas. Ao consumir APIs marcadas com esse atributo, você receberá um erro de compilação, a menos que seu arquivo de projeto inclua a propriedade <EnablePreviewFeatures>true</EnablePreviewFeatures>. Definir essa propriedade como true também define <LangVersion>Preview</LangVersion>, que permite o uso de recursos de idioma de visualização.
Por exemplo, no .NET 6, a biblioteca de matemática genérica foi marcada com RequiresPreviewFeaturesAttribute porque exigia membros da interface estática, que estavam em visualização no momento.
ExperimentalAttribute
O .NET 8 adicionou ExperimentalAttribute, que não requer nenhum recurso de tempo de execução ou visualização de linguagem e simplesmente indica que uma determinada API ainda não está estável.
Ao construir com base em uma API experimental, o compilador produz um erro. Cada recurso marcado como experimental tem sua própria ID de diagnóstico separada. Para expressar o consentimento ao uso de uma API experimental, você suprime o diagnóstico específico. Você pode fazer isso por meio de qualquer um dos meios para suprimir diagnósticos, mas a maneira recomendada é adicionar o diagnóstico à propriedade <NoWarn> do projeto.
Como cada recurso experimental tem um ID separado, consentir em usar um recurso experimental não consente em usar outro.
Para obter mais informações, consulte Recursos Experimentais e o artigo no guia C# sobre atributos gerais.
Orientação para desenvolvedores de bibliotecas
Os desenvolvedores de bibliotecas geralmente devem expressar que uma API está em visualização de uma das duas maneiras:
- Para novas APIs introduzidas numa versão pré-lançamento do seu pacote, você não precisa fazer nada; o pacote já expressa a qualidade de pré-visualização.
- Se você quiser enviar um pacote estável que contenha algumas APIs de qualidade de visualização, marque essas APIs usando
[Experimental]. Certifique-se de usar seu próprio de ID de diagnóstico e torná-lo específico para esses recursos. Se tiver vários recursos independentes, considere usar vários IDs.
O atributo [RequiresPreviewFeatures] destina-se apenas a componentes da própria plataforma .NET. Mesmo lá, ele é usado apenas para APIs que exigem recursos de tempo de execução e pré-visualização de linguagem. Se for apenas uma API que está em visualização, a plataforma .NET usa o atributo [Experimental].
A exceção a essa regra é se você estiver criando uma biblioteca estável e quiser expor determinados recursos que, por sua vez, dependem de comportamentos de tempo de execução ou visualização de linguagem. Nesse caso, você deve usar [RequiresPreviewFeatures] para os pontos de entrada desse recurso. No entanto, você precisa considerar que os usuários dessas APIs também precisam ativar os recursos de visualização, o que os expõe a todos os comportamentos de tempo de execução, biblioteca e visualização de idioma.
