アプリの構成App configuration

Web フォームでアプリ構成を読み込む主な方法は、 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 は、アプリが WINDOWS IIS サーバーでホストされている場合、 web.config ファイルが存在する可能性があります。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 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, 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.jsappsettings.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 Core CLI のコマンドを使用して管理さ user-secrets れます。Managed with the .NET Core 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 は、2つのアンダースコア () を持つ値をアクセス時にコロンに変換することによって、この制限に対処 __ します。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.config の戻り値The return of web.config

アプリを IIS の Windows にデプロイした場合、 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 モジュール (モジュール) への参照を追加します。By default, IIS adds a reference to the ASP.NET Core Module (ANCM). モジュールは、Kestrel web サーバーの代わりにアプリをホストするネイティブ IIS モジュールです。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 framework は、前に構成した解決済みの構成をこのインターフェイスに自動的に設定します。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

Web フォームでは、 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.