APIs de pré-visualização

  • Artigo

A plataforma .NET se orgulha de levar a compatibilidade a sério. Por isso, o ecossistema de bibliotecas tende a evitar fazer alterações significativas, especialmente com relação à API.

No entanto, ao projetar APIs, é importante coletar comentários dos usuários e alterar a API com base nesses comentários, se necessário. Para evitar surpresas, é importante que os usuários entendam quais APIs são consideradas estáveis e quais ainda estão em desenvolvimento ativo e podem sofrer alterações.

Há várias maneiras de uma API se expressar em forma de pré-visualização:

  • O componente inteiro é considerado uma pré-visualização:

    • Exposto em uma versão prévia do runtime do .NET
    • Exposto em um pacote NuGet de pré-lançamento

  • Um componente estável marca especificamente determinadas APIs como pré-visualização:

Este artigo explica como escolher entre essas opções e como cada uma delas funciona.

Visualizações do runtime do .NET

Com exceção dos candidatos à versão (RCs) com uma licença go-live, não há suporte para versões prévias do runtime e do SDK do .NET.

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 que as visualizações recebem. Para usar uma visualização do runtime do .NET, você precisa direcionar explicitamente uma versão mais recente da estrutura. Ao fazer isso, você expressa implicitamente o consentimento para consumir APIs que podem ser alteradas.

Pacotes NuGet de Pré-lançamento

Os pacotes NuGet podem ser estáveis ou marcados como pré-lançamento, ou seja, o pacote tem um sufixo de pré-lançamento. Por exemplo, System.Text.Json 9.0.0-preview.2.24128.5 tem um sufixo de pré-lançamento preview.2.24128.5.

Os autores de pacotes geralmente não dão suporte para pacotes de pré-lançamento e os usam como um meio de coletar comentários dos usuários pioneiros.

Ao instalar pacotes, seja por meio da CLI ou da interface do usuário, você geralmente precisa indicar explicitamente se deseja instalar o pré-lançamento, mais uma vez expressando implicitamente o consentimento para consumir APIs que podem ser alteradas.

RequiresPreviewFeaturesAttribute

Desde o .NET 6, a plataforma inclui o atributo RequiresPreviewFeaturesAttribute.

Esse atributo é usado para APIs que exigem comportamentos de pré-visualização em toda a pilha, incluindo o runtime, o compilador C# e as bibliotecas. Ao consumir APIs marcadas com esse atributo, você receberá um erro de build, a menos que seu projeto defina <EnablePreviewFeatures>true</EnablePreviewFeatures>. A definição dessa propriedade como true também define <LangVersion>Preview</LangVersion>, permitindo o uso de recursos da linguagem de pré-visualização.

A equipe do .NET usou o atributo RequiresPreviewFeaturesAttribute no .NET 6 para testar a matemática genérica, pois ela exigia membros de interface estáticos, que estavam em pré-visualização na época.

ExperimentalAttribute

O .NET 8 adicionou ExperimentalAttribute, que não exige nenhuma versão prévia do recurso de runtime ou linguagem e simplesmente indica que uma determinada API ainda não está estável.

Ao criar com base em uma API experimental, o compilador produzirá um erro. Cada recurso marcado como experimental tem sua própria ID de diagnóstico separada. Para expressar o consentimento para usá-los, suprima 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 uma ID separada, consentir com o uso de um recurso experimental não significa consentir com o uso de outro.

Escolha entre as opções

Os desenvolvedores de bibliotecas devem usar somente pacotes NuGet de pré-lançamento ou marcar APIs com [Experimental]:

  • 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 pré-visualização, deverá marcar essas APIs usando [Experimental]. Certifique-se de usar sua própria ID de diagnóstico e torná-la específica para esses recursos. Se você tiver vários recursos independentes, considere o uso de várias IDs.

O atributo [RequiresPreviewFeatures] destina-se apenas a componentes da própria plataforma .NET. E, mesmo assim, é usado apenas para APIs que exigem versões prévias do recurso de linguagem e runtime. Se for apenas uma API que está em pré-visualização, 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 runtime ou de visualização da linguagem. Nesse caso, você deve usar [RequiresPreviewFeatures] para os pontos de entrada desse recurso. No entanto, é preciso considerar que os usuários dessas APIs também precisam ativar as versões prévias do recurso, o que os expõe a todos os comportamentos de visualização da linguagem, biblioteca e do runtime.