Compartir a través de

API en versión preliminar

  • Artículo

La plataforma .NET se enorgullece de tomarse en serio la compatibilidad. Como tal, el ecosistema de bibliotecas tiende a evitar hacer cambios importantes, especialmente con respecto a la API.

Sin embargo, al diseñar API, es importante recopilar comentarios de los usuarios y modificarla en función de esos comentarios si es necesario. Para evitar sorpresas, es importante que los usuarios comprendan qué API se consideran estables y cuáles siguen en desarrollo activo y podrían cambiar.

Hay varias maneras en que una API puede expresarse para que esté en forma de versión preliminar:

  • Todo el componente se considera versión preliminar:

    • Expuesto en una versión preliminar del entorno de ejecución de .NET
    • Expuesto en un paquete NuGet de versión preliminar

  • Un componente estable marca específicamente determinadas API como versión preliminar:

En este artículo se explica cómo elegir entre estas opciones y cómo funciona cada una de ellas.

Versiones preliminares del entorno de ejecución de .NET

A excepción de las versiones candidatas para lanzamiento (RC) con una licencia de lanzamiento, no se admiten versiones preliminares del entorno de ejecución y el SDK de .NET.

Por lo tanto, las API agregadas como parte de una versión preliminar de .NET se consideran sujetas a cambios, en función de los comentarios que reciben las versiones preliminares. Para usar una versión preliminar del runtime de .NET, debe tener como destino explícitamente una versión de marco más reciente. Al hacerlo, expresa implícitamente el consentimiento para consumir las API que podrían cambiar.

Versión preliminar de paquetes NuGet

Los paquetes NuGet pueden ser estables o marcados como versión preliminar, es decir, el paquete tiene un sufijo de versión preliminar. Por ejemplo, System.Text.Json 9.0.0-preview.2.24128.5 tiene un sufijo de versión preliminar de preview.2.24128.5.

Los autores de paquetes generalmente no admiten paquetes de versión preliminar y los usan como medio para recopilar comentarios de los usuarios pioneros.

Al instalar paquetes, ya sea a través de la CLI o de la interfaz de usuario, generalmente tiene que indicar explícitamente si desea instalar la versión preliminar, de nuevo expresando implícitamente el consentimiento para consumir API que podrían cambiar.

RequiresPreviewFeaturesAttribute

Desde .NET 6, la plataforma incluye el atributo RequiresPreviewFeaturesAttribute.

Este atributo se usa para las API que requieren comportamientos de vista previa en toda la pila, incluido el runtime, el compilador de C# y las bibliotecas. Cuando consuma API marcadas con este atributo, recibirá un error de compilación a menos que el proyecto establezca <EnablePreviewFeatures>true</EnablePreviewFeatures>. Al establecer esa propiedad en true también se establece <LangVersion>Preview</LangVersion>, lo que permite el uso de características de lenguaje de vista previa.

El equipo de .NET utilizó el atributo RequiresPreviewFeaturesAttribute en .NET 6 para probar la matemática genérica, ya que requería miembros de interfaz estáticos, que en ese momento estaban en versión preliminar.

ExperimentalAttribute

.NET 8 ha agregado ExperimentalAttribute, que no requiere ninguna característica en runtime o en vista previa del lenguaje y simplemente indica que una API determinada aún no es estable.

Al compilar en una API experimental, el compilador producirá un error. Cada característica marcada como experimental tiene su propio identificador de diagnóstico independiente. Para expresar su consentimiento para usarlas, suprima el diagnóstico específico. Puede hacerlo a través de cualquiera de los medios para suprimir diagnósticos, pero la manera recomendada es agregar el diagnóstico a la propiedad <NoWarn> del proyecto.

Dado que cada característica experimental tiene un identificador independiente, el consentimiento para usar una no da su consentimiento para usar otra.

Elección de una opción

Los desarrolladores de bibliotecas solo deben usar paquetes NuGet de versión preliminar o marcar las API con [Experimental]:

  • Para las nuevas API introducidas en una versión preliminar del paquete, no es necesario hacer nada; el paquete ya expresa la calidad de la vista previa.

  • Si desea enviar un paquete estable que contenga algunas API de calidad de versión preliminar, debe marcar esas API con [Experimental]. Asegúrese de usar su propio identificador de diagnóstico y de que sea específico de esas características. Si tiene varias características independientes, considere la posibilidad de usar varios identificadores.

El atributo [RequiresPreviewFeatures] solo está diseñado para componentes de la propia plataforma .NET. E incluso allí solo se usa para las API que requieren características en runtime y vista previa del lenguaje. Si es solo una API que está en versión preliminar, la plataforma .NET usa el atributo [Experimental] .

La excepción a esta regla es si va a compilar una biblioteca estable y desea exponer determinadas características que, a su vez, dependen de comportamientos en runtime o vista previa del lenguaje. En ese caso, debe usar [RequiresPreviewFeatures] para los puntos de entrada de esa característica. Sin embargo, debe tener en cuenta que los usuarios de estas API también tienen que activar las características en vista previa, lo que les expone a todos los comportamientos en runtime, biblioteca y vista previa del lenguaje.