Modèle d’options dans ASP.NET CoreOptions pattern in ASP.NET Core

Par Luke LathamBy Luke Latham

Le modèle d’options utilise des classes pour représenter les groupes de paramètres associés.The options pattern uses classes to represent groups of related settings. Quand les paramètres de configuration sont isolés par scénario dans des classes distinctes, l’application est conforme à deux principes d’ingénierie logicielle importants :When configuration settings are isolated by scenario into separate classes, the app adheres to two important software engineering principles:

Ces options fournissent également un mécanisme de validation des données de configuration.Options also provide a mechanism to validate configuration data. Pour plus d'informations, reportez-vous à la section Validation des options.For more information, see the Options validation section.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

PrérequisPrerequisites

Référencer le métapackage Microsoft.AspNetCore.App ou ajouter une référence de package au package Microsoft.Extensions.Options.ConfigurationExtensions.Reference the Microsoft.AspNetCore.App metapackage or add a package reference to the Microsoft.Extensions.Options.ConfigurationExtensions package.

Interfaces d’optionsOptions interfaces

IOptionsMonitor<TOptions> permet de récupérer des options et de gérer les notifications d’options pour les instances TOptions.IOptionsMonitor<TOptions> is used to retrieve options and manage options notifications for TOptions instances. IOptionsMonitor<TOptions> prend en charge les scénarios suivants :IOptionsMonitor<TOptions> supports the following scenarios:

Des scénarios post-configuration vous permettent de définir ou de modifier les options après chaque configuration de IConfigureOptions<TOptions>.Post-configuration scenarios allow you to set or change options after all IConfigureOptions<TOptions> configuration occurs.

IOptionsFactory<TOptions> est chargée de créer les instances d’options.IOptionsFactory<TOptions> is responsible for creating new options instances. Elle dispose d’une seule méthode Create.It has a single Create method. L’implémentation par défaut prend toutes les IConfigureOptions<TOptions> et IPostConfigureOptions<TOptions> inscrites et exécute toutes les configurations, puis les post-configurations.The default implementation takes all registered IConfigureOptions<TOptions> and IPostConfigureOptions<TOptions> and runs all the configurations first, followed by the post-configuration. Elle fait la distinction entre IConfigureNamedOptions<TOptions> et IConfigureOptions<TOptions> et n’appelle que l’interface appropriée.It distinguishes between IConfigureNamedOptions<TOptions> and IConfigureOptions<TOptions> and only calls the appropriate interface.

IOptionsMonitorCache<TOptions> est utilisée par IOptionsMonitor<TOptions> pour mettre en cache les instances TOptions.IOptionsMonitorCache<TOptions> is used by IOptionsMonitor<TOptions> to cache TOptions instances. IOptionsMonitorCache<TOptions> invalide les instances des options dans le moniteur afin que la valeur soit recalculée (TryRemove).The IOptionsMonitorCache<TOptions> invalidates options instances in the monitor so that the value is recomputed (TryRemove). Les valeurs peuvent aussi être introduites manuellement avec TryAdd.Values can be manually introduced with TryAdd. La méthode Clear est utilisée quand toutes les instances nommées doivent être recréées à la demande.The Clear method is used when all named instances should be recreated on demand.

IOptionsSnapshot<TOptions> est utile dans les scénarios où des options doivent être recalculées à chaque requête.IOptionsSnapshot<TOptions> is useful in scenarios where options should be recomputed on every request. Pour plus d’informations, consultez la section Recharger les données de configuration avec IOptionsSnapshot.For more information, see the Reload configuration data with IOptionsSnapshot section.

IOptions<TOptions> peut être utilisée pour prendre en charge des options.IOptions<TOptions> can be used to support options. Toutefois, IOptions<TOptions> ne prend pas en charge les scénarios IOptionsMonitor<TOptions> précédents.However, IOptions<TOptions> doesn't support the preceding scenarios of IOptionsMonitor<TOptions>. Vous pouvez continuer à utiliser IOptions<TOptions> dans des infrastructures et bibliothèques existantes qui utilisent déjà l’interface IOptions<TOptions> mais ne nécessitent pas les scénarios fournis par IOptionsMonitor<TOptions>.You may continue to use IOptions<TOptions> in existing frameworks and libraries that already use the IOptions<TOptions> interface and don't require the scenarios provided by IOptionsMonitor<TOptions>.

Configuration des options généralesGeneral options configuration

La configuration des options générales est illustrée dans l’exemple #1 de l’exemple d’application.General options configuration is demonstrated as Example #1 in the sample app.

Une classe d’options doit être non abstraite avec un constructeur public sans paramètre.An options class must be non-abstract with a public parameterless constructor. La classe suivante, MyOptions, a deux propriétés : Option1 et Option2.The following class, MyOptions, has two properties, Option1 and Option2. Définir des valeurs par défaut est facultatif, mais le constructeur de classe dans l’exemple suivant définit la valeur par défaut Option1.Setting default values is optional, but the class constructor in the following example sets the default value of Option1. Option2 a une valeur par défaut définie par l’initialisation directe de la propriété (Models/MyOptions.cs) :Option2 has a default value set by initializing the property directly (Models/MyOptions.cs):

public class MyOptions
{
    public MyOptions()
    {
        // Set default value.
        Option1 = "value1_from_ctor";
    }
    
    public string Option1 { get; set; }
    public int Option2 { get; set; } = 5;
}

La classe MyOptions est ajoutée au conteneur de service avec Configure et liée à la configuration :The MyOptions class is added to the service container with Configure and bound to configuration:

// Example #1: General configuration
// Register the Configuration instance which MyOptions binds against.
services.Configure<MyOptions>(Configuration);

Le modèle de page suivant utilise une injection de dépendances de constructeur avec IOptionsMonitor<TOptions> pour accéder aux paramètres (Pages/Index.cshtml.cs) :The following page model uses constructor dependency injection with IOptionsMonitor<TOptions> to access the settings (Pages/Index.cshtml.cs):

private readonly MyOptions _options;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #1: Simple options
var option1 = _options.Option1;
var option2 = _options.Option2;
SimpleOptions = $"option1 = {option1}, option2 = {option2}";

Le fichier appsettings.json de l’exemple spécifie des valeurs pour option1 et option2 :The sample's appsettings.json file specifies values for option1 and option2:

{
  "option1": "value1_from_json",
  "option2": -1,
  "subsection": {
    "suboption1": "subvalue1_from_json",
    "suboption2": 200
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Quand l’application est exécutée, la méthode OnGet du modèle de page retourne une chaîne indiquant les valeurs de la classe d’options :When the app is run, the page model's OnGet method returns a string showing the option class values:

option1 = value1_from_json, option2 = -1

Notes

Quand vous utilisez un ConfigurationBuilder personnalisé pour charger une configuration d’options à partir d’un fichier de paramètres, vérifiez que le chemin de base est correctement défini :When using a custom ConfigurationBuilder to load options configuration from a settings file, confirm that the base path is set correctly:

var configBuilder = new ConfigurationBuilder()
   .SetBasePath(Directory.GetCurrentDirectory())
   .AddJsonFile("appsettings.json", optional: true);
var config = configBuilder.Build();

services.Configure<MyOptions>(config);

Vous n’avez pas besoin de définir explicitement le chemin de base quand vous chargez une configuration d’options à partir du fichier de paramètres via CreateDefaultBuilder.Explicitly setting the base path isn't required when loading options configuration from the settings file via CreateDefaultBuilder.

Configurer des options simples avec un déléguéConfigure simple options with a delegate

La configuration d’options simples avec un délégué est illustrée dans l’exemple #2 de l’exemple d’application.Configuring simple options with a delegate is demonstrated as Example #2 in the sample app.

Utilisez un délégué pour définir les valeurs des options.Use a delegate to set options values. L’exemple d’application utilise la classe MyOptionsWithDelegateConfig (Models/MyOptionsWithDelegateConfig.cs) :The sample app uses the MyOptionsWithDelegateConfig class (Models/MyOptionsWithDelegateConfig.cs):

public class MyOptionsWithDelegateConfig
{
    public MyOptionsWithDelegateConfig()
    {
        // Set default value.
        Option1 = "value1_from_ctor";
    }
    
    public string Option1 { get; set; }
    public int Option2 { get; set; } = 5;
}

Dans le code suivant, un second service IConfigureOptions<TOptions> est ajouté au conteneur de services.In the following code, a second IConfigureOptions<TOptions> service is added to the service container. Il utilise un délégué pour configurer la liaison avec MyOptionsWithDelegateConfig :It uses a delegate to configure the binding with MyOptionsWithDelegateConfig:

// Example #2: Options bound and configured by a delegate
services.Configure<MyOptionsWithDelegateConfig>(myOptions =>
{
    myOptions.Option1 = "value1_configured_by_delegate";
    myOptions.Option2 = 500;
});

Index.cshtml.cs :Index.cshtml.cs:

private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #2: Options configured by delegate
var delegate_config_option1 = _optionsWithDelegateConfig.Option1;
var delegate_config_option2 = _optionsWithDelegateConfig.Option2;
SimpleOptionsWithDelegateConfig = 
    $"delegate_option1 = {delegate_config_option1}, " +
    $"delegate_option2 = {delegate_config_option2}";

Vous pouvez ajouter plusieurs fournisseurs de configuration.You can add multiple configuration providers. Des fournisseurs de configuration sont disponibles à partir de packages NuGet et sont appliqués dans l’ordre de leur inscription.Configuration providers are available from NuGet packages and are applied in the order that they're registered. Pour plus d’informations, consultez Configuration dans ASP.NET Core.For more information, see Configuration dans ASP.NET Core.

Chaque appel à Configure ajoute un service IConfigureOptions<TOptions> au conteneur de services.Each call to Configure adds an IConfigureOptions<TOptions> service to the service container. Dans l’exemple précédent, les valeurs de Option1 et Option2 sont toutes deux spécifiées dans appsettings.json, mais les valeurs de Option1 et Option2 sont remplacées par le délégué configuré.In the preceding example, the values of Option1 and Option2 are both specified in appsettings.json, but the values of Option1 and Option2 are overridden by the configured delegate.

Quand plusieurs services de configuration sont activés, la dernière source de configuration spécifiée gagne et définit la valeur de configuration.When more than one configuration service is enabled, the last configuration source specified wins and sets the configuration value. Quand l’application est exécutée, la méthode OnGet du modèle de page retourne une chaîne indiquant les valeurs de la classe d’options :When the app is run, the page model's OnGet method returns a string showing the option class values:

delegate_option1 = value1_configured_by_delegate, delegate_option2 = 500

Configuration des sous-optionsSuboptions configuration

La configuration des sous-options est illustrée dans l’exemple #3 de l’exemple d’application.Suboptions configuration is demonstrated as Example #3 in the sample app.

Les applications doivent créer des classes d’options qui appartiennent à des groupes de scénarios spécifiques (classes) dans l’application.Apps should create options classes that pertain to specific scenario groups (classes) in the app. Les parties de l’application qui requièrent des valeurs de configuration ne doivent avoir accès qu’aux valeurs de configuration qu’elles utilisent.Parts of the app that require configuration values should only have access to the configuration values that they use.

Au moment de la liaison des options à la configuration, chaque propriété du type options est liée à une clé de configuration sous la forme property[:sub-property:].When binding options to configuration, each property in the options type is bound to a configuration key of the form property[:sub-property:]. Par exemple, la propriété MyOptions.Option1 est liée à la clé Option1, qui est lue à partir de la propriété option1 dans appsettings.json.For example, the MyOptions.Option1 property is bound to the key Option1, which is read from the option1 property in appsettings.json.

Dans le code suivant, un troisième service IConfigureOptions<TOptions> est ajouté au conteneur de services.In the following code, a third IConfigureOptions<TOptions> service is added to the service container. Il lie MySubOptions à la section subsection du fichier appsettings.json :It binds MySubOptions to the section subsection of the appsettings.json file:

// Example #3: Suboptions
// Bind options using a sub-section of the appsettings.json file.
services.Configure<MySubOptions>(Configuration.GetSection("subsection"));

La méthode d’extension GetSection requiert le package NuGet Microsoft.Extensions.Options.ConfigurationExtensions.The GetSection extension method requires the Microsoft.Extensions.Options.ConfigurationExtensions NuGet package. Si l’application utilise le métapaquet Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou version ultérieure), le package est automatiquement inclus.If the app uses the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later), the package is automatically included.

Le fichier appsettings.json de l’exemple définit un membre subsection avec des clés pour suboption1 et suboption2 :The sample's appsettings.json file defines a subsection member with keys for suboption1 and suboption2:

{
  "option1": "value1_from_json",
  "option2": -1,
  "subsection": {
    "suboption1": "subvalue1_from_json",
    "suboption2": 200
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

La classe MySubOptions définit des propriétés, SubOption1 et SubOption2, pour conserver les valeurs des options (Models/MySubOptions.cs) :The MySubOptions class defines properties, SubOption1 and SubOption2, to hold the options values (Models/MySubOptions.cs):

public class MySubOptions
{
    public MySubOptions()
    {
        // Set default values.
        SubOption1 = "value1_from_ctor";
        SubOption2 = 5;
    }
    
    public string SubOption1 { get; set; }
    public int SubOption2 { get; set; }
}

La méthode OnGet du modèle de page retourne une chaîne avec les valeurs des options (Pages/Index.cshtml.cs) :The page model's OnGet method returns a string with the options values (Pages/Index.cshtml.cs):

private readonly MySubOptions _subOptions;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #3: Suboptions
var subOption1 = _subOptions.SubOption1;
var subOption2 = _subOptions.SubOption2;
SubOptions = $"subOption1 = {subOption1}, subOption2 = {subOption2}";

Quand l’application est exécutée, la méthode OnGet retourne une chaîne indiquant les valeurs de la classe de sous-options :When the app is run, the OnGet method returns a string showing the suboption class values:

subOption1 = subvalue1_from_json, subOption2 = 200

Options fournies par un modèle d’affichage ou avec une injection de vue directeOptions provided by a view model or with direct view injection

Les options fournies par un modèle d’affichage ou avec une injection de vue directe sont illustrées dans l’exemple #4 de l’exemple d’application.Options provided by a view model or with direct view injection is demonstrated as Example #4 in the sample app.

Vous pouvez fournir les options dans un modèle d’affichage ou en injectant IOptionsMonitor<TOptions> directement dans une vue (Pages/Index.cshtml.cs) :Options can be supplied in a view model or by injecting IOptionsMonitor<TOptions> directly into a view (Pages/Index.cshtml.cs):

private readonly MyOptions _options;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #4: Bind options directly to the page
MyOptions = _options;

L’exemple d’application montre comment injecter IOptionsMonitor<MyOptions> avec une directive @inject :The sample app shows how to inject IOptionsMonitor<MyOptions> with an @inject directive:

@page
@model IndexModel
@using Microsoft.Extensions.Options
@inject IOptionsMonitor<MyOptions> OptionsAccessor
@{
    ViewData["Title"] = "Options Sample";
}

<h1>@ViewData["Title"]</h1>

Quand l’application est exécutée, les valeurs d’options sont affichées dans la page rendue :When the app is run, the options values are shown in the rendered page:

Les valeurs d’options Option1: value1_from_json et Option2: -1 sont chargées à partir du modèle et par injection dans la vue.

Recharger les données de configuration avec IOptionsSnapshotReload configuration data with IOptionsSnapshot

Le rechargement des données de configuration avec IOptionsSnapshot<TOptions> est illustré dans l’exemple #5 de l’exemple d’application.Reloading configuration data with IOptionsSnapshot<TOptions> is demonstrated in Example #5 in the sample app.

IOptionsSnapshot<TOptions> prend en charge le rechargement des options avec une charge de traitement minimale.IOptionsSnapshot<TOptions> supports reloading options with minimal processing overhead.

Les options sont calculées une fois par requête quand le système y accède et sont mises en cache pour toute la durée de vie de la requête.Options are computed once per request when accessed and cached for the lifetime of the request.

Dans l’exemple suivant, un IOptionsSnapshot<TOptions> est créé à la suite de la modification du fichier appsettings.json (Pages/Index.cshtml.cs).The following example demonstrates how a new IOptionsSnapshot<TOptions> is created after appsettings.json changes (Pages/Index.cshtml.cs). Plusieurs demandes adressées au serveur retournent des valeurs constantes fournies par le fichier appsettings.json tant que ce dernier n’est pas changé et que la configuration n’est pas rechargée.Multiple requests to the server return constant values provided by the appsettings.json file until the file is changed and configuration reloads.

private readonly MyOptions _snapshotOptions;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #5: Snapshot options
var snapshotOption1 = _snapshotOptions.Option1;
var snapshotOption2 = _snapshotOptions.Option2;
SnapshotOptions = 
    $"snapshot option1 = {snapshotOption1}, " +
    $"snapshot option2 = {snapshotOption2}";

L’image suivante montre les valeurs option1 et option2 initiales chargées à partir du fichier appsettings.json :The following image shows the initial option1 and option2 values loaded from the appsettings.json file:

snapshot option1 = value1_from_json, snapshot option2 = -1

Changez les valeurs dans le fichier appsettings.json en value1_from_json UPDATED et 200.Change the values in the appsettings.json file to value1_from_json UPDATED and 200. Enregistrez le fichier appsettings.json.Save the appsettings.json file. Actualisez le navigateur pour constater la mise à jour des valeurs des options :Refresh the browser to see that the options values are updated:

snapshot option1 = value1_from_json UPDATED, snapshot option2 = 200

Prise en charge des options nommées avec IConfigureNamedOptionsNamed options support with IConfigureNamedOptions

La prise en charge des options nommées avec IConfigureNamedOptions<TOptions> est illustrée dans l’exemple #6 de l’exemple d’application.Named options support with IConfigureNamedOptions<TOptions> is demonstrated as Example #6 in the sample app.

La prise en charge des options nommées permet à l’application de faire la distinction entre les configurations d’options nommées.Named options support allows the app to distinguish between named options configurations. Dans l’exemple d’application, les options nommées sont déclarées avec OptionsServiceCollectionExtensions.Configure, qui appelle la méthode d’extension ConfigureNamedOptions<TOptions>.Configure :In the sample app, named options are declared with OptionsServiceCollectionExtensions.Configure, which calls the ConfigureNamedOptions<TOptions>.Configure extension method:

// Example #6: Named options (named_options_1)
// Register the ConfigurationBuilder instance which MyOptions binds against.
// Specify that the options loaded from configuration are named
// "named_options_1".
services.Configure<MyOptions>("named_options_1", Configuration);

// Example #6: Named options (named_options_2)
// Specify that the options loaded from the MyOptions class are named
// "named_options_2".
// Use a delegate to configure option values.
services.Configure<MyOptions>("named_options_2", myOptions =>
{
    myOptions.Option1 = "named_options_2_value1_from_action";
});

L’exemple d’application accède aux options nommées avec Get (Pages/Index.cshtml.cs) :The sample app accesses the named options with Get (Pages/Index.cshtml.cs):

private readonly MyOptions _named_options_1;
private readonly MyOptions _named_options_2;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #6: Named options
var named_options_1 = 
    $"named_options_1: option1 = {_named_options_1.Option1}, " +
    $"option2 = {_named_options_1.Option2}";
var named_options_2 = 
    $"named_options_2: option1 = {_named_options_2.Option1}, " +
    $"option2 = {_named_options_2.Option2}";
NamedOptions = $"{named_options_1} {named_options_2}";

Quand l’exemple d’application est exécuté, les options nommées sont retournées :Running the sample app, the named options are returned:

named_options_1: option1 = value1_from_json, option2 = -1
named_options_2: option1 = named_options_2_value1_from_action, option2 = 5

Les valeurs named_options_1, issues de la configuration, sont chargées à partir du fichier appsettings.json.named_options_1 values are provided from configuration, which are loaded from the appsettings.json file. Les valeurs named_options_2 sont fournies par :named_options_2 values are provided by:

  • Le délégué named_options_2 dans ConfigureServices pour Option1.The named_options_2 delegate in ConfigureServices for Option1.
  • La valeur par défaut Option2 fournie par la classe MyOptions.The default value for Option2 provided by the MyOptions class.

Configurer toutes les options avec la méthode ConfigureAllConfigure all options with the ConfigureAll method

Configurez toutes les instances d’options avec la méthode ConfigureAll.Configure all options instances with the ConfigureAll method. Le code suivant configure Option1 pour toutes les instances de configuration ayant une valeur commune.The following code configures Option1 for all configuration instances with a common value. Ajoutez le code suivant manuellement à la méthode Startup.ConfigureServices :Add the following code manually to the Startup.ConfigureServices method:

services.ConfigureAll<MyOptions>(myOptions => 
{
    myOptions.Option1 = "ConfigureAll replacement value";
});

Exécuter l’exemple d’application après avoir ajouté le code produit le résultat suivant :Running the sample app after adding the code produces the following result:

named_options_1: option1 = ConfigureAll replacement value, option2 = -1
named_options_2: option1 = ConfigureAll replacement value, option2 = 5

Notes

Toutes les options sont des instances nommées.All options are named instances. Les instances IConfigureOptions<TOptions> existantes sont traitées comme ciblant l’instance Options.DefaultName, qui est string.Empty.Existing IConfigureOptions<TOptions> instances are treated as targeting the Options.DefaultName instance, which is string.Empty. En outre, IConfigureNamedOptions<TOptions> implémente IConfigureOptions<TOptions>.IConfigureNamedOptions<TOptions> also implements IConfigureOptions<TOptions>. L’implémentation par défaut de IOptionsFactory<TOptions> possède une logique qui utilise chaque élément de manière appropriée.The default implementation of the IOptionsFactory<TOptions> has logic to use each appropriately. L’option nommée null est utilisée pour cibler toutes les instances nommées au lieu d’une instance nommée spécifique (ConfigureAll et PostConfigureAll utilisent cette convention).The null named option is used to target all of the named instances instead of a specific named instance (ConfigureAll and PostConfigureAll use this convention).

API OptionsBuilderOptionsBuilder API

OptionsBuilder<TOptions> permet de configurer des instances TOptions.OptionsBuilder<TOptions> is used to configure TOptions instances. OptionsBuilder simplifie la création d’options nommées. En effet, il est le seul paramètre de l’appel AddOptions<TOptions>(string optionsName) initial et n’apparaît pas dans les appels ultérieurs.OptionsBuilder streamlines creating named options as it's only a single parameter to the initial AddOptions<TOptions>(string optionsName) call instead of appearing in all of the subsequent calls. La validation des options et les surcharges ConfigureOptions qui acceptent des dépendances de service sont uniquement disponibles avec OptionsBuilder.Options validation and the ConfigureOptions overloads that accept service dependencies are only available via OptionsBuilder.

// Options.DefaultName = "" is used.
services.AddOptions<MyOptions>().Configure(o => o.Property = "default");

services.AddOptions<MyOptions>("optionalName")
    .Configure(o => o.Property = "named");

Utiliser les services d’injection de dépendances (DI) pour configurer des optionsUse DI services to configure options

Vous pouvez accéder à d’autres services à partir de l’injection de dépendances pendant que vous configurez des options de deux manières différentes :You can access other services from dependency injection while configuring options in two ways:

Nous vous recommandons de transmettre un délégué de configuration à Configure, car il est plus complexe de créer un service.We recommend passing a configuration delegate to Configure, since creating a service is more complex. Créer votre propre type équivaut à ce que fait automatiquement le framework quand vous utilisez Configure.Creating your own type is equivalent to what the framework does for you when you use Configure. L’appel de Configure a pour effet d’inscrire une instance générique temporaire de IConfigureNamedOptions<TOptions>, dont l’un des constructeurs accepte les types de service génériques spécifiés.Calling Configure registers a transient generic IConfigureNamedOptions<TOptions>, which has a constructor that accepts the generic service types specified.

Validation des optionsOptions validation

La validation des options vous permet de valider les options lorsque celles-ci sont configurées.Options validation allows you to validate options when options are configured. Appelez Validate avec une méthode de validation qui retourne true si les options sont valides et false si elles ne sont pas valides :Call Validate with a validation method that returns true if options are valid and false if they aren't valid:

// Registration
services.AddOptions<MyOptions>("optionalOptionsName")
    .Configure(o => { }) // Configure the options
    .Validate(o => YourValidationShouldReturnTrueIfValid(o), 
        "custom error");

// Consumption
var monitor = services.BuildServiceProvider()
    .GetService<IOptionsMonitor<MyOptions>>();

try
{
    var options = monitor.Get("optionalOptionsName");
}
catch (OptionsValidationException e) 
{
   // e.OptionsName returns "optionalOptionsName"
   // e.OptionsType returns typeof(MyOptions)
   // e.Failures returns a list of errors, which would contain 
   //     "custom error"
}

L’exemple précédent définit l’instance d’options nommée sur optionalOptionsName.The preceding example sets the named options instance to optionalOptionsName. L'instance d’options par défaut est Options.DefaultName.The default options instance is Options.DefaultName.

La validation s’exécute lorsque l’instance d’options est créée.Validation runs when the options instance is created. Votre instance d’options est garantie de réussir la validation lors du premier accès.Your options instance is guaranteed to pass validation the first time it's accessed.

Important

La validation des options ne protège pas contre les modifications des options une fois que les options sont initialement configurées et validées.Options validation doesn't guard against options modifications after the options are initially configured and validated.

La méthode Validate accepte un Func<TOptions, bool>.The Validate method accepts a Func<TOptions, bool>. Pour personnaliser entièrement la validation, implémentez IValidateOptions<TOptions>, ce qui permet :To fully customize validation, implement IValidateOptions<TOptions>, which allows:

  • Validation de plusieurs types d’options : class ValidateTwo : IValidateOptions<Option1>, IValidationOptions<Option2>Validation of multiple options types: class ValidateTwo : IValidateOptions<Option1>, IValidationOptions<Option2>
  • Validation qui dépend d’un autre type d’option : public DependsOnAnotherOptionValidator(IOptionsMonitor<AnotherOption> options)Validation that depends on another option type: public DependsOnAnotherOptionValidator(IOptionsMonitor<AnotherOption> options)

IValidateOptions valide :IValidateOptions validates:

  • Une instance d’options nommée spécifique.A specific named options instance.
  • Toutes les options quand name est null.All options when name is null.

Retourne ValidateOptionsResult à partir de votre implémentation de l’interface :Return a ValidateOptionsResult from your implementation of the interface:

public interface IValidateOptions<TOptions> where TOptions : class
{
    ValidateOptionsResult Validate(string name, TOptions options);
}

La validation basée sur l’annotation de données est disponible dans le package Microsoft.Extensions.Options.DataAnnotations. Pour cela, appelez la méthode ValidateDataAnnotations sur OptionsBuilder<TOptions>.Data Annotation-based validation is available from the Microsoft.Extensions.Options.DataAnnotations package by calling the ValidateDataAnnotations method on OptionsBuilder<TOptions>. Microsoft.Extensions.Options.DataAnnotations est inclus dans le métapaquet Microsoft.AspNetCore.App (ASP.NET Core 2.2 ou ultérieur).Microsoft.Extensions.Options.DataAnnotations is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.2 or later).

using Microsoft.Extensions.DependencyInjection;

private class AnnotatedOptions
{
    [Required]
    public string Required { get; set; }

    [StringLength(5, ErrorMessage = "Too long.")]
    public string StringLength { get; set; }

    [Range(-5, 5, ErrorMessage = "Out of range.")]
    public int IntRange { get; set; }
}

[Fact]
public void CanValidateDataAnnotations()
{
    var services = new ServiceCollection();
    services.AddOptions<AnnotatedOptions>()
        .Configure(o =>
        {
            o.StringLength = "111111";
            o.IntRange = 10;
            o.Custom = "nowhere";
        })
        .ValidateDataAnnotations();

    var sp = services.BuildServiceProvider();

    var error = Assert.Throws<OptionsValidationException>(() => 
        sp.GetRequiredService<IOptionsMonitor<AnnotatedOptions>>().Value);
    ValidateFailure<AnnotatedOptions>(error, Options.DefaultName, 1,
        "DataAnnotation validation failed for members Required " +
            "with the error 'The Required field is required.'.",
        "DataAnnotation validation failed for members StringLength " +
            "with the error 'Too long.'.",
        "DataAnnotation validation failed for members IntRange " +
            "with the error 'Out of range.'.");
}

La validation hâtive (échec rapide au démarrage) est à l’étude pour une version ultérieure.Eager validation (fail fast at startup) is under consideration for a future release.

Options de post-configurationOptions post-configuration

Définissez la post-configuration avec IPostConfigureOptions<TOptions>.Set post-configuration with IPostConfigureOptions<TOptions>. La post-configuration s’exécute après chaque configuration de IConfigureOptions<TOptions> :Post-configuration runs after all IConfigureOptions<TOptions> configuration occurs:

services.PostConfigure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

PostConfigure permet de post-configurer les options nommées :PostConfigure is available to post-configure named options:

services.PostConfigure<MyOptions>("named_options_1", myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

Utilisez PostConfigureAll pour post-configurer toutes les instances de configuration :Use PostConfigureAll to post-configure all configuration instances:

services.PostConfigureAll<MyOptions>(myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

Accès aux options au démarrageAccessing options during startup

IOptions<TOptions> et IOptionsMonitor<TOptions> peuvent être utilisées dans Startup.Configure, dans la mesure où les services sont générés avant que la méthode Configure ne s’exécute.IOptions<TOptions> and IOptionsMonitor<TOptions> can be used in Startup.Configure, since services are built before the Configure method executes.

public void Configure(IApplicationBuilder app, IOptionsMonitor<MyOptions> optionsAccessor)
{
    var option1 = optionsAccessor.CurrentValue.Option1;
}

N’utilisez pas IOptions<TOptions> ou IOptionsMonitor<TOptions> dans Startup.ConfigureServices.Don't use IOptions<TOptions> or IOptionsMonitor<TOptions> in Startup.ConfigureServices. Un état d’options incohérent peut exister en raison de l’ordre des inscriptions de service.An inconsistent options state may exist due to the ordering of service registrations.

Le modèle d’options utilise des classes pour représenter les groupes de paramètres associés.The options pattern uses classes to represent groups of related settings. Quand les paramètres de configuration sont isolés par scénario dans des classes distinctes, l’application est conforme à deux principes d’ingénierie logicielle importants :When configuration settings are isolated by scenario into separate classes, the app adheres to two important software engineering principles:

Ces options fournissent également un mécanisme de validation des données de configuration.Options also provide a mechanism to validate configuration data. Pour plus d'informations, reportez-vous à la section Validation des options.For more information, see the Options validation section.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

PrérequisPrerequisites

Référencer le métapackage Microsoft.AspNetCore.App ou ajouter une référence de package au package Microsoft.Extensions.Options.ConfigurationExtensions.Reference the Microsoft.AspNetCore.App metapackage or add a package reference to the Microsoft.Extensions.Options.ConfigurationExtensions package.

Interfaces d’optionsOptions interfaces

IOptionsMonitor<TOptions> permet de récupérer des options et de gérer les notifications d’options pour les instances TOptions.IOptionsMonitor<TOptions> is used to retrieve options and manage options notifications for TOptions instances. IOptionsMonitor<TOptions> prend en charge les scénarios suivants :IOptionsMonitor<TOptions> supports the following scenarios:

Des scénarios post-configuration vous permettent de définir ou de modifier les options après chaque configuration de IConfigureOptions<TOptions>.Post-configuration scenarios allow you to set or change options after all IConfigureOptions<TOptions> configuration occurs.

IOptionsFactory<TOptions> est chargée de créer les instances d’options.IOptionsFactory<TOptions> is responsible for creating new options instances. Elle dispose d’une seule méthode Create.It has a single Create method. L’implémentation par défaut prend toutes les IConfigureOptions<TOptions> et IPostConfigureOptions<TOptions> inscrites et exécute toutes les configurations, puis les post-configurations.The default implementation takes all registered IConfigureOptions<TOptions> and IPostConfigureOptions<TOptions> and runs all the configurations first, followed by the post-configuration. Elle fait la distinction entre IConfigureNamedOptions<TOptions> et IConfigureOptions<TOptions> et n’appelle que l’interface appropriée.It distinguishes between IConfigureNamedOptions<TOptions> and IConfigureOptions<TOptions> and only calls the appropriate interface.

IOptionsMonitorCache<TOptions> est utilisée par IOptionsMonitor<TOptions> pour mettre en cache les instances TOptions.IOptionsMonitorCache<TOptions> is used by IOptionsMonitor<TOptions> to cache TOptions instances. IOptionsMonitorCache<TOptions> invalide les instances des options dans le moniteur afin que la valeur soit recalculée (TryRemove).The IOptionsMonitorCache<TOptions> invalidates options instances in the monitor so that the value is recomputed (TryRemove). Les valeurs peuvent aussi être introduites manuellement avec TryAdd.Values can be manually introduced with TryAdd. La méthode Clear est utilisée quand toutes les instances nommées doivent être recréées à la demande.The Clear method is used when all named instances should be recreated on demand.

IOptionsSnapshot<TOptions> est utile dans les scénarios où des options doivent être recalculées à chaque requête.IOptionsSnapshot<TOptions> is useful in scenarios where options should be recomputed on every request. Pour plus d’informations, consultez la section Recharger les données de configuration avec IOptionsSnapshot.For more information, see the Reload configuration data with IOptionsSnapshot section.

IOptions<TOptions> peut être utilisée pour prendre en charge des options.IOptions<TOptions> can be used to support options. Toutefois, IOptions<TOptions> ne prend pas en charge les scénarios IOptionsMonitor<TOptions> précédents.However, IOptions<TOptions> doesn't support the preceding scenarios of IOptionsMonitor<TOptions>. Vous pouvez continuer à utiliser IOptions<TOptions> dans des infrastructures et bibliothèques existantes qui utilisent déjà l’interface IOptions<TOptions> mais ne nécessitent pas les scénarios fournis par IOptionsMonitor<TOptions>.You may continue to use IOptions<TOptions> in existing frameworks and libraries that already use the IOptions<TOptions> interface and don't require the scenarios provided by IOptionsMonitor<TOptions>.

Configuration des options généralesGeneral options configuration

La configuration des options générales est illustrée dans l’exemple #1 de l’exemple d’application.General options configuration is demonstrated as Example #1 in the sample app.

Une classe d’options doit être non abstraite avec un constructeur public sans paramètre.An options class must be non-abstract with a public parameterless constructor. La classe suivante, MyOptions, a deux propriétés : Option1 et Option2.The following class, MyOptions, has two properties, Option1 and Option2. Définir des valeurs par défaut est facultatif, mais le constructeur de classe dans l’exemple suivant définit la valeur par défaut Option1.Setting default values is optional, but the class constructor in the following example sets the default value of Option1. Option2 a une valeur par défaut définie par l’initialisation directe de la propriété (Models/MyOptions.cs) :Option2 has a default value set by initializing the property directly (Models/MyOptions.cs):

public class MyOptions
{
    public MyOptions()
    {
        // Set default value.
        Option1 = "value1_from_ctor";
    }
    
    public string Option1 { get; set; }
    public int Option2 { get; set; } = 5;
}

La classe MyOptions est ajoutée au conteneur de service avec Configure et liée à la configuration :The MyOptions class is added to the service container with Configure and bound to configuration:

// Example #1: General configuration
// Register the Configuration instance which MyOptions binds against.
services.Configure<MyOptions>(Configuration);

Le modèle de page suivant utilise une injection de dépendances de constructeur avec IOptionsMonitor<TOptions> pour accéder aux paramètres (Pages/Index.cshtml.cs) :The following page model uses constructor dependency injection with IOptionsMonitor<TOptions> to access the settings (Pages/Index.cshtml.cs):

private readonly MyOptions _options;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #1: Simple options
var option1 = _options.Option1;
var option2 = _options.Option2;
SimpleOptions = $"option1 = {option1}, option2 = {option2}";

Le fichier appsettings.json de l’exemple spécifie des valeurs pour option1 et option2 :The sample's appsettings.json file specifies values for option1 and option2:

{
  "option1": "value1_from_json",
  "option2": -1,
  "subsection": {
    "suboption1": "subvalue1_from_json",
    "suboption2": 200
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Quand l’application est exécutée, la méthode OnGet du modèle de page retourne une chaîne indiquant les valeurs de la classe d’options :When the app is run, the page model's OnGet method returns a string showing the option class values:

option1 = value1_from_json, option2 = -1

Notes

Quand vous utilisez un ConfigurationBuilder personnalisé pour charger une configuration d’options à partir d’un fichier de paramètres, vérifiez que le chemin de base est correctement défini :When using a custom ConfigurationBuilder to load options configuration from a settings file, confirm that the base path is set correctly:

var configBuilder = new ConfigurationBuilder()
   .SetBasePath(Directory.GetCurrentDirectory())
   .AddJsonFile("appsettings.json", optional: true);
var config = configBuilder.Build();

services.Configure<MyOptions>(config);

Vous n’avez pas besoin de définir explicitement le chemin de base quand vous chargez une configuration d’options à partir du fichier de paramètres via CreateDefaultBuilder.Explicitly setting the base path isn't required when loading options configuration from the settings file via CreateDefaultBuilder.

Configurer des options simples avec un déléguéConfigure simple options with a delegate

La configuration d’options simples avec un délégué est illustrée dans l’exemple #2 de l’exemple d’application.Configuring simple options with a delegate is demonstrated as Example #2 in the sample app.

Utilisez un délégué pour définir les valeurs des options.Use a delegate to set options values. L’exemple d’application utilise la classe MyOptionsWithDelegateConfig (Models/MyOptionsWithDelegateConfig.cs) :The sample app uses the MyOptionsWithDelegateConfig class (Models/MyOptionsWithDelegateConfig.cs):

public class MyOptionsWithDelegateConfig
{
    public MyOptionsWithDelegateConfig()
    {
        // Set default value.
        Option1 = "value1_from_ctor";
    }
    
    public string Option1 { get; set; }
    public int Option2 { get; set; } = 5;
}

Dans le code suivant, un second service IConfigureOptions<TOptions> est ajouté au conteneur de services.In the following code, a second IConfigureOptions<TOptions> service is added to the service container. Il utilise un délégué pour configurer la liaison avec MyOptionsWithDelegateConfig :It uses a delegate to configure the binding with MyOptionsWithDelegateConfig:

// Example #2: Options bound and configured by a delegate
services.Configure<MyOptionsWithDelegateConfig>(myOptions =>
{
    myOptions.Option1 = "value1_configured_by_delegate";
    myOptions.Option2 = 500;
});

Index.cshtml.cs :Index.cshtml.cs:

private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #2: Options configured by delegate
var delegate_config_option1 = _optionsWithDelegateConfig.Option1;
var delegate_config_option2 = _optionsWithDelegateConfig.Option2;
SimpleOptionsWithDelegateConfig = 
    $"delegate_option1 = {delegate_config_option1}, " +
    $"delegate_option2 = {delegate_config_option2}";

Vous pouvez ajouter plusieurs fournisseurs de configuration.You can add multiple configuration providers. Des fournisseurs de configuration sont disponibles à partir de packages NuGet et sont appliqués dans l’ordre de leur inscription.Configuration providers are available from NuGet packages and are applied in the order that they're registered. Pour plus d’informations, consultez Configuration dans ASP.NET Core.For more information, see Configuration dans ASP.NET Core.

Chaque appel à Configure ajoute un service IConfigureOptions<TOptions> au conteneur de services.Each call to Configure adds an IConfigureOptions<TOptions> service to the service container. Dans l’exemple précédent, les valeurs de Option1 et Option2 sont toutes deux spécifiées dans appsettings.json, mais les valeurs de Option1 et Option2 sont remplacées par le délégué configuré.In the preceding example, the values of Option1 and Option2 are both specified in appsettings.json, but the values of Option1 and Option2 are overridden by the configured delegate.

Quand plusieurs services de configuration sont activés, la dernière source de configuration spécifiée gagne et définit la valeur de configuration.When more than one configuration service is enabled, the last configuration source specified wins and sets the configuration value. Quand l’application est exécutée, la méthode OnGet du modèle de page retourne une chaîne indiquant les valeurs de la classe d’options :When the app is run, the page model's OnGet method returns a string showing the option class values:

delegate_option1 = value1_configured_by_delegate, delegate_option2 = 500

Configuration des sous-optionsSuboptions configuration

La configuration des sous-options est illustrée dans l’exemple #3 de l’exemple d’application.Suboptions configuration is demonstrated as Example #3 in the sample app.

Les applications doivent créer des classes d’options qui appartiennent à des groupes de scénarios spécifiques (classes) dans l’application.Apps should create options classes that pertain to specific scenario groups (classes) in the app. Les parties de l’application qui requièrent des valeurs de configuration ne doivent avoir accès qu’aux valeurs de configuration qu’elles utilisent.Parts of the app that require configuration values should only have access to the configuration values that they use.

Au moment de la liaison des options à la configuration, chaque propriété du type options est liée à une clé de configuration sous la forme property[:sub-property:].When binding options to configuration, each property in the options type is bound to a configuration key of the form property[:sub-property:]. Par exemple, la propriété MyOptions.Option1 est liée à la clé Option1, qui est lue à partir de la propriété option1 dans appsettings.json.For example, the MyOptions.Option1 property is bound to the key Option1, which is read from the option1 property in appsettings.json.

Dans le code suivant, un troisième service IConfigureOptions<TOptions> est ajouté au conteneur de services.In the following code, a third IConfigureOptions<TOptions> service is added to the service container. Il lie MySubOptions à la section subsection du fichier appsettings.json :It binds MySubOptions to the section subsection of the appsettings.json file:

// Example #3: Suboptions
// Bind options using a sub-section of the appsettings.json file.
services.Configure<MySubOptions>(Configuration.GetSection("subsection"));

La méthode d’extension GetSection requiert le package NuGet Microsoft.Extensions.Options.ConfigurationExtensions.The GetSection extension method requires the Microsoft.Extensions.Options.ConfigurationExtensions NuGet package. Si l’application utilise le métapaquet Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou version ultérieure), le package est automatiquement inclus.If the app uses the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later), the package is automatically included.

Le fichier appsettings.json de l’exemple définit un membre subsection avec des clés pour suboption1 et suboption2 :The sample's appsettings.json file defines a subsection member with keys for suboption1 and suboption2:

{
  "option1": "value1_from_json",
  "option2": -1,
  "subsection": {
    "suboption1": "subvalue1_from_json",
    "suboption2": 200
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

La classe MySubOptions définit des propriétés, SubOption1 et SubOption2, pour conserver les valeurs des options (Models/MySubOptions.cs) :The MySubOptions class defines properties, SubOption1 and SubOption2, to hold the options values (Models/MySubOptions.cs):

public class MySubOptions
{
    public MySubOptions()
    {
        // Set default values.
        SubOption1 = "value1_from_ctor";
        SubOption2 = 5;
    }
    
    public string SubOption1 { get; set; }
    public int SubOption2 { get; set; }
}

La méthode OnGet du modèle de page retourne une chaîne avec les valeurs des options (Pages/Index.cshtml.cs) :The page model's OnGet method returns a string with the options values (Pages/Index.cshtml.cs):

private readonly MySubOptions _subOptions;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #3: Suboptions
var subOption1 = _subOptions.SubOption1;
var subOption2 = _subOptions.SubOption2;
SubOptions = $"subOption1 = {subOption1}, subOption2 = {subOption2}";

Quand l’application est exécutée, la méthode OnGet retourne une chaîne indiquant les valeurs de la classe de sous-options :When the app is run, the OnGet method returns a string showing the suboption class values:

subOption1 = subvalue1_from_json, subOption2 = 200

Options fournies par un modèle d’affichage ou avec une injection de vue directeOptions provided by a view model or with direct view injection

Les options fournies par un modèle d’affichage ou avec une injection de vue directe sont illustrées dans l’exemple #4 de l’exemple d’application.Options provided by a view model or with direct view injection is demonstrated as Example #4 in the sample app.

Vous pouvez fournir les options dans un modèle d’affichage ou en injectant IOptionsMonitor<TOptions> directement dans une vue (Pages/Index.cshtml.cs) :Options can be supplied in a view model or by injecting IOptionsMonitor<TOptions> directly into a view (Pages/Index.cshtml.cs):

private readonly MyOptions _options;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #4: Bind options directly to the page
MyOptions = _options;

L’exemple d’application montre comment injecter IOptionsMonitor<MyOptions> avec une directive @inject :The sample app shows how to inject IOptionsMonitor<MyOptions> with an @inject directive:

@page
@model IndexModel
@using Microsoft.Extensions.Options
@inject IOptionsMonitor<MyOptions> OptionsAccessor
@{
    ViewData["Title"] = "Options Sample";
}

<h1>@ViewData["Title"]</h1>

Quand l’application est exécutée, les valeurs d’options sont affichées dans la page rendue :When the app is run, the options values are shown in the rendered page:

Les valeurs d’options Option1: value1_from_json et Option2: -1 sont chargées à partir du modèle et par injection dans la vue.

Recharger les données de configuration avec IOptionsSnapshotReload configuration data with IOptionsSnapshot

Le rechargement des données de configuration avec IOptionsSnapshot<TOptions> est illustré dans l’exemple #5 de l’exemple d’application.Reloading configuration data with IOptionsSnapshot<TOptions> is demonstrated in Example #5 in the sample app.

IOptionsSnapshot<TOptions> prend en charge le rechargement des options avec une charge de traitement minimale.IOptionsSnapshot<TOptions> supports reloading options with minimal processing overhead.

Les options sont calculées une fois par requête quand le système y accède et sont mises en cache pour toute la durée de vie de la requête.Options are computed once per request when accessed and cached for the lifetime of the request.

Dans l’exemple suivant, un IOptionsSnapshot<TOptions> est créé à la suite de la modification du fichier appsettings.json (Pages/Index.cshtml.cs).The following example demonstrates how a new IOptionsSnapshot<TOptions> is created after appsettings.json changes (Pages/Index.cshtml.cs). Plusieurs demandes adressées au serveur retournent des valeurs constantes fournies par le fichier appsettings.json tant que ce dernier n’est pas changé et que la configuration n’est pas rechargée.Multiple requests to the server return constant values provided by the appsettings.json file until the file is changed and configuration reloads.

private readonly MyOptions _snapshotOptions;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #5: Snapshot options
var snapshotOption1 = _snapshotOptions.Option1;
var snapshotOption2 = _snapshotOptions.Option2;
SnapshotOptions = 
    $"snapshot option1 = {snapshotOption1}, " +
    $"snapshot option2 = {snapshotOption2}";

L’image suivante montre les valeurs option1 et option2 initiales chargées à partir du fichier appsettings.json :The following image shows the initial option1 and option2 values loaded from the appsettings.json file:

snapshot option1 = value1_from_json, snapshot option2 = -1

Changez les valeurs dans le fichier appsettings.json en value1_from_json UPDATED et 200.Change the values in the appsettings.json file to value1_from_json UPDATED and 200. Enregistrez le fichier appsettings.json.Save the appsettings.json file. Actualisez le navigateur pour constater la mise à jour des valeurs des options :Refresh the browser to see that the options values are updated:

snapshot option1 = value1_from_json UPDATED, snapshot option2 = 200

Prise en charge des options nommées avec IConfigureNamedOptionsNamed options support with IConfigureNamedOptions

La prise en charge des options nommées avec IConfigureNamedOptions<TOptions> est illustrée dans l’exemple #6 de l’exemple d’application.Named options support with IConfigureNamedOptions<TOptions> is demonstrated as Example #6 in the sample app.

La prise en charge des options nommées permet à l’application de faire la distinction entre les configurations d’options nommées.Named options support allows the app to distinguish between named options configurations. Dans l’exemple d’application, les options nommées sont déclarées avec OptionsServiceCollectionExtensions.Configure, qui appelle la méthode d’extension ConfigureNamedOptions<TOptions>.Configure :In the sample app, named options are declared with OptionsServiceCollectionExtensions.Configure, which calls the ConfigureNamedOptions<TOptions>.Configure extension method:

// Example #6: Named options (named_options_1)
// Register the ConfigurationBuilder instance which MyOptions binds against.
// Specify that the options loaded from configuration are named
// "named_options_1".
services.Configure<MyOptions>("named_options_1", Configuration);

// Example #6: Named options (named_options_2)
// Specify that the options loaded from the MyOptions class are named
// "named_options_2".
// Use a delegate to configure option values.
services.Configure<MyOptions>("named_options_2", myOptions =>
{
    myOptions.Option1 = "named_options_2_value1_from_action";
});

L’exemple d’application accède aux options nommées avec Get (Pages/Index.cshtml.cs) :The sample app accesses the named options with Get (Pages/Index.cshtml.cs):

private readonly MyOptions _named_options_1;
private readonly MyOptions _named_options_2;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #6: Named options
var named_options_1 = 
    $"named_options_1: option1 = {_named_options_1.Option1}, " +
    $"option2 = {_named_options_1.Option2}";
var named_options_2 = 
    $"named_options_2: option1 = {_named_options_2.Option1}, " +
    $"option2 = {_named_options_2.Option2}";
NamedOptions = $"{named_options_1} {named_options_2}";

Quand l’exemple d’application est exécuté, les options nommées sont retournées :Running the sample app, the named options are returned:

named_options_1: option1 = value1_from_json, option2 = -1
named_options_2: option1 = named_options_2_value1_from_action, option2 = 5

Les valeurs named_options_1, issues de la configuration, sont chargées à partir du fichier appsettings.json.named_options_1 values are provided from configuration, which are loaded from the appsettings.json file. Les valeurs named_options_2 sont fournies par :named_options_2 values are provided by:

  • Le délégué named_options_2 dans ConfigureServices pour Option1.The named_options_2 delegate in ConfigureServices for Option1.
  • La valeur par défaut Option2 fournie par la classe MyOptions.The default value for Option2 provided by the MyOptions class.

Configurer toutes les options avec la méthode ConfigureAllConfigure all options with the ConfigureAll method

Configurez toutes les instances d’options avec la méthode ConfigureAll.Configure all options instances with the ConfigureAll method. Le code suivant configure Option1 pour toutes les instances de configuration ayant une valeur commune.The following code configures Option1 for all configuration instances with a common value. Ajoutez le code suivant manuellement à la méthode Startup.ConfigureServices :Add the following code manually to the Startup.ConfigureServices method:

services.ConfigureAll<MyOptions>(myOptions => 
{
    myOptions.Option1 = "ConfigureAll replacement value";
});

Exécuter l’exemple d’application après avoir ajouté le code produit le résultat suivant :Running the sample app after adding the code produces the following result:

named_options_1: option1 = ConfigureAll replacement value, option2 = -1
named_options_2: option1 = ConfigureAll replacement value, option2 = 5

Notes

Toutes les options sont des instances nommées.All options are named instances. Les instances IConfigureOptions<TOptions> existantes sont traitées comme ciblant l’instance Options.DefaultName, qui est string.Empty.Existing IConfigureOptions<TOptions> instances are treated as targeting the Options.DefaultName instance, which is string.Empty. En outre, IConfigureNamedOptions<TOptions> implémente IConfigureOptions<TOptions>.IConfigureNamedOptions<TOptions> also implements IConfigureOptions<TOptions>. L’implémentation par défaut de IOptionsFactory<TOptions> possède une logique qui utilise chaque élément de manière appropriée.The default implementation of the IOptionsFactory<TOptions> has logic to use each appropriately. L’option nommée null est utilisée pour cibler toutes les instances nommées au lieu d’une instance nommée spécifique (ConfigureAll et PostConfigureAll utilisent cette convention).The null named option is used to target all of the named instances instead of a specific named instance (ConfigureAll and PostConfigureAll use this convention).

API OptionsBuilderOptionsBuilder API

OptionsBuilder<TOptions> permet de configurer des instances TOptions.OptionsBuilder<TOptions> is used to configure TOptions instances. OptionsBuilder simplifie la création d’options nommées. En effet, il est le seul paramètre de l’appel AddOptions<TOptions>(string optionsName) initial et n’apparaît pas dans les appels ultérieurs.OptionsBuilder streamlines creating named options as it's only a single parameter to the initial AddOptions<TOptions>(string optionsName) call instead of appearing in all of the subsequent calls. La validation des options et les surcharges ConfigureOptions qui acceptent des dépendances de service sont uniquement disponibles avec OptionsBuilder.Options validation and the ConfigureOptions overloads that accept service dependencies are only available via OptionsBuilder.

// Options.DefaultName = "" is used.
services.AddOptions<MyOptions>().Configure(o => o.Property = "default");

services.AddOptions<MyOptions>("optionalName")
    .Configure(o => o.Property = "named");

Utiliser les services d’injection de dépendances (DI) pour configurer des optionsUse DI services to configure options

Vous pouvez accéder à d’autres services à partir de l’injection de dépendances pendant que vous configurez des options de deux manières différentes :You can access other services from dependency injection while configuring options in two ways:

Nous vous recommandons de transmettre un délégué de configuration à Configure, car il est plus complexe de créer un service.We recommend passing a configuration delegate to Configure, since creating a service is more complex. Créer votre propre type équivaut à ce que fait automatiquement le framework quand vous utilisez Configure.Creating your own type is equivalent to what the framework does for you when you use Configure. L’appel de Configure a pour effet d’inscrire une instance générique temporaire de IConfigureNamedOptions<TOptions>, dont l’un des constructeurs accepte les types de service génériques spécifiés.Calling Configure registers a transient generic IConfigureNamedOptions<TOptions>, which has a constructor that accepts the generic service types specified.

Validation des optionsOptions validation

La validation des options vous permet de valider les options lorsque celles-ci sont configurées.Options validation allows you to validate options when options are configured. Appelez Validate avec une méthode de validation qui retourne true si les options sont valides et false si elles ne sont pas valides :Call Validate with a validation method that returns true if options are valid and false if they aren't valid:

// Registration
services.AddOptions<MyOptions>("optionalOptionsName")
    .Configure(o => { }) // Configure the options
    .Validate(o => YourValidationShouldReturnTrueIfValid(o), 
        "custom error");

// Consumption
var monitor = services.BuildServiceProvider()
    .GetService<IOptionsMonitor<MyOptions>>();

try
{
    var options = monitor.Get("optionalOptionsName");
}
catch (OptionsValidationException e) 
{
   // e.OptionsName returns "optionalOptionsName"
   // e.OptionsType returns typeof(MyOptions)
   // e.Failures returns a list of errors, which would contain 
   //     "custom error"
}

L’exemple précédent définit l’instance d’options nommée sur optionalOptionsName.The preceding example sets the named options instance to optionalOptionsName. L'instance d’options par défaut est Options.DefaultName.The default options instance is Options.DefaultName.

La validation s’exécute lorsque l’instance d’options est créée.Validation runs when the options instance is created. Votre instance d’options est garantie de réussir la validation lors du premier accès.Your options instance is guaranteed to pass validation the first time it's accessed.

Important

La validation des options ne protège pas contre les modifications des options une fois que les options sont initialement configurées et validées.Options validation doesn't guard against options modifications after the options are initially configured and validated.

La méthode Validate accepte un Func<TOptions, bool>.The Validate method accepts a Func<TOptions, bool>. Pour personnaliser entièrement la validation, implémentez IValidateOptions<TOptions>, ce qui permet :To fully customize validation, implement IValidateOptions<TOptions>, which allows:

  • Validation de plusieurs types d’options : class ValidateTwo : IValidateOptions<Option1>, IValidationOptions<Option2>Validation of multiple options types: class ValidateTwo : IValidateOptions<Option1>, IValidationOptions<Option2>
  • Validation qui dépend d’un autre type d’option : public DependsOnAnotherOptionValidator(IOptionsMonitor<AnotherOption> options)Validation that depends on another option type: public DependsOnAnotherOptionValidator(IOptionsMonitor<AnotherOption> options)

IValidateOptions valide :IValidateOptions validates:

  • Une instance d’options nommée spécifique.A specific named options instance.
  • Toutes les options quand name est null.All options when name is null.

Retourne ValidateOptionsResult à partir de votre implémentation de l’interface :Return a ValidateOptionsResult from your implementation of the interface:

public interface IValidateOptions<TOptions> where TOptions : class
{
    ValidateOptionsResult Validate(string name, TOptions options);
}

La validation basée sur l’annotation de données est disponible dans le package Microsoft.Extensions.Options.DataAnnotations. Pour cela, appelez la méthode ValidateDataAnnotations sur OptionsBuilder<TOptions>.Data Annotation-based validation is available from the Microsoft.Extensions.Options.DataAnnotations package by calling the ValidateDataAnnotations method on OptionsBuilder<TOptions>. Microsoft.Extensions.Options.DataAnnotations est inclus dans le métapaquet Microsoft.AspNetCore.App (ASP.NET Core 2.2 ou ultérieur).Microsoft.Extensions.Options.DataAnnotations is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.2 or later).

using Microsoft.Extensions.DependencyInjection;

private class AnnotatedOptions
{
    [Required]
    public string Required { get; set; }

    [StringLength(5, ErrorMessage = "Too long.")]
    public string StringLength { get; set; }

    [Range(-5, 5, ErrorMessage = "Out of range.")]
    public int IntRange { get; set; }
}

[Fact]
public void CanValidateDataAnnotations()
{
    var services = new ServiceCollection();
    services.AddOptions<AnnotatedOptions>()
        .Configure(o =>
        {
            o.StringLength = "111111";
            o.IntRange = 10;
            o.Custom = "nowhere";
        })
        .ValidateDataAnnotations();

    var sp = services.BuildServiceProvider();

    var error = Assert.Throws<OptionsValidationException>(() => 
        sp.GetRequiredService<IOptionsMonitor<AnnotatedOptions>>().Value);
    ValidateFailure<AnnotatedOptions>(error, Options.DefaultName, 1,
        "DataAnnotation validation failed for members Required " +
            "with the error 'The Required field is required.'.",
        "DataAnnotation validation failed for members StringLength " +
            "with the error 'Too long.'.",
        "DataAnnotation validation failed for members IntRange " +
            "with the error 'Out of range.'.");
}

La validation hâtive (échec rapide au démarrage) est à l’étude pour une version ultérieure.Eager validation (fail fast at startup) is under consideration for a future release.

Options de post-configurationOptions post-configuration

Définissez la post-configuration avec IPostConfigureOptions<TOptions>.Set post-configuration with IPostConfigureOptions<TOptions>. La post-configuration s’exécute après chaque configuration de IConfigureOptions<TOptions> :Post-configuration runs after all IConfigureOptions<TOptions> configuration occurs:

services.PostConfigure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

PostConfigure permet de post-configurer les options nommées :PostConfigure is available to post-configure named options:

services.PostConfigure<MyOptions>("named_options_1", myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

Utilisez PostConfigureAll pour post-configurer toutes les instances de configuration :Use PostConfigureAll to post-configure all configuration instances:

services.PostConfigureAll<MyOptions>(myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

Accès aux options au démarrageAccessing options during startup

IOptions<TOptions> et IOptionsMonitor<TOptions> peuvent être utilisées dans Startup.Configure, dans la mesure où les services sont générés avant que la méthode Configure ne s’exécute.IOptions<TOptions> and IOptionsMonitor<TOptions> can be used in Startup.Configure, since services are built before the Configure method executes.

public void Configure(IApplicationBuilder app, IOptionsMonitor<MyOptions> optionsAccessor)
{
    var option1 = optionsAccessor.CurrentValue.Option1;
}

N’utilisez pas IOptions<TOptions> ou IOptionsMonitor<TOptions> dans Startup.ConfigureServices.Don't use IOptions<TOptions> or IOptionsMonitor<TOptions> in Startup.ConfigureServices. Un état d’options incohérent peut exister en raison de l’ordre des inscriptions de service.An inconsistent options state may exist due to the ordering of service registrations.

Le modèle d’options utilise des classes pour représenter les groupes de paramètres associés.The options pattern uses classes to represent groups of related settings. Quand les paramètres de configuration sont isolés par scénario dans des classes distinctes, l’application est conforme à deux principes d’ingénierie logicielle importants :When configuration settings are isolated by scenario into separate classes, the app adheres to two important software engineering principles:

Ces options fournissent également un mécanisme de validation des données de configuration.Options also provide a mechanism to validate configuration data. Pour plus d'informations, reportez-vous à la section Validation des options.For more information, see the Options validation section.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

PrérequisPrerequisites

Référencer le métapackage Microsoft.AspNetCore.App ou ajouter une référence de package au package Microsoft.Extensions.Options.ConfigurationExtensions.Reference the Microsoft.AspNetCore.App metapackage or add a package reference to the Microsoft.Extensions.Options.ConfigurationExtensions package.

Interfaces d’optionsOptions interfaces

IOptionsMonitor<TOptions> permet de récupérer des options et de gérer les notifications d’options pour les instances TOptions.IOptionsMonitor<TOptions> is used to retrieve options and manage options notifications for TOptions instances. IOptionsMonitor<TOptions> prend en charge les scénarios suivants :IOptionsMonitor<TOptions> supports the following scenarios:

Des scénarios post-configuration vous permettent de définir ou de modifier les options après chaque configuration de IConfigureOptions<TOptions>.Post-configuration scenarios allow you to set or change options after all IConfigureOptions<TOptions> configuration occurs.

IOptionsFactory<TOptions> est chargée de créer les instances d’options.IOptionsFactory<TOptions> is responsible for creating new options instances. Elle dispose d’une seule méthode Create.It has a single Create method. L’implémentation par défaut prend toutes les IConfigureOptions<TOptions> et IPostConfigureOptions<TOptions> inscrites et exécute toutes les configurations, puis les post-configurations.The default implementation takes all registered IConfigureOptions<TOptions> and IPostConfigureOptions<TOptions> and runs all the configurations first, followed by the post-configuration. Elle fait la distinction entre IConfigureNamedOptions<TOptions> et IConfigureOptions<TOptions> et n’appelle que l’interface appropriée.It distinguishes between IConfigureNamedOptions<TOptions> and IConfigureOptions<TOptions> and only calls the appropriate interface.

IOptionsMonitorCache<TOptions> est utilisée par IOptionsMonitor<TOptions> pour mettre en cache les instances TOptions.IOptionsMonitorCache<TOptions> is used by IOptionsMonitor<TOptions> to cache TOptions instances. IOptionsMonitorCache<TOptions> invalide les instances des options dans le moniteur afin que la valeur soit recalculée (TryRemove).The IOptionsMonitorCache<TOptions> invalidates options instances in the monitor so that the value is recomputed (TryRemove). Les valeurs peuvent aussi être introduites manuellement avec TryAdd.Values can be manually introduced with TryAdd. La méthode Clear est utilisée quand toutes les instances nommées doivent être recréées à la demande.The Clear method is used when all named instances should be recreated on demand.

IOptionsSnapshot<TOptions> est utile dans les scénarios où des options doivent être recalculées à chaque requête.IOptionsSnapshot<TOptions> is useful in scenarios where options should be recomputed on every request. Pour plus d’informations, consultez la section Recharger les données de configuration avec IOptionsSnapshot.For more information, see the Reload configuration data with IOptionsSnapshot section.

IOptions<TOptions> peut être utilisée pour prendre en charge des options.IOptions<TOptions> can be used to support options. Toutefois, IOptions<TOptions> ne prend pas en charge les scénarios IOptionsMonitor<TOptions> précédents.However, IOptions<TOptions> doesn't support the preceding scenarios of IOptionsMonitor<TOptions>. Vous pouvez continuer à utiliser IOptions<TOptions> dans des infrastructures et bibliothèques existantes qui utilisent déjà l’interface IOptions<TOptions> mais ne nécessitent pas les scénarios fournis par IOptionsMonitor<TOptions>.You may continue to use IOptions<TOptions> in existing frameworks and libraries that already use the IOptions<TOptions> interface and don't require the scenarios provided by IOptionsMonitor<TOptions>.

Configuration des options généralesGeneral options configuration

La configuration des options générales est illustrée dans l’exemple #1 de l’exemple d’application.General options configuration is demonstrated as Example #1 in the sample app.

Une classe d’options doit être non abstraite avec un constructeur public sans paramètre.An options class must be non-abstract with a public parameterless constructor. La classe suivante, MyOptions, a deux propriétés : Option1 et Option2.The following class, MyOptions, has two properties, Option1 and Option2. Définir des valeurs par défaut est facultatif, mais le constructeur de classe dans l’exemple suivant définit la valeur par défaut Option1.Setting default values is optional, but the class constructor in the following example sets the default value of Option1. Option2 a une valeur par défaut définie par l’initialisation directe de la propriété (Models/MyOptions.cs) :Option2 has a default value set by initializing the property directly (Models/MyOptions.cs):

public class MyOptions
{
    public MyOptions()
    {
        // Set default value.
        Option1 = "value1_from_ctor";
    }
    
    public string Option1 { get; set; }
    public int Option2 { get; set; } = 5;
}

La classe MyOptions est ajoutée au conteneur de service avec Configure et liée à la configuration :The MyOptions class is added to the service container with Configure and bound to configuration:

// Example #1: General configuration
// Register the Configuration instance which MyOptions binds against.
services.Configure<MyOptions>(Configuration);

Le modèle de page suivant utilise une injection de dépendances de constructeur avec IOptionsMonitor<TOptions> pour accéder aux paramètres (Pages/Index.cshtml.cs) :The following page model uses constructor dependency injection with IOptionsMonitor<TOptions> to access the settings (Pages/Index.cshtml.cs):

private readonly MyOptions _options;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #1: Simple options
var option1 = _options.Option1;
var option2 = _options.Option2;
SimpleOptions = $"option1 = {option1}, option2 = {option2}";

Le fichier appsettings.json de l’exemple spécifie des valeurs pour option1 et option2 :The sample's appsettings.json file specifies values for option1 and option2:

{
  "option1": "value1_from_json",
  "option2": -1,
  "subsection": {
    "suboption1": "subvalue1_from_json",
    "suboption2": 200
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Quand l’application est exécutée, la méthode OnGet du modèle de page retourne une chaîne indiquant les valeurs de la classe d’options :When the app is run, the page model's OnGet method returns a string showing the option class values:

option1 = value1_from_json, option2 = -1

Notes

Quand vous utilisez un ConfigurationBuilder personnalisé pour charger une configuration d’options à partir d’un fichier de paramètres, vérifiez que le chemin de base est correctement défini :When using a custom ConfigurationBuilder to load options configuration from a settings file, confirm that the base path is set correctly:

var configBuilder = new ConfigurationBuilder()
   .SetBasePath(Directory.GetCurrentDirectory())
   .AddJsonFile("appsettings.json", optional: true);
var config = configBuilder.Build();

services.Configure<MyOptions>(config);

Vous n’avez pas besoin de définir explicitement le chemin de base quand vous chargez une configuration d’options à partir du fichier de paramètres via CreateDefaultBuilder.Explicitly setting the base path isn't required when loading options configuration from the settings file via CreateDefaultBuilder.

Configurer des options simples avec un déléguéConfigure simple options with a delegate

La configuration d’options simples avec un délégué est illustrée dans l’exemple #2 de l’exemple d’application.Configuring simple options with a delegate is demonstrated as Example #2 in the sample app.

Utilisez un délégué pour définir les valeurs des options.Use a delegate to set options values. L’exemple d’application utilise la classe MyOptionsWithDelegateConfig (Models/MyOptionsWithDelegateConfig.cs) :The sample app uses the MyOptionsWithDelegateConfig class (Models/MyOptionsWithDelegateConfig.cs):

public class MyOptionsWithDelegateConfig
{
    public MyOptionsWithDelegateConfig()
    {
        // Set default value.
        Option1 = "value1_from_ctor";
    }
    
    public string Option1 { get; set; }
    public int Option2 { get; set; } = 5;
}

Dans le code suivant, un second service IConfigureOptions<TOptions> est ajouté au conteneur de services.In the following code, a second IConfigureOptions<TOptions> service is added to the service container. Il utilise un délégué pour configurer la liaison avec MyOptionsWithDelegateConfig :It uses a delegate to configure the binding with MyOptionsWithDelegateConfig:

// Example #2: Options bound and configured by a delegate
services.Configure<MyOptionsWithDelegateConfig>(myOptions =>
{
    myOptions.Option1 = "value1_configured_by_delegate";
    myOptions.Option2 = 500;
});

Index.cshtml.cs :Index.cshtml.cs:

private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #2: Options configured by delegate
var delegate_config_option1 = _optionsWithDelegateConfig.Option1;
var delegate_config_option2 = _optionsWithDelegateConfig.Option2;
SimpleOptionsWithDelegateConfig = 
    $"delegate_option1 = {delegate_config_option1}, " +
    $"delegate_option2 = {delegate_config_option2}";

Vous pouvez ajouter plusieurs fournisseurs de configuration.You can add multiple configuration providers. Des fournisseurs de configuration sont disponibles à partir de packages NuGet et sont appliqués dans l’ordre de leur inscription.Configuration providers are available from NuGet packages and are applied in the order that they're registered. Pour plus d’informations, consultez Configuration dans ASP.NET Core.For more information, see Configuration dans ASP.NET Core.

Chaque appel à Configure ajoute un service IConfigureOptions<TOptions> au conteneur de services.Each call to Configure adds an IConfigureOptions<TOptions> service to the service container. Dans l’exemple précédent, les valeurs de Option1 et Option2 sont toutes deux spécifiées dans appsettings.json, mais les valeurs de Option1 et Option2 sont remplacées par le délégué configuré.In the preceding example, the values of Option1 and Option2 are both specified in appsettings.json, but the values of Option1 and Option2 are overridden by the configured delegate.

Quand plusieurs services de configuration sont activés, la dernière source de configuration spécifiée gagne et définit la valeur de configuration.When more than one configuration service is enabled, the last configuration source specified wins and sets the configuration value. Quand l’application est exécutée, la méthode OnGet du modèle de page retourne une chaîne indiquant les valeurs de la classe d’options :When the app is run, the page model's OnGet method returns a string showing the option class values:

delegate_option1 = value1_configured_by_delegate, delegate_option2 = 500

Configuration des sous-optionsSuboptions configuration

La configuration des sous-options est illustrée dans l’exemple #3 de l’exemple d’application.Suboptions configuration is demonstrated as Example #3 in the sample app.

Les applications doivent créer des classes d’options qui appartiennent à des groupes de scénarios spécifiques (classes) dans l’application.Apps should create options classes that pertain to specific scenario groups (classes) in the app. Les parties de l’application qui requièrent des valeurs de configuration ne doivent avoir accès qu’aux valeurs de configuration qu’elles utilisent.Parts of the app that require configuration values should only have access to the configuration values that they use.

Au moment de la liaison des options à la configuration, chaque propriété du type options est liée à une clé de configuration sous la forme property[:sub-property:].When binding options to configuration, each property in the options type is bound to a configuration key of the form property[:sub-property:]. Par exemple, la propriété MyOptions.Option1 est liée à la clé Option1, qui est lue à partir de la propriété option1 dans appsettings.json.For example, the MyOptions.Option1 property is bound to the key Option1, which is read from the option1 property in appsettings.json.

Dans le code suivant, un troisième service IConfigureOptions<TOptions> est ajouté au conteneur de services.In the following code, a third IConfigureOptions<TOptions> service is added to the service container. Il lie MySubOptions à la section subsection du fichier appsettings.json :It binds MySubOptions to the section subsection of the appsettings.json file:

// Example #3: Suboptions
// Bind options using a sub-section of the appsettings.json file.
services.Configure<MySubOptions>(Configuration.GetSection("subsection"));

La méthode d’extension GetSection requiert le package NuGet Microsoft.Extensions.Options.ConfigurationExtensions.The GetSection extension method requires the Microsoft.Extensions.Options.ConfigurationExtensions NuGet package. Si l’application utilise le métapaquet Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou version ultérieure), le package est automatiquement inclus.If the app uses the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later), the package is automatically included.

Le fichier appsettings.json de l’exemple définit un membre subsection avec des clés pour suboption1 et suboption2 :The sample's appsettings.json file defines a subsection member with keys for suboption1 and suboption2:

{
  "option1": "value1_from_json",
  "option2": -1,
  "subsection": {
    "suboption1": "subvalue1_from_json",
    "suboption2": 200
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

La classe MySubOptions définit des propriétés, SubOption1 et SubOption2, pour conserver les valeurs des options (Models/MySubOptions.cs) :The MySubOptions class defines properties, SubOption1 and SubOption2, to hold the options values (Models/MySubOptions.cs):

public class MySubOptions
{
    public MySubOptions()
    {
        // Set default values.
        SubOption1 = "value1_from_ctor";
        SubOption2 = 5;
    }
    
    public string SubOption1 { get; set; }
    public int SubOption2 { get; set; }
}

La méthode OnGet du modèle de page retourne une chaîne avec les valeurs des options (Pages/Index.cshtml.cs) :The page model's OnGet method returns a string with the options values (Pages/Index.cshtml.cs):

private readonly MySubOptions _subOptions;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #3: Suboptions
var subOption1 = _subOptions.SubOption1;
var subOption2 = _subOptions.SubOption2;
SubOptions = $"subOption1 = {subOption1}, subOption2 = {subOption2}";

Quand l’application est exécutée, la méthode OnGet retourne une chaîne indiquant les valeurs de la classe de sous-options :When the app is run, the OnGet method returns a string showing the suboption class values:

subOption1 = subvalue1_from_json, subOption2 = 200

Options fournies par un modèle d’affichage ou avec une injection de vue directeOptions provided by a view model or with direct view injection

Les options fournies par un modèle d’affichage ou avec une injection de vue directe sont illustrées dans l’exemple #4 de l’exemple d’application.Options provided by a view model or with direct view injection is demonstrated as Example #4 in the sample app.

Vous pouvez fournir les options dans un modèle d’affichage ou en injectant IOptionsMonitor<TOptions> directement dans une vue (Pages/Index.cshtml.cs) :Options can be supplied in a view model or by injecting IOptionsMonitor<TOptions> directly into a view (Pages/Index.cshtml.cs):

private readonly MyOptions _options;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #4: Bind options directly to the page
MyOptions = _options;

L’exemple d’application montre comment injecter IOptionsMonitor<MyOptions> avec une directive @inject :The sample app shows how to inject IOptionsMonitor<MyOptions> with an @inject directive:

@page
@model IndexModel
@using Microsoft.Extensions.Options
@inject IOptionsMonitor<MyOptions> OptionsAccessor
@{
    ViewData["Title"] = "Options Sample";
}

<h1>@ViewData["Title"]</h1>

Quand l’application est exécutée, les valeurs d’options sont affichées dans la page rendue :When the app is run, the options values are shown in the rendered page:

Les valeurs d’options Option1: value1_from_json et Option2: -1 sont chargées à partir du modèle et par injection dans la vue.

Recharger les données de configuration avec IOptionsSnapshotReload configuration data with IOptionsSnapshot

Le rechargement des données de configuration avec IOptionsSnapshot<TOptions> est illustré dans l’exemple #5 de l’exemple d’application.Reloading configuration data with IOptionsSnapshot<TOptions> is demonstrated in Example #5 in the sample app.

IOptionsSnapshot<TOptions> prend en charge le rechargement des options avec une charge de traitement minimale.IOptionsSnapshot<TOptions> supports reloading options with minimal processing overhead.

Les options sont calculées une fois par requête quand le système y accède et sont mises en cache pour toute la durée de vie de la requête.Options are computed once per request when accessed and cached for the lifetime of the request.

Dans l’exemple suivant, un IOptionsSnapshot<TOptions> est créé à la suite de la modification du fichier appsettings.json (Pages/Index.cshtml.cs).The following example demonstrates how a new IOptionsSnapshot<TOptions> is created after appsettings.json changes (Pages/Index.cshtml.cs). Plusieurs demandes adressées au serveur retournent des valeurs constantes fournies par le fichier appsettings.json tant que ce dernier n’est pas changé et que la configuration n’est pas rechargée.Multiple requests to the server return constant values provided by the appsettings.json file until the file is changed and configuration reloads.

private readonly MyOptions _snapshotOptions;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #5: Snapshot options
var snapshotOption1 = _snapshotOptions.Option1;
var snapshotOption2 = _snapshotOptions.Option2;
SnapshotOptions = 
    $"snapshot option1 = {snapshotOption1}, " +
    $"snapshot option2 = {snapshotOption2}";

L’image suivante montre les valeurs option1 et option2 initiales chargées à partir du fichier appsettings.json :The following image shows the initial option1 and option2 values loaded from the appsettings.json file:

snapshot option1 = value1_from_json, snapshot option2 = -1

Changez les valeurs dans le fichier appsettings.json en value1_from_json UPDATED et 200.Change the values in the appsettings.json file to value1_from_json UPDATED and 200. Enregistrez le fichier appsettings.json.Save the appsettings.json file. Actualisez le navigateur pour constater la mise à jour des valeurs des options :Refresh the browser to see that the options values are updated:

snapshot option1 = value1_from_json UPDATED, snapshot option2 = 200

Prise en charge des options nommées avec IConfigureNamedOptionsNamed options support with IConfigureNamedOptions

La prise en charge des options nommées avec IConfigureNamedOptions<TOptions> est illustrée dans l’exemple #6 de l’exemple d’application.Named options support with IConfigureNamedOptions<TOptions> is demonstrated as Example #6 in the sample app.

La prise en charge des options nommées permet à l’application de faire la distinction entre les configurations d’options nommées.Named options support allows the app to distinguish between named options configurations. Dans l’exemple d’application, les options nommées sont déclarées avec OptionsServiceCollectionExtensions.Configure, qui appelle la méthode d’extension ConfigureNamedOptions<TOptions>.Configure :In the sample app, named options are declared with OptionsServiceCollectionExtensions.Configure, which calls the ConfigureNamedOptions<TOptions>.Configure extension method:

// Example #6: Named options (named_options_1)
// Register the ConfigurationBuilder instance which MyOptions binds against.
// Specify that the options loaded from configuration are named
// "named_options_1".
services.Configure<MyOptions>("named_options_1", Configuration);

// Example #6: Named options (named_options_2)
// Specify that the options loaded from the MyOptions class are named
// "named_options_2".
// Use a delegate to configure option values.
services.Configure<MyOptions>("named_options_2", myOptions =>
{
    myOptions.Option1 = "named_options_2_value1_from_action";
});

L’exemple d’application accède aux options nommées avec Get (Pages/Index.cshtml.cs) :The sample app accesses the named options with Get (Pages/Index.cshtml.cs):

private readonly MyOptions _named_options_1;
private readonly MyOptions _named_options_2;
public IndexModel(
    IOptionsMonitor<MyOptions> optionsAccessor, 
    IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig, 
    IOptionsMonitor<MySubOptions> subOptionsAccessor, 
    IOptionsSnapshot<MyOptions> snapshotOptionsAccessor, 
    IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
    _options = optionsAccessor.CurrentValue;
    _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
    _subOptions = subOptionsAccessor.CurrentValue;
    _snapshotOptions = snapshotOptionsAccessor.Value;
    _named_options_1 = namedOptionsAccessor.Get("named_options_1");
    _named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
// Example #6: Named options
var named_options_1 = 
    $"named_options_1: option1 = {_named_options_1.Option1}, " +
    $"option2 = {_named_options_1.Option2}";
var named_options_2 = 
    $"named_options_2: option1 = {_named_options_2.Option1}, " +
    $"option2 = {_named_options_2.Option2}";
NamedOptions = $"{named_options_1} {named_options_2}";

Quand l’exemple d’application est exécuté, les options nommées sont retournées :Running the sample app, the named options are returned:

named_options_1: option1 = value1_from_json, option2 = -1
named_options_2: option1 = named_options_2_value1_from_action, option2 = 5

Les valeurs named_options_1, issues de la configuration, sont chargées à partir du fichier appsettings.json.named_options_1 values are provided from configuration, which are loaded from the appsettings.json file. Les valeurs named_options_2 sont fournies par :named_options_2 values are provided by:

  • Le délégué named_options_2 dans ConfigureServices pour Option1.The named_options_2 delegate in ConfigureServices for Option1.
  • La valeur par défaut Option2 fournie par la classe MyOptions.The default value for Option2 provided by the MyOptions class.

Configurer toutes les options avec la méthode ConfigureAllConfigure all options with the ConfigureAll method

Configurez toutes les instances d’options avec la méthode ConfigureAll.Configure all options instances with the ConfigureAll method. Le code suivant configure Option1 pour toutes les instances de configuration ayant une valeur commune.The following code configures Option1 for all configuration instances with a common value. Ajoutez le code suivant manuellement à la méthode Startup.ConfigureServices :Add the following code manually to the Startup.ConfigureServices method:

services.ConfigureAll<MyOptions>(myOptions => 
{
    myOptions.Option1 = "ConfigureAll replacement value";
});

Exécuter l’exemple d’application après avoir ajouté le code produit le résultat suivant :Running the sample app after adding the code produces the following result:

named_options_1: option1 = ConfigureAll replacement value, option2 = -1
named_options_2: option1 = ConfigureAll replacement value, option2 = 5

Notes

Toutes les options sont des instances nommées.All options are named instances. Les instances IConfigureOptions<TOptions> existantes sont traitées comme ciblant l’instance Options.DefaultName, qui est string.Empty.Existing IConfigureOptions<TOptions> instances are treated as targeting the Options.DefaultName instance, which is string.Empty. En outre, IConfigureNamedOptions<TOptions> implémente IConfigureOptions<TOptions>.IConfigureNamedOptions<TOptions> also implements IConfigureOptions<TOptions>. L’implémentation par défaut de IOptionsFactory<TOptions> possède une logique qui utilise chaque élément de manière appropriée.The default implementation of the IOptionsFactory<TOptions> has logic to use each appropriately. L’option nommée null est utilisée pour cibler toutes les instances nommées au lieu d’une instance nommée spécifique (ConfigureAll et PostConfigureAll utilisent cette convention).The null named option is used to target all of the named instances instead of a specific named instance (ConfigureAll and PostConfigureAll use this convention).

API OptionsBuilderOptionsBuilder API

OptionsBuilder<TOptions> permet de configurer des instances TOptions.OptionsBuilder<TOptions> is used to configure TOptions instances. OptionsBuilder simplifie la création d’options nommées. En effet, il est le seul paramètre de l’appel AddOptions<TOptions>(string optionsName) initial et n’apparaît pas dans les appels ultérieurs.OptionsBuilder streamlines creating named options as it's only a single parameter to the initial AddOptions<TOptions>(string optionsName) call instead of appearing in all of the subsequent calls. La validation des options et les surcharges ConfigureOptions qui acceptent des dépendances de service sont uniquement disponibles avec OptionsBuilder.Options validation and the ConfigureOptions overloads that accept service dependencies are only available via OptionsBuilder.

// Options.DefaultName = "" is used.
services.AddOptions<MyOptions>().Configure(o => o.Property = "default");

services.AddOptions<MyOptions>("optionalName")
    .Configure(o => o.Property = "named");

Utiliser les services d’injection de dépendances (DI) pour configurer des optionsUse DI services to configure options

Vous pouvez accéder à d’autres services à partir de l’injection de dépendances pendant que vous configurez des options de deux manières différentes :You can access other services from dependency injection while configuring options in two ways:

Nous vous recommandons de transmettre un délégué de configuration à Configure, car il est plus complexe de créer un service.We recommend passing a configuration delegate to Configure, since creating a service is more complex. Créer votre propre type équivaut à ce que fait automatiquement le framework quand vous utilisez Configure.Creating your own type is equivalent to what the framework does for you when you use Configure. L’appel de Configure a pour effet d’inscrire une instance générique temporaire de IConfigureNamedOptions<TOptions>, dont l’un des constructeurs accepte les types de service génériques spécifiés.Calling Configure registers a transient generic IConfigureNamedOptions<TOptions>, which has a constructor that accepts the generic service types specified.

Options de post-configurationOptions post-configuration

Définissez la post-configuration avec IPostConfigureOptions<TOptions>.Set post-configuration with IPostConfigureOptions<TOptions>. La post-configuration s’exécute après chaque configuration de IConfigureOptions<TOptions> :Post-configuration runs after all IConfigureOptions<TOptions> configuration occurs:

services.PostConfigure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

PostConfigure permet de post-configurer les options nommées :PostConfigure is available to post-configure named options:

services.PostConfigure<MyOptions>("named_options_1", myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

Utilisez PostConfigureAll pour post-configurer toutes les instances de configuration :Use PostConfigureAll to post-configure all configuration instances:

services.PostConfigureAll<MyOptions>(myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

Accès aux options au démarrageAccessing options during startup

IOptions<TOptions> et IOptionsMonitor<TOptions> peuvent être utilisées dans Startup.Configure, dans la mesure où les services sont générés avant que la méthode Configure ne s’exécute.IOptions<TOptions> and IOptionsMonitor<TOptions> can be used in Startup.Configure, since services are built before the Configure method executes.

public void Configure(IApplicationBuilder app, IOptionsMonitor<MyOptions> optionsAccessor)
{
    var option1 = optionsAccessor.CurrentValue.Option1;
}

N’utilisez pas IOptions<TOptions> ou IOptionsMonitor<TOptions> dans Startup.ConfigureServices.Don't use IOptions<TOptions> or IOptionsMonitor<TOptions> in Startup.ConfigureServices. Un état d’options incohérent peut exister en raison de l’ordre des inscriptions de service.An inconsistent options state may exist due to the ordering of service registrations.

Ressources supplémentairesAdditional resources