チュートリアル:ASP.NET Core アプリで動的な構成を使用するTutorial: Use dynamic configuration in an ASP.NET Core app

ASP.NET Core には、さまざまなソースから構成データを読み取ることができるプラグ可能な構成システムがあります。ASP.NET Core has a pluggable configuration system that can read configuration data from a variety of sources. アプリケーションを再起動せずに、その場で変更を処理できます。It can handle changes on the fly without causing an application to restart. ASP.NET Core では、厳密に型指定された .NET クラスへの構成設定のバインドがサポートされています。ASP.NET Core supports the binding of configuration settings to strongly typed .NET classes. さまざまな IOptions<T> パターンを使用して、それらをコードに挿入します。It injects them into your code by using the various IOptions<T> patterns. そうしたパターンの 1 つである IOptionsSnapshot<T> では、基になるデータが変化したときに、アプリケーションの構成が自動的にリロードされます。One of these patterns, specifically IOptionsSnapshot<T>, automatically reloads the application's configuration when the underlying data changes. アプリケーションのコントローラーに IOptionsSnapshot<T> を挿入すれば、Azure App Configuration に格納されている最新の構成にアクセスすることができます。You can inject IOptionsSnapshot<T> into controllers in your application to access the most recent configuration stored in Azure App Configuration.

ミドルウェアを使って構成設定のセットを動的に更新するよう、App Configuration ASP.NET Core クライアント ライブラリを設定することもできます。You also can set up the App Configuration ASP.NET Core client library to refresh a set of configuration settings dynamically using a middleware. Web アプリで要求の受信が続けられている限り、構成設定は継続的に構成ストアで更新されます。As long as the web app continues to receive requests, the configuration settings continue to get updated with the configuration store.

設定の更新を維持しながら、構成ストアの呼び出しが多くなりすぎないようにするため、キャッシュが各設定に使用されます。In order to keep the settings updated and avoid too many calls to the configuration store, a cache is used for each setting. 設定のキャッシュされた値の有効期限が切れるまで、構成ストアの値が変更された場合でも、更新操作で値は更新されません。Until the cached value of a setting has expired, the refresh operation does not update the value, even when the value has changed in the configuration store. 各要求の既定の有効期間は 30 秒ですが、必要な場合はオーバーライドできます。The default expiration time for each request is 30 seconds, but it can be overridden if required.

このチュートリアルでは、自分が作成するコードに、構成の動的更新を実装する方法について説明します。This tutorial shows how you can implement dynamic configuration updates in your code. これは、クイック スタートで紹介されている Web アプリに基づいています。It builds on the web app introduced in the quickstarts. 先に進む前に、App Configuration を使用した ASP.NET Core アプリの作成を完了しておいてください。Before you continue, finish Create an ASP.NET Core app with App Configuration first.

このチュートリアルの手順は、任意のコード エディターを使用して実行できます。You can use any code editor to do the steps in this tutorial. 推奨のエディターは Visual Studio Code です (Windows、macOS、および Linux プラットフォームで使用できます)。Visual Studio Code is an excellent option that's available on the Windows, macOS, and Linux platforms.

このチュートリアルでは、以下の内容を学習します。In this tutorial, you learn how to:

  • App Configuration ストアへの変更に合わせて構成を更新するようにアプリケーションを設定する。Set up your application to update its configuration in response to changes in an App Configuration store.
  • アプリケーションのコントローラーに最新の構成を挿入する。Inject the latest configuration in your application's controllers.

前提条件Prerequisites

このチュートリアルを実行するには、.NET Core SDK をインストールします。To do this tutorial, install the .NET Core SDK.

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。If you don't have an Azure subscription, create a free account before you begin.

先に進む前に、App Configuration を使用した ASP.NET Core アプリの作成を完了しておいてください。Before you continue, finish Create an ASP.NET Core app with App Configuration first.

App Configuration からデータを再度読み込むReload data from App Configuration

  1. 次のコマンドを実行して、Microsoft.Azure.AppConfiguration.AspNetCore NuGet パッケージへの参照を追加します。Add a reference to the Microsoft.Azure.AppConfiguration.AspNetCore NuGet package by running the following command:

    dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore --version 3.0.0-preview-011100002-1192
    
  2. Program.cs を開き、config.AddAzureAppConfiguration() メソッドを追加して CreateWebHostBuilder メソッドを更新します。Open Program.cs, and update the CreateWebHostBuilder method to add the config.AddAzureAppConfiguration() method.

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                var settings = config.Build();
    
                config.AddAzureAppConfiguration(options =>
                {
                    options.Connect(settings["ConnectionStrings:AppConfig"])
                           .ConfigureRefresh(refresh =>
                           {
                               refresh.Register("TestApp:Settings:BackgroundColor")
                                      .Register("TestApp:Settings:FontColor")
                                      .Register("TestApp:Settings:Message");
                           });
                });
            })
            .UseStartup<Startup>();
    

    更新操作がトリガーされたときに、構成データを App Configuration ストアで更新するために使用する設定を指定するには、ConfigureRefresh メソッドを使います。The ConfigureRefresh method is used to specify the settings used to update the configuration data with the App Configuration store when a refresh operation is triggered. 実際に更新操作をトリガーするには、変更が発生したら構成データを更新するように、アプリケーションに対して更新ミドルウェアを構成する必要があります。In order to actually trigger a refresh operation, a refresh middleware needs to be configured for the application to refresh the configuration data when any change occurs.

  3. 新しい Settings クラスを定義して実装する Settings.cs ファイルを追加します。Add a Settings.cs file that defines and implements a new Settings class.

    namespace TestAppConfig
    {
        public class Settings
        {
            public string BackgroundColor { get; set; }
            public long FontSize { get; set; }
            public string FontColor { get; set; }
            public string Message { get; set; }
        }
    }
    
  4. Startup.cs を開き、ConfigureServices メソッドの IServiceCollection.Configure<T> を使用して、構成データを Settings クラスにバインドします。Open Startup.cs, and use IServiceCollection.Configure<T> in the ConfigureServices method to bind configuration data to the Settings class.

    public void ConfigureServices(IServiceCollection services)
    {
        services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
        services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    }
    
  5. Configure メソッドに UseAzureAppConfiguration ミドルウェアを追加して更新し、ASP.NET Core Web アプリで要求の受信が続けられている間、更新用に登録された構成設定を更新できるようにします。Update the Configure method, adding the UseAzureAppConfiguration middleware to allow the configuration settings registered for refresh to be updated while the ASP.NET Core web app continues to receive requests.

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseAzureAppConfiguration();
    
        services.Configure<CookiePolicyOptions>(options =>
        {
            options.CheckConsentNeeded = context => true;
            options.MinimumSameSitePolicy = SameSiteMode.None;
        });
    
        app.UseMvc();
    }
    

    ミドルウェアでは、Program.csAddAzureAppConfiguration メソッドで指定されている更新の構成を使って、ASP.NET Core Web アプリによって受信された各要求の更新がトリガーされます。The middleware uses the refresh configuration specified in the AddAzureAppConfiguration method in Program.cs to trigger a refresh for each request received by the ASP.NET Core web app. 要求ごとに、更新操作がトリガーされ、登録されている構成設定のキャッシュされた値の有効期限が切れているかどうかが、クライアント ライブラリによって確認されます。For each request, a refresh operation is triggered and the client library checks if the cached value for the registered configuration settings have expired. キャッシュされた値の有効期限が切れている設定については、App Configuration ストアで値が更新され、それ以外の値は変更されません。For the cached values that have expired, the values for the settings are updated with the App Configuration store, and the remaining values remain unchanged.

    注意

    構成設定の既定のキャッシュ有効期限は 30 秒ですが、ConfigureRefresh メソッドへの引数として渡されるオプション初期化子で SetCacheExpiration メソッドを呼び出すことにより、オーバーライドできます。The default cache expiration time for a configuration setting is 30 seconds, but can be overridden by calling the SetCacheExpiration method on the options initializer passed as an argument to the ConfigureRefresh method.

最新の構成データを使用するUse the latest configuration data

  1. Controllers ディレクトリにある HomeController.cs を開いて、Microsoft.Extensions.Options パッケージへの参照を追加します。Open HomeController.cs in the Controllers directory, and add a reference to the Microsoft.Extensions.Options package.

    using Microsoft.Extensions.Options;
    
  2. HomeController クラスを更新して、依存関係の挿入を通じて Settings を受け取り、その値を利用するようにします。Update the HomeController class to receive Settings through dependency injection, and make use of its values.

    public class HomeController : Controller
    {
        private readonly Settings _settings;
        public HomeController(IOptionsSnapshot<Settings> settings)
        {
            _settings = settings.Value;
        }
    
        public IActionResult Index()
        {
            ViewData["BackgroundColor"] = _settings.BackgroundColor;
            ViewData["FontSize"] = _settings.FontSize;
            ViewData["FontColor"] = _settings.FontColor;
            ViewData["Message"] = _settings.Message;
    
            return View();
        }
    }
    
  3. Views の Home ディレクトリにある Index.cshtml を開いて、内容を次のスクリプトに置き換えます。Open Index.cshtml in the Views > Home directory, and replace its content with the following script:

    <!DOCTYPE html>
    <html lang="en">
    <style>
        body {
            background-color: @ViewData["BackgroundColor"]
        }
        h1 {
            color: @ViewData["FontColor"];
            font-size: @ViewData["FontSize"];
        }
    </style>
    <head>
        <title>Index View</title>
    </head>
    <body>
        <h1>@ViewData["Message"]</h1>
    </body>
    </html>
    

アプリをビルドしてローカルで実行するBuild and run the app locally

  1. .NET Core CLI を使用してアプリケーションをビルドするには、コマンド シェルで次のコマンドを実行します。To build the app by using the .NET Core CLI, run the following command in the command shell:

     dotnet build
    
  2. ビルドが正常に完了したら、次のコマンドを実行して、Web アプリをローカルで実行します。After the build successfully completes, run the following command to run the web app locally:

     dotnet run
    
  3. ブラウザー ウィンドウを開いて、http://localhost:5000 (ローカルでホストされた Web アプリの既定の URL) に移動します。Open a browser window, and go to http://localhost:5000, which is the default URL for the web app hosted locally.

    クイック スタートのアプリ (ローカルで起動)

  4. Azure portal にサインインします。Sign in to the Azure portal. [すべてのリソース] を選択し、クイック スタートで作成した App Configuration ストア インスタンスを選択します。Select All resources, and select the App Configuration store instance that you created in the quickstart.

  5. [Configuration Explorer](構成エクスプローラー) を選択して次のキーの値を更新します。Select Configuration Explorer, and update the values of the following keys:

    KeyKey ValueValue
    TestApp:Settings:BackgroundColorTestApp:Settings:BackgroundColor greengreen
    TestApp:Settings:FontColorTestApp:Settings:FontColor lightGraylightGray
    TestApp:Settings:MessageTestApp:Settings:Message Data from Azure App Configuration - now with live updates!Data from Azure App Configuration - now with live updates!
  6. ブラウザー ページを最新の情報に更新して新しい構成設定を確認します。Refresh the browser page to see the new configuration settings. 変更を反映するには、ブラウザー ページの複数の更新が必要な場合があります。More than one refresh of the browser page may be required for the changes to be reflected.

    クイック スタートのアプリ (ローカルで最新の情報に更新)

    注意

    構成設定は既定の有効期限 30 秒でキャッシュされるので、App Configuration ストアの設定に対する変更は、キャッシュの有効期限が切れたときにのみ、Web アプリに反映されます。Since the configuration settings are cached with a default expiration time of 30 seconds, any changes made to the settings in the App Configuration store would only be reflected in the web app when the cache has expired.

リソースをクリーンアップするClean up resources

次のチュートリアルに進む場合は、このクイックスタートで作成したリソースを再利用できるよう残しておいてください。If you plan to continue to the next tutorial, keep the resources you created in this quickstart for that you can reuse them.

クイック スタートのサンプル アプリケーションの使用を終える場合は、課金を避けるために、このクイック スタートで作成した Azure リソースを削除することができます。If you're finished with the quickstart sample application, delete the Azure resources you created in this quickstart to avoid charges.

重要

リソース グループを削除すると、元に戻すことができません。Deleting a resource group is irreversible. リソース グループとそのすべてのリソースは完全に削除されます。The resource group and all the resources in it are permanently deleted. 間違ったリソース グループやリソースをうっかり削除しないようにしてください。Make sure that you don't accidentally delete the wrong resource group or resources. このサンプルをホストするためのリソースを、保持したいリソースを含むリソース グループ内に作成した場合は、リソース グループを削除する代わりに、各リソースをそれぞれのウィンドウから個別に削除します。If you created the resources for hosting this sample inside a resource group that contains resources you want to keep, delete each resource individually from its respective pane instead of deleting the resource group.

  1. Azure portal にサインインし、 [リソース グループ] を選択します。Sign in to the Azure portal, and select Resource groups.
  2. [名前でフィルター] ボックスにリソース グループの名前を入力します。In the Filter by name box, enter the name of your resource group.
  3. 結果一覧からリソース グループを選択し、行を右クリックするか省略記号 ( ... ) ボタンを使用してコンテキスト メニューを開きます。In the result list, select the resource group, and either right-click the row or use the ellipsis (...) button to open the context menu.
  4. [リソース グループの削除] を選択します。Select Delete resource group.
  5. リソース グループの削除の確認を求めるメッセージが表示されます。You're asked to confirm the deletion of the resource group. 確認のためにリソース グループの名前を入力し、 [削除] を選択します。Enter the name of your resource group to confirm, and select Delete.

しばらくすると、リソース グループとそのすべてのリソースが削除されます。After a few moments, the resource group and all its resources are deleted.

次のステップNext steps

このチュートリアルでは、App Configuration から動的に構成設定を更新できるように ASP.NET Core Web アプリを設定しました。In this tutorial, you enabled your ASP.NET Core web app to dynamically refresh configuration settings from App Configuration. App Configuration へのアクセスを効率化する Azure マネージド ID を使用する方法については、次のチュートリアルに進んでください。To learn how to use an Azure managed identity to streamline the access to App Configuration, continue to the next tutorial.