L’accès synchrone à des options validées de manière asynchrone provoque une exception

À compter de .NET 11 RC 1, l’accès synchrone à un type d’options qui utilise uniquement des validateurs asynchrones échoue rapidement. Au lieu de retourner une instance d’options sans validation asynchrone, le processus de création synchrone génère un OptionsValidationException.

Version introduite

.NET 11 RC 1

Comportement antérieur

Auparavant, dans .NET 11 Preview 6 et Preview 7, IAsyncValidateOptions<TOptions> était indépendant de IValidateOptions<TOptions>. Les validateurs asynchrones n’étaient exécutés que via le processus de validation asynchrone au démarrage.

Lorsque vous accédiez à un type d’options validé de manière asynchrone via un chemin de création synchrone, comme IOptions<TOptions>.Value, CurrentValue, Get, IOptionsSnapshot<TOptions>.Value, Get ou Create, le validateur asynchrone ne s’exécutait pas. Le chemin synchrone a retourné une instance d’options non valides.

Les types qui implémentaient directement IAsyncValidateOptions<TOptions> n’avaient qu’à implémenter ValidateAsync.

Nouveau comportement

À partir de .NET 11 RC 1, IAsyncValidateOptions<TOptions> dérive de IValidateOptions<TOptions>, et l’interface n’est plus contravariante. Les validateurs asynchrones font partie de la même collection de validateurs que les validateurs synchrones.

Lorsque vous accédez à un type d’options avec uniquement des validateurs asynchrones via un chemin de création synchrone, la méthode héritée Validate retourne un échec ValidateOptionsResult. Create lève ensuite un OptionsValidationException. Le message d’exception vous indique d’appeler ValidateOnStart et de terminer le démarrage avant d’accéder de manière synchrone aux options.

Les types personnalisés qui implémentent IAsyncValidateOptions<TOptions> directement doivent désormais implémenter la méthode héritée Validate .

Type de changement avec rupture de compatibilité

Cette modification est un changement comportemental et peut affecter la compatibilité de la source. Dans un scénario étroit où un fichier binaire en préversion implémente IAsyncValidateOptions<TOptions> directement sans recompilation, la modification peut également affecter la compatibilité binaire.

Raison du changement

La validation des options asynchrones a été introduite dans .NET 11 Preview 6 en tant que chemin de validation au démarrage uniquement. Le travail de conception ultérieur pour la validation post-démarrage a exposé un écart d’exactitude : les options ont également des chemins de création et d’accès synchrones. Un validateur qui implémentait uniquement l’interface asynchrone n’a pas pu s’exécuter via ces chemins synchrones, de sorte que les options non valides peuvent être retournées et mises en cache avant l’exécution de la validation asynchrone.

Pour combler cet écart avant que l’API atteigne une version stable, IAsyncValidateOptions<TOptions> dérive maintenant de IValidateOptions<TOptions>. Le contrat unifié maintient une seule collection de validateurs, préserve l’ordre d’enregistrement et fait échouer tout accès synchrone non pris en charge avec une exception explicite indiquant la marche à suivre. Pour plus d’informations, consultez dotnet/runtime#131197 et la proposition d’API approuvée.

Pour les options qui utilisent uniquement des validateurs asynchrones, appelez ValidateOnStart et terminez le démarrage de l’hôte avant d’accéder aux options de manière synchrone :

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

await host.StartAsync();

Évitez l’accès synchrone aux options avec uniquement des validateurs asynchrones avant la fin du démarrage. Cette aide s’applique à IOptions<TOptions>.Value, IOptionsMonitor<TOptions>.CurrentValue, IOptionsMonitor<TOptions>.Get, IOptionsSnapshot<TOptions>.Value, IOptionsSnapshot<TOptions>.Get et IOptionsFactory<TOptions>.Create.

Certains chemins restent synchrones même après l’utilisation ValidateOnStart. La validation de démarrage ne génère pas de valeurs initiales IOptionsSnapshot<TOptions> pour les étendues ultérieures et IOptionsMonitor<TOptions> recrée les options de façon synchrone après une modification de configuration. Si vous avez besoin de ces chemins pour valider correctement, conservez au moins un validateur synchrone.

Si vous implémentez IAsyncValidateOptions<TOptions> directement, ajoutez la méthode héritée Validate(string? name, TOptions options) et recompilez sur .NET 11. Retourne ValidateOptionsResult.Skip lorsque le validateur ne s’applique pas ou retourne ValidateOptionsResult.Fail lorsque la validation synchrone n’est pas prise en charge.

Si votre code reposait sur la contravariance supprimée in TOptions, mettez à jour les affectations concernées, les conversions de type ou les enregistrements.

Vous ne pouvez pas contrôler ce comportement avec un commutateur AppContext ou un paramètre de configuration.

API affectées

  • Last updated on