Конфигурация приложенийApp configuration

Основной способ загрузки конфигурации приложения в веб-формы — с записями в web.config файле — либо на сервере, либо в связанном файле конфигурации, на который ссылается web.config. Статический объект можно использовать ConfigurationManager для взаимодействия с параметрами приложения, строками подключения репозитория данных и другими поставщиками расширенной конфигурации, добавленными в приложение.The primary way to load app configuration in Web Forms is with entries in the web.config file—either on the server or a related configuration file referenced by web.config. You can use the static ConfigurationManager object to interact with app settings, data repository connection strings, and other extended configuration providers that are added into the app. Обычно для просмотра взаимодействия с конфигурацией приложения отображается следующий код:It's typical to see interactions with app configuration as seen in the following code:

var configurationValue = ConfigurationManager.AppSettings["ConfigurationSettingName"];
var connectionString = ConfigurationManager.ConnectionStrings["MyDatabaseConnectionName"].ConnectionString;

При использовании ASP.NET Core и на стороне сервера Blazor файл web.config может присутствовать, если приложение размещено на сервере Windows IIS.With ASP.NET Core and server-side Blazor, the web.config file MAY be present if your app is hosted on a Windows IIS server. Однако ConfigurationManager взаимодействие с этой конфигурацией не требуется, и вы можете получить более структурированную конфигурацию приложения из других источников.However, there's no ConfigurationManager interaction with this configuration, and you can receive more structured app configuration from other sources. Давайте посмотрим, как собирается конфигурация и как можно получить доступ к сведениям о конфигурации из файла web.config .Let's take a look at how configuration is gathered and how you can still access configuration information from a web.config file.

Источники конфигурацийConfiguration sources

ASP.NET Core распознает множество источников конфигурации, которые вы можете использовать для приложения.ASP.NET Core recognizes there are many configuration sources you may want to use for your app. Платформа пытается предложить наиболее подходящие из этих функций по умолчанию.The framework attempts to offer you the best of these features by default. Конфигурация считывается и объединяется из этих различных источников с помощью ASP.NET Core.Configuration is read and aggregated from these various sources by ASP.NET Core. Более поздние загруженные значения для одного и того же ключа конфигурации имеют приоритет над более ранними значениями.Later loaded values for the same configuration key take precedence over earlier values.

ASP.NET Core была разработана для обеспечения работы в облаке и упрощения настройки приложений для операторов и разработчиков.ASP.NET Core was designed to be cloud-aware and to make the configuration of apps easier for both operators and developers. ASP.NET Core работает с учетом среды и знает, работает ли она в Production Development среде или.ASP.NET Core is environment-aware and knows if it's running in your Production or Development environment. Индикатор среды задается в ASPNETCORE_ENVIRONMENT системной переменной среды.The environment indicator is set in the ASPNETCORE_ENVIRONMENT system environment variable. Если значение не задано, приложение по умолчанию работает в Production среде.If no value is configured, the app defaults to running in the Production environment.

Приложение может активировать и добавить конфигурацию из нескольких источников в зависимости от имени среды.Your app can trigger and add configuration from several sources based on the environment's name. По умолчанию конфигурация загружается из следующих ресурсов в указанном порядке.By default, the configuration is loaded from the following resources in the order listed:

  1. appsettings.jsв файле, если он естьappsettings.json file, if present
  2. appSettings. Файл {ENVIRONMENT_NAME}. JSON , если он естьappsettings.{ENVIRONMENT_NAME}.json file, if present
  3. Файл секретов пользователя на диске, если он естьUser secrets file on disk, if present
  4. Переменные средыEnvironment variables
  5. аргументов командной строки;Command-line arguments

appsettings.jsк формату и доступуappsettings.json format and access

appsettings.jsв файле могут быть иерархическими со значениями, структурированными как в следующем JSON:The appsettings.json file can be hierarchical with values structured like the following JSON:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

При отображении с помощью предыдущего JSON система конфигурации выравнивает дочерние значения и ссылается на полные иерархические пути.When presented with the preceding JSON, the configuration system flattens child values and references their fully qualified hierarchical paths. Символ двоеточия ( : ) разделяет каждое свойство в иерархии.A colon (:) character separates each property in the hierarchy. Например, ключ конфигурации section1:key0 обращается к section1 значению объектного литерала key0 .For example, the configuration key section1:key0 accesses the section1 object literal's key0 value.

Секреты пользователя.User secrets

Секреты пользователя:User secrets are:

  • Значения конфигурации, хранящиеся в JSON-файле на рабочей станции разработчика, за пределами папки разработки приложения.Configuration values that are stored in a JSON file on the developer's workstation, outside of the app development folder.
  • Загружается только при выполнении в Development среде.Only loaded when running in the Development environment.
  • Связан с конкретным приложением.Associated with a specific app.
  • Управляется с помощью команды интерфейса командной строки .NET user-secrets .Managed with the .NET CLI's user-secrets command.

Настройте приложение для хранения секретных данных, выполнив user-secrets команду:Configure your app for secrets storage by executing the user-secrets command:

dotnet user-secrets init

Предыдущая команда добавляет UserSecretsId элемент в файл проекта.The preceding command adds a UserSecretsId element to the project file. Элемент содержит идентификатор GUID, который используется для связывания секретов с приложением.The element contains a GUID, which is used to associate secrets with the app. Затем можно определить секрет с помощью set команды.You can then define a secret with the set command. Пример:For example:

dotnet user-secrets set "Parent:ApiKey" "12345"

Предыдущая команда делает Parent:ApiKey ключ конфигурации доступным на рабочей станции разработчика со значением 12345 .The preceding command makes the Parent:ApiKey configuration key available on a developer's workstation with the value 12345.

Дополнительные сведения о создании, хранении и управлении секретами пользователей см. в разделе безопасного хранения секретов приложений в разработке в ASP.NET Core документе.For more information about creating, storing, and managing user secrets, see the Safe storage of app secrets in development in ASP.NET Core document.

Переменные средыEnvironment variables

Следующий набор значений, загружаемых в конфигурацию приложения, — это переменные среды системы.The next set of values loaded into your app configuration is the system's environment variables. Все параметры переменных среды системы теперь доступны через API настройки.All of your system's environment variable settings are now accessible to you through the configuration API. При чтении внутри приложения иерархические значения преобразуются в плоские и разделяются символами двоеточия.Hierarchical values are flattened and separated by colon characters when read inside your app. Однако некоторые операционные системы не разрешают имена переменных среды с двоеточием.However, some operating systems don't allow the colon character environment variable names. ASP.NET Core устраняет это ограничение, преобразуя значения с двойным подчеркиванием ( __ ) в двоеточие при обращении к ним.ASP.NET Core addresses this limitation by converting values that have double-underscores (__) into a colon when they're accessed. Parent:ApiKeyЗначение из приведенного выше раздела секреты пользователя можно переопределить с помощью переменной среды Parent__ApiKey .The Parent:ApiKey value from the user secrets section above can be overridden with the environment variable Parent__ApiKey.

аргументов командной строки;Command-line arguments

Кроме того, конфигурацию можно указать в качестве аргументов командной строки при запуске приложения.Configuration can also be provided as command-line arguments when your app is started. Используйте двойное тире ( -- ) или прямую косую черту ( / ), чтобы указать имя устанавливаемого значения конфигурации и значение, которое необходимо настроить.Use the double-dash (--) or forward-slash (/) notation to indicate the name of the configuration value to set and the value to be configured. Синтаксис напоминает следующие команды:The syntax resembles the following commands:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890

Возврат web.configThe return of web.config

Если вы развернули приложение в Windows на IIS, файл web.config по-прежнему настраивает IIS для управления приложением.If you've deployed your app to Windows on IIS, the web.config file still configures IIS to manage your app. По умолчанию службы IIS добавляют ссылку на модуль ASP.NET Core (ANCM).By default, IIS adds a reference to the ASP.NET Core Module (ANCM). ANCM — это собственный модуль IIS, в котором размещено приложение вместо веб-сервера Kestrel.ANCM is a native IIS module that hosts your app in place of the Kestrel web server. Этот web.config раздел напоминает следующую XML-разметку:This web.config section resembles the following XML markup:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Конфигурация конкретного приложения может быть определена путем вложения environmentVariables элемента в aspNetCore элемент.App-specific configuration can be defined by nesting an environmentVariables element in the aspNetCore element. Значения, определенные в этом разделе, представлены в ASP.NET Core приложении в виде переменных среды.The values defined in this section are presented to the ASP.NET Core app as environment variables. Переменные среды загружаются соответствующим образом во время выполнения этого сегмента запуска приложения.The environment variables load appropriately during that segment of app startup.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="Parent:ApiKey" value="67890" />
  </environmentVariables>
</aspNetCore>

Чтение конфигурации в приложенииRead configuration in the app

ASP.NET Core предоставляет конфигурацию приложения через IConfiguration интерфейс.ASP.NET Core provides app configuration through the IConfiguration interface. Этот интерфейс конфигурации должен запрашиваться Blazor компонентами, Blazor страницами и любым другим управляемым ASP.NET Core классом, которым требуется доступ к конфигурации.This configuration interface should be requested by your Blazor components, Blazor pages, and any other ASP.NET Core-managed class that needs access to configuration. Платформа ASP.NET Core автоматически заполнит этот интерфейс разрешенной конфигурацией, настроенной ранее.The ASP.NET Core framework will automatically populate this interface with the resolved configuration configured earlier. На Blazor странице или в разметке Razor компонента можно внедрить IConfiguration объект с @inject директивой, расположенной в верхней части файла . Razor следующим образом:On a Blazor page or a component's Razor markup, you can inject the IConfiguration object with an @inject directive at the top of the .razor file like this:

@inject IConfiguration Configuration

Приведенная выше инструкция делает IConfiguration объект доступным в качестве Configuration переменной на протяжении всего остального шаблона Razor.This preceding statement makes the IConfiguration object available as the Configuration variable throughout the rest of the Razor template.

Отдельные параметры конфигурации можно прочитать, указав иерархию параметров конфигурации, которую нужно использовать в качестве параметра индексатора:Individual configuration settings can be read by specifying the configuration setting hierarchy sought as an indexer parameter:

var mySetting = Configuration["section1:key0"];

Вы можете извлечь все разделы конфигурации с помощью GetSection метода, чтобы получить коллекцию ключей в определенном месте с синтаксисом, аналогичным GetSection("section1") получению конфигурации для Section1 из предыдущего примера.You can fetch entire configuration sections by using the GetSection method to retrieve a collection of keys at a specific location with a syntax similar to GetSection("section1") to retrieve the configuration for section1 from the earlier example.

Строго типизированная конфигурацияStrongly typed configuration

С помощью веб-форм можно было создать строго типизированный тип конфигурации, наследуемый от ConfigurationSection типа и связанных с ним типов.With Web Forms, it was possible to create a strongly typed configuration type that inherited from the ConfigurationSection type and associated types. ConfigurationSectionВы можете настроить некоторые бизнес-правила и обработку для этих значений конфигурации.A ConfigurationSection allowed you to configure some business rules and processing for those configuration values.

В ASP.NET Core можно указать иерархию классов, которая будет принимать значения конфигурации.In ASP.NET Core, you can specify a class hierarchy that will receive the configuration values. Следующие классы:These classes:

  • Не нужно наследовать от родительского класса.Don't need to inherit from a parent class.
  • Должны быть включены public свойства, соответствующие свойствам и ссылкам на типы для структуры конфигурации, которую вы хотите захватить.Should include public properties that match the properties and type references for the configuration structure you wish to capture.

Для предыдущих appsettings.js образца можно было определить следующие классы для записи значений:For the earlier appsettings.json sample, you could define the following classes to capture the values:

public class MyConfig
{
    public MyConfigSection section0 { get; set;}

    public MyConfigSection section1 { get; set;}
}

public class MyConfigSection
{
    public string key0 { get; set; }

    public string key1 { get; set; }
}

Эту иерархию классов можно заполнить, добавив следующую строку в Startup.ConfigureServices метод:This class hierarchy can be populated by adding the following line to the Startup.ConfigureServices method:

services.Configure<MyConfig>(Configuration);

В оставшейся части приложения можно добавить входной параметр в классы или @inject директиву в шаблонах Razor типа IOptions<MyConfig> для получения строго типизированных параметров конфигурации.In the rest of the app, you can add an input parameter to classes or an @inject directive in Razor templates of type IOptions<MyConfig> to receive the strongly typed configuration settings. IOptions<MyConfig>.ValueСвойство даст MyConfig значение, заполненное из параметров конфигурации.The IOptions<MyConfig>.Value property will yield the MyConfig value populated from the configuration settings.

@inject IOptions<MyConfig> options
@code {
    var MyConfiguration = options.Value;
    var theSetting = MyConfiguration.section1.key0;
}

Дополнительные сведения о функциях параметров можно найти в шаблоне параметров в ASP.NET Core документе.More information about the Options feature can be found in the Options pattern in ASP.NET Core document.