O acesso síncrono a opções com validação assíncrona gera um erro

A partir do .NET 11 RC 1, o acesso síncrono a um tipo de opções que usa apenas validadores assíncronos falha rapidamente. Em vez de retornar uma instância de opções sem validação assíncrona, o caminho de criação síncrona lança um OptionsValidationException.

Versão introduzida

.NET 11 RC 1

Comportamento anterior

Anteriormente, em .NET 11 Versão Prévia 6 e Versão Prévia 7, IAsyncValidateOptions<TOptions> era independente de IValidateOptions<TOptions>. Validadores assíncronos eram executados somente por meio do fluxo assíncrono de validação na inicialização.

Quando você acessou um tipo de opções validadas de forma assíncrona por meio de um caminho de criação síncrono, como IOptions<TOptions>.Value, CurrentValue, Get, IOptionsSnapshot<TOptions>.Value, Get ou Create, o validador assíncrono não foi executado. O caminho síncrono retornou uma instância de opções não avaliadas.

Os tipos que implementavam IAsyncValidateOptions<TOptions> diretamente só precisavam implementar ValidateAsync.

Novo comportamento

A partir do .NET 11 RC 1, IAsyncValidateOptions<TOptions> deriva de IValidateOptions<TOptions>, e a interface não é mais contravariante. Validadores assíncronos participam da mesma coleção de validadores que validadores síncronos.

Quando você acessa um tipo de opções com apenas validadores assíncronos por meio de um caminho de criação síncrono, o método herdado Validate retorna uma falha ValidateOptionsResult. em seguida, Create lança um OptionsValidationException. A mensagem de exceção orienta você a chamar ValidateOnStart e concluir a inicialização antes de acessar as opções de forma síncrona.

Os tipos personalizados que implementam IAsyncValidateOptions<TOptions> diretamente agora também devem implementar o método herdado Validate .

Tipo de mudança disruptiva

Essa alteração é uma alteração comportamental e pode afetar a compatibilidade de origem. Em um cenário estreito em que um binário de visualização implementa IAsyncValidateOptions<TOptions> diretamente sem recompilação, a alteração também pode afetar a compatibilidade binária.

Motivo da alteração

A validação de opções assíncronas foi introduzida no .NET 11 Versão Prévia 6 como um caminho de validação somente de inicialização. O trabalho de design posterior para validação pós-inicialização expôs uma lacuna de correção: as opções também têm caminhos de criação e acesso síncronos. Um validador que implementou apenas a interface assíncrona não pôde ser executado por esses caminhos síncronos, portanto, opções inválidas poderiam ser retornadas e armazenadas em cache antes da validação assíncrona ser executada.

Para fechar essa lacuna antes que a API atinja uma versão estável, IAsyncValidateOptions<TOptions> agora deriva de IValidateOptions<TOptions>. O contrato unificado mantém uma coleção de validadores, preserva a ordem de registro e faz com que o acesso síncrono sem suporte falhe com uma exceção acionável. Para obter mais informações, consulte dotnet/runtime#131197 e a proposta de API aprovada.

Para opções que usam somente validadores assíncronos, chame ValidateOnStart e conclua a inicialização do host antes de acessar as opções de forma síncrona:

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

await host.StartAsync();

Evite o acesso síncrono às opções com apenas validadores assíncronos antes da conclusão da inicialização. Esta orientação se aplica aIOptions<TOptions>.Value, , IOptionsMonitor<TOptions>.CurrentValue, IOptionsMonitor<TOptions>.Get, IOptionsSnapshot<TOptions>.Valuee IOptionsFactory<TOptions>.CreateIOptionsSnapshot<TOptions>.Get.

Alguns caminhos permanecem síncronos mesmo depois de você usar ValidateOnStart. A validação de inicialização não fornece valores de IOptionsSnapshot<TOptions> para escopos posteriores, e IOptionsMonitor<TOptions> recria as opções sincronamente após uma alteração de configuração. Se você precisar desses caminhos para validar com êxito, mantenha pelo menos um validador síncrono.

Se você implementar IAsyncValidateOptions<TOptions> diretamente, adicione o método herdado Validate(string? name, TOptions options) e recompile com o .NET 11. Retorne ValidateOptionsResult.Skip quando o validador não se aplica ou retorne ValidateOptionsResult.Fail quando não houver suporte para validação síncrona.

Se o código depender da contravariância removida in TOptions , atualize as atribuições, conversões ou registros afetados.

Você não pode controlar esse comportamento com uma chave do AppContext nem com uma configuração.

APIs afetadas

  • Last updated on