APIs de pré-visualização
A plataforma .NET leva a compatibilidade a sério. Dessa forma, o ecossistema da biblioteca tende a evitar fazer alterações significativas, especialmente no que diz respeito à API.
No entanto, ao criar APIs, é importante ser capaz de coletar comentários 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 versão prévia:
O componente inteiro será considerado versão prévia se for exposto:
- Em uma versão prévia do runtime do .NET.
- Em um pacote NuGet pré-lançamento.
Outro componente 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 biblioteca, como escolher entre essas opções.
Pré-visualizações do runtime do .NET
Com exceção dos Release Candidates (RCs) com uma licença go-live, as versões prévias do .NET runtime e do SDK não são suportadas.
Dessa forma, todas as APIs adicionadas como parte de uma visualização do .NET são consideradas sujeitas a alterações, com base nos comentários recebidos pelas visualizações. Para usar uma versão prévia do runtime do .NET, você precisa direcionar explicitamente uma versão mais recente da estrutura em seu projeto. Ao fazer isso, você expressa implicitamente o 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 preview.2.24128.5.
Os pacotes de pré-lançamento geralmente são usados como um meio de coletar comentários dos primeiros adotantes. Eles geralmente não são suportados por seu autor.
Ao instalar um pacote, 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 o consentimento para consumir APIs que podem mudar.
RequiresPreviewFeaturesAttribute
O atributo RequiresPreviewFeaturesAttribute é usado para APIs que exigem comportamentos de visualização em toda a pilha, incluindo o runtime, o compilador C# e bibliotecas. Ao consumir APIs marcadas com esse atributo, você receberá um erro de build, a menos que o arquivo de projeto inclua a propriedade <EnablePreviewFeatures>true</EnablePreviewFeatures>. Definir essa propriedade como true também define <LangVersion>Preview</LangVersion>, o que permite o uso de recursos de linguagem de visualização.
Por exemplo, no .NET 6, a biblioteca matemática genérica foi marcada com RequiresPreviewFeaturesAttribute porque exigia membros de interface estática, que estavam em versão prévia na época.
ExperimentalAttribute
O .NET 8 adicionou ExperimentalAttribute, que não exige nenhum recurso de runtime ou visualização de idioma e simplesmente indica que uma determinada API ainda não está estável.
Ao construir contra 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 para usar uma API experimental, você suprime o diagnóstico específico. Você pode fazer isso por meio de qualquer um dos meios para suprimir o diagnóstico, mas a maneira recomendada é adicionar o diagnóstico à propriedade <NoWarn> do projeto.
Como cada recurso experimental tem uma ID separada, consentir em usar um recurso experimental não consente em usar outro.
Para mais informações, consulte Recursos experimentais e o artigo no guia de C# sobre atributos gerais.
Diretrizes para desenvolvedores de biblioteca
Os desenvolvedores de biblioteca geralmente devem expressar que uma API está em versão prévia de uma das duas maneiras:
- Para novas APIs introduzidas em uma versão de pré-lançamento do seu pacote, você não precisa fazer nada; o pacote já expressa a qualidade da 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 sua própria identificação de diagnóstico e assegure-se de que ela seja específica para essas funcionalidades. Se você tiver várias características independentes, considere usar vários identificadores.
O atributo [RequiresPreviewFeatures] destina-se apenas a componentes da própria plataforma .NET. Mesmo lá, ele é usado apenas para APIs que exigem recursos de runtime e visualização de idioma. Se for apenas uma API que está em versão prévia, a plataforma .NET usará 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 visualização de linguagem ou runtime. 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 recursos de visualização, o que os expõe a todos os comportamentos de runtime, biblioteca e visualização de idioma.
