L'accesso sincrono a opzioni validate in modo asincrono solleva un'eccezione

A partire da .NET 11 RC 1, l'accesso sincrono a un tipo di opzioni che usa solo validatori asincroni fallisce immediatamente. Anziché restituire un'istanza di opzioni senza convalida asincrona, il percorso di creazione sincrono genera un'eccezione OptionsValidationException.

Versione introdotta

.NET 11 RC 1

Comportamento precedente

In precedenza, in .NET 11 Preview 6 e Preview 7, IAsyncValidateOptions<TOptions> era indipendente da IValidateOptions<TOptions>. I validator asincroni vengono eseguiti solo tramite il percorso di convalida dell'avvio asincrono.

Quando si accede a un tipo di opzioni con convalida asincrona tramite un percorso di creazione sincrono, ad esempio IOptions<TOptions>.Value, IOptionsSnapshot<TOptions>.ValueGetCurrentValueGeto Create, il validator asincrono non è stato eseguito. Il percorso sincrono ha restituito un'istanza di opzioni non convalidata.

I tipi che implementavano IAsyncValidateOptions<TOptions> direttamente dovevano solo implementare ValidateAsync.

Nuovo comportamento

A partire da .NET 11 RC 1, IAsyncValidateOptions<TOptions> deriva da IValidateOptions<TOptions>e l'interfaccia non è più controvariante. I validatori asincroni fanno parte dello stesso insieme di validatori dei validatori sincroni.

Quando si accede a un tipo di opzioni con solo validator asincroni tramite un percorso di creazione sincrono, il metodo ereditato Validate restituisce un errore ValidateOptionsResult. Create genera quindi un'eccezione OptionsValidationException. Il messaggio di eccezione indica all'utente di chiamare ValidateOnStart e completare l'avvio prima di accedere in modo sincrono alle opzioni.

Anche i tipi personalizzati che implementano IAsyncValidateOptions<TOptions> direttamente devono implementare il metodo ereditato Validate .

Tipo di modifica che causa un'interruzione

Questa modifica è un cambiamento comportamentale e può influire sulla compatibilità dell'origine. In uno scenario stretto in cui un file binario di anteprima implementa IAsyncValidateOptions<TOptions> direttamente senza ricompilazione, la modifica può influire anche sulla compatibilità binaria.

Motivo della modifica

La convalida delle opzioni asincrone è stata introdotta in .NET 11 Preview 6 come percorso di convalida di sola avvio. Il lavoro di progettazione successivo per la convalida post-avvio ha esposto un divario di correttezza: le opzioni hanno anche percorsi di creazione e accesso sincroni. Un validator che ha implementato solo l'interfaccia asincrona non è riuscito a eseguire tali percorsi sincroni, quindi è possibile restituire e memorizzare nella cache le opzioni non valide prima dell'esecuzione della convalida asincrona.

Per chiudere tale gap prima che l'API raggiunga una versione stabile, IAsyncValidateOptions<TOptions> ora deriva da IValidateOptions<TOptions>. Il contratto unificato mantiene un'unica raccolta di validatori, preserva l'ordine di registrazione e fa sì che ogni accesso sincrono non supportato non vada a buon fine, generando un'eccezione che indica come intervenire. Per altre informazioni, vedere dotnet/runtime#131197 e la proposta di API approvata.

Per le opzioni che usano solo validator asincroni, chiamare ValidateOnStart e completare l'avvio dell'host prima di accedere in modo sincrono alle opzioni:

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

await host.StartAsync();

Evitare l'accesso sincrono alle opzioni con esclusivamente validatori asincroni prima del completamento dell'avvio. Queste linee guida si applicano a IOptions<TOptions>.Value, IOptionsMonitor<TOptions>.CurrentValueIOptionsMonitor<TOptions>.Get, IOptionsSnapshot<TOptions>.Value, , IOptionsSnapshot<TOptions>.Gete IOptionsFactory<TOptions>.Create.

Alcuni percorsi rimangono sincroni anche dopo aver usato ValidateOnStart. La convalida all'avvio non propaga IOptionsSnapshot<TOptions> valori iniziali agli ambiti successivi e IOptionsMonitor<TOptions> ricrea sincronicamente le opzioni dopo una modifica della configurazione. Se è necessario convalidare correttamente questi percorsi, mantenere almeno un validator sincrono.

Se si implementa IAsyncValidateOptions<TOptions> direttamente, aggiungere il metodo ereditato Validate(string? name, TOptions options) e ricompilare in .NET 11. Restituisce ValidateOptionsResult.Skip quando il validator non si applica o restituisce ValidateOptionsResult.Fail quando la convalida sincrona non è supportata.

Se il codice si basava sulla controvarianza rimossa in TOptions, aggiorna le assegnazioni, le conversioni di tipo o le registrazioni interessate.

Non è possibile controllare questo comportamento con un'impostazione di configurazione o un'opzione AppContext.

Le API interessate

  • Last updated on