El acceso síncrono a opciones validadas de forma asíncrona genera un error.

A partir de .NET 11 RC 1, el acceso sincrónico a un tipo de opciones que usa solo validadores asincrónicos produce un error rápido. En lugar de devolver una instancia de opciones sin validación asincrónica, la ruta de creación sincrónica lanza una excepción OptionsValidationException.

Versión introducida

.NET 11 RC 1

Comportamiento anterior

Anteriormente, en .NET 11 Preview 6 y Preview 7, IAsyncValidateOptions<TOptions> era independiente de IValidateOptions<TOptions>. Los validadores asincrónicos solo se ejecutaron a través de la ruta de validación asincrónica durante el inicio.

Cuando se accedía a un tipo de opciones validado asincrónicamente mediante una vía de creación sincrónica, como IOptions<TOptions>.Value, CurrentValue, Get, Get, IOptionsSnapshot<TOptions>.Value o Create, el validador asíncrono no se ejecutaba. La ruta de acceso sincrónica devolvió una instancia de opciones no validada.

Los tipos que implementaban IAsyncValidateOptions<TOptions> directamente solo necesitaban implementar ValidateAsync.

Nuevo comportamiento

A partir de .NET 11 RC 1, IAsyncValidateOptions<TOptions> deriva de IValidateOptions<TOptions>y la interfaz ya no es contravariante. Los validadores asincrónicos participan en la misma colección de validadores que los validadores sincrónicos.

Cuando se accede a un tipo de opciones con solo validadores asincrónicos a través de una ruta de creación sincrónica, el método heredado Validate devuelve un error ValidateOptionsResult. Create luego genera una OptionsValidationExceptionexcepción. El mensaje de excepción le dirige a llamar ValidateOnStart y completar el inicio antes de acceder sincrónicamente a las opciones.

Los tipos personalizados que implementan IAsyncValidateOptions<TOptions> directamente ahora también deben implementar el método heredado Validate .

Tipo de cambio disruptivo

Este cambio es un cambio de comportamiento y puede afectar a la compatibilidad de origen. En un escenario estrecho en el que un binario de vista previa implementa IAsyncValidateOptions<TOptions> directamente sin volver a compilar, el cambio también puede afectar a la compatibilidad binaria.

Motivo del cambio

La validación de opciones asincrónicas se introdujo en .NET 11 Preview 6 como ruta de validación solo de inicio. El trabajo de diseño posterior para la validación posterior al inicio ha expuesto una brecha de corrección: las opciones también tienen rutas de acceso y creación sincrónicas. Un validador que solo implementaba la interfaz asíncrona no podía ejecutarse por esas rutas síncronas, por lo que podían devolverse y almacenarse en caché opciones no válidas antes de que se ejecutara la validación asíncrona.

Para cerrar esa brecha antes de que la API alcance una versión estable, IAsyncValidateOptions<TOptions> ahora deriva de IValidateOptions<TOptions>. El contrato unificado mantiene una única colección de validadores, conserva el orden de registro y hace que el acceso síncrono no compatible falle con una excepción que indica cómo actuar. Para más información, consulte dotnet/runtime#131197 y la propuesta de API aprobada.

En el caso de las opciones que usan solo validadores asincrónicos, llame ValidateOnStart a y complete el inicio del host antes de acceder a las opciones de forma sincrónica:

services.AddOptions<MyOptions>()
    .Configure(o => o.Value = 42)
    .ValidateAsync(o => Task.FromResult(o.Value > 0), "Value must be positive.")
    .ValidateOnStart();

await host.StartAsync();

Evite el acceso síncrono a las opciones que solo tienen validadores asíncronos antes de que finalice el inicio. Esta guía se aplica a IOptions<TOptions>.Value, IOptionsMonitor<TOptions>.CurrentValue, IOptionsMonitor<TOptions>.Get, IOptionsSnapshot<TOptions>.Value, , IOptionsSnapshot<TOptions>.Gety IOptionsFactory<TOptions>.Create.

Algunas rutas de acceso permanecen sincrónicas incluso después de usar ValidateOnStart. La validación de inicio no propaga valores iniciales de IOptionsSnapshot<TOptions> en ámbitos posteriores, y IOptionsMonitor<TOptions> recrea las opciones de manera síncrona después de un cambio en la configuración. Si necesita esas rutas de acceso para validarse correctamente, mantenga al menos un validador sincrónico.

Si implementa IAsyncValidateOptions<TOptions> directamente, agregue el método heredado Validate(string? name, TOptions options) y vuelva a compilar con .NET 11. Devuelve ValidateOptionsResult.Skip cuando el validador no se aplica o devuelve ValidateOptionsResult.Fail cuando no se admite la validación sincrónica.

Si su código se basaba en la contravarianza in TOptions eliminada, actualice las asignaciones, conversiones o registros afectados.

No puede controlar este comportamiento con un modificador o una configuración de AppContext.

Las APIs afectadas

  • Last updated on