API de versión preliminar
La plataforma .NET toma en serio la compatibilidad. Por lo tanto, el ecosistema de bibliotecas tiende a evitar realizar cambios importantes, especialmente con respecto a la API.
Sin embargo, al diseñar API, es importante poder recopilar comentarios de los usuarios y realizar cambios en la API en función de esos comentarios si es necesario. Para evitar sorpresas, debe comprender qué API usa se consideran estables y cuáles siguen en desarrollo activo y podrían cambiar.
Hay varias maneras en que una API puede expresar que está en forma de vista previa:
El componente completo se considera versión preliminar si se expone:
- En una versión preliminar del entorno de ejecución de .NET.
- En un paquete NuGet de versión preliminar.
En caso contrario, un componente estable marca las API específicas como versión preliminar con los atributos siguientes:
En este artículo se explica cómo funciona cada opción y, para los desarrolladores de bibliotecas, cómo elegir entre estas opciones.
Versiones preliminares del entorno de ejecución de .NET
A excepción de los candidatos de lanzamiento (RCs) 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 entorno de ejecución de .NET, debe tener como destino explícitamente una versión de marco más reciente en el proyecto. Al hacerlo, expresa implícitamente el consentimiento para consumir las API que podrían cambiar.
Paquetes NuGet en versión preliminar
Los paquetes NuGet pueden ser estables o de versión preliminar. Los paquetes de versión preliminar se marcan como tales con un sufijo de versión preliminar en su versión. Por ejemplo, System.Text.Json 9.0.0-preview.2.24128.5 tiene el sufijo de versión preliminar preview.2.24128.5.
Los paquetes de versión preliminar se suelen usar como medio para recopilar comentarios de los usuarios pioneros. Por lo general, no cuentan con el apoyo de su autor.
Al instalar un paquete, ya sea a través de la CLI o la interfaz de usuario, debe indicar explícitamente si desea instalar una versión preliminar. Al hacerlo, da su consentimiento implícito para utilizar los APIs que podrían modificarse.
RequiresPreviewFeaturesAttribute
El atributo RequiresPreviewFeaturesAttribute se usa para las API que requieren comportamientos de vista previa en toda la pila, incluido el entorno de ejecución, el compilador de C# y las bibliotecas. Cuando utilice APIs marcadas con este atributo, recibirá un error de construcción a menos que el archivo del proyecto incluya la propiedad <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.
Por ejemplo, en .NET 6, la biblioteca de matemáticas genéricas se marcó con RequiresPreviewFeaturesAttribute porque requería miembros de interfaz estática, que estaban en versión preliminar en ese momento.
ExperimentalAttribute
.NET 8 añadió ExperimentalAttribute, que no requiere ninguna característica en tiempo de ejecución ni previsualización del lenguaje y simplemente indica que una API específica aún no es estable.
Al compilar en una API experimental, el compilador genera un error. Cada característica marcada como experimental tiene su propio identificador de diagnóstico independiente. Para expresar el consentimiento al uso de una API experimental, suprima el diagnóstico específico. Puede hacerlo mediante cualquiera de los métodos para suprimir diagnósticos, pero la forma 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 característica experimental no da su consentimiento para usar otra.
Para obtener más información, consulte Características experimentales y el artículo de la guía de C# sobre atributos generales.
Guía para desarrolladores de bibliotecas
Por lo general, los desarrolladores de bibliotecas deben expresar que una API está en versión preliminar de una de estas dos maneras:
- 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 versión preliminar.
- Si desea enviar un paquete estable que contenga algunas API de calidad de versión preliminar, debe marcar esas API mediante
[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. Incluso allí, solo se usa para las API que requieren características en tiempo de ejecución y versión preliminar 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 tiempo de ejecución 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 versión preliminar, lo que los expone a todos los comportamientos en tiempo de ejecución, biblioteca y vista previa del lenguaje.
