チュートリアル:ASP.NET Core アプリで動的な構成を使用する

このチュートリアルでは、ASP.NET Core アプリで構成の動的な更新を有効にする方法について説明します。 これは、クイック スタートで紹介されている Web アプリに基づいています。 アプリでは、組み込みの構成キャッシュと更新機能に App Configuration プロバイダー ライブラリを利用します。 先に進む前に、App Configuration を使用した ASP.NET Core アプリの作成を完了しておいてください。

このチュートリアルでは、以下の内容を学習します。

前提条件

クイック スタート「App Configuration を使用して ASP.NET Core アプリを作成する」を完了します。

センチネル キーを追加する

''センチネル キー'' は、他のすべてのキーの変更を完了した後に更新するキーです。 センチネル キーをアプリで監視してください。 変更が検出されると、アプリによって構成の値がすべて更新されます。 このアプローチは、アプリの構成の一貫性を確保するのに役立ち、すべてのキーの変更を監視する場合と比べると、App Configuration ストアに対して行う全体的な要求の数が少なくなります。

1. Azure portal で App Configuration ストアを開き、Configuration Explorer >[作成] >[キーの値] を選択します。
2. [キー] に「TestApp:Settings:Sentinel」と入力します。 [値] には、「1」と入力します。 [ラベル] と [コンテンツの種類] は空にしておきます。
3. [適用] を選択します。

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

1. Program.cs を開き、クイックスタート中に追加した AddAzureAppConfiguration メソッドを更新します。 Microsoft Entra ID (推奨) または接続文字列を使用して App Configuration に接続できます。 次のコード スニペットは、Microsoft Entra ID を使用する場合を示しています。

   DefaultAzureCredential を使って、App Configuration ストアに対する認証を行います。 前提条件に記載されているクイックスタートを完了するときに、App Configuration データ閲覧者ロール資格情報を既に割り当てています。

   // Load configuration from Azure App Configuration
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       options.Connect(new Uri(endpoint), new DefaultAzureCredential());
               // Load all keys that start with `TestApp:` and have no label
               .Select("TestApp:*", LabelFilter.Null)
               // Configure to reload configuration if the registered sentinel key is modified
               .ConfigureRefresh(refreshOptions =>
                   refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
   });
   

   この Select メソッドは、キー名が TestApp で始まり、ラベルのないすべてのキー値を読み込むのため使用されます。 Select メソッドを複数回呼び出して、さまざまなプレフィックスやラベルをもつ構成を読み込むことができます。 1 つの App Configuration ストアを複数のアプリと共有する場合、このアプローチは、ストアからすべてを読み込むのではなく、現在のアプリに関連する構成のみを読み込むのに役立ちます。

   ConfigureRefresh メソッドでは、App Configuration ストア内で変更を監視するキーを登録します。 Register メソッドの refreshAll パラメーターは、登録されたキーが変更された場合に、Select メソッドで指定したすべての構成が再読み込みされることを示します。

   ヒント

   refreshOptions.SetCacheExpiration メソッドの呼び出しを追加して、構成の更新間隔の最小時間を指定できます。 今回の例では既定の値である 30 秒を使用します。 App Configuration ストアに対する要求の数を減らす必要がある場合は、より大きな値に調整します。

2. Azure App Configuration ミドルウェアをアプリのサービス コレクションに追加します。

   次のコードを使用して Program.cs を更新します。

   // Existing code in Program.cs
   // ... ...
   
   builder.Services.AddRazorPages();
   
   // Add Azure App Configuration middleware to the container of services.
   builder.Services.AddAzureAppConfiguration();
   
   // Bind configuration "TestApp:Settings" section to the Settings object
   builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

3. UseAzureAppConfiguration メソッドを呼び出します。 これにより、アプリで App Configuration ミドルウェアを使用して、自動的に構成を更新できます。

   次のコードを使用して Program.cs を更新します。

   // Existing code in Program.cs
   // ... ...
   
   var app = builder.Build();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/Error");
       app.UseHsts();
   }
   
   // Use Azure App Configuration middleware for dynamic configuration refresh.
   app.UseAzureAppConfiguration();
   
   // The rest of existing code in program.cs
   // ... ...
   

クイックスタート中に、ASP.NET Core のオプション パターンを使用するようにアプリを設定しました。 アプリの基になる構成が App Configuration から更新されると、IOptionsSnapshot<T> を介して取得した厳密に型指定された Settings オブジェクトが自動的に更新されます。 アプリの起動後に構成データが読み取られないため、動的構成更新が必要な場合は IOptions<T> を使用しないでください。

要求ドリブン構成の更新

構成の更新は、Web アプリで受信される要求によってトリガーされます。 アプリがアイドル状態の場合、更新は行われません。 アプリがアクティブ状態の場合、App Configuration ミドルウェアによって、ConfigureRefresh 呼び出しで更新するために登録したセンチネル キーまたは他のキーが監視されます。 ミドルウェアは、アプリで受信される要求ごとにトリガーされます。 ただし、ミドルウェアでは、設定したキャッシュの有効期限が過ぎたときに App Configuration で値を確認する要求のみを送信します。

• App Configuration に対する変更の検出の要求が失敗した場合、アプリではキャッシュされた構成が引き続き使用されます。 アプリへの新しい要求の受信がある間、変更を確認する新しい試行が定期的に行われます。
• 構成の更新は、アプリでの要求の受信の処理とは非同期的に行われます。 更新をトリガーした受信要求をブロックしたり、速度が低下することはありません。 更新をトリガーした要求では、更新された構成値が取得されない場合がありますが、それ以降の要求では新しい構成値が取得されます。
• ミドルウェアが確実にトリガーされるようにするには、要求パイプラインでできるだけ早く app.UseAzureAppConfiguration() メソッドを呼び出し、アプリで別のミドルウェアがそれをスキップしないようにします。

アプリをビルドしてローカルで実行する

1. .NET CLI を使用してアプリケーションをビルドするには、コマンド シェルで次のコマンドを実行します。

       dotnet build
   

2. ビルドが正常に完了したら、次のコマンドを実行して、Web アプリをローカルで実行します。

       dotnet run
   

3. ブラウザー ウィンドウを開いて、dotnet run 出力に表示される URL に移動します。

   

4. Azure portal にサインインします。 [すべてのリソース] を選択し、クイックスタートで作成した App Configuration ストアを選択します。

5. [構成エクスプローラー] を選択し、次のキーの値を更新します。 最後に必ずセンチネル キーを更新してください。

   キー	値
   TestApp:Settings:BackgroundColor	green
   TestApp:Settings:FontColor	lightGray
   TestApp:Settings:Message	Data from Azure App Configuration - now with live updates!
   TestApp:Settings:Sentinel	2

6. ブラウザーを数回更新します。 30 秒後にキャッシュが有効期限切れになると、ページには更新された内容が表示されます。

   

ログ記録と監視

ログは構成の更新時に出力され、App Configuration ストアから取得されたキー値と、アプリケーションに加えられた構成変更に関する詳細情報を含んでいます。

• services.AddAzureAppConfiguration() が呼び出されると、既定値 ILoggerFactory が自動的に追加されます。 App Configuration プロバイダーは、この ILoggerFactory を使用して ILogger のインスタンスを作成し、これらのログを出力します。 ASP.NET Core は既定でログに ILogger を使用するため、App Configuration プロバイダーのログを有効にするために追加のコード変更を行う必要はありません。

• ログはさまざまなログ レベルで出力されます。 既定のレベルは Information です。

  ログ レベル	説明
  デバッグ	ログには、アプリケーションが App Configuration ストアからの変更を監視するキーとキー値のラベルが含まれます。 この情報には、アプリケーションが既に読み込んだ内容と比較してキー値が変更されたかどうかも含まれます。 構成の変更が想定どおりに行われなかった場合にアプリケーションのトラブルシューティングを行うには、このレベルでログを有効にします。
  Information	ログには、構成の更新中に更新された構成設定のキーが含まれます。 機密データが漏洩しないように、構成設定の値はログから省略されます。 このレベルのログを監視して、アプリケーションが予想される構成変更を確実に取得できるようにします。
  警告	ログには、構成の更新中に発生したエラーと例外が含まれます。 構成プロバイダーはキャッシュされたデータを引き続き使用し、次回は構成を更新しようとするため、不定期な発生は無視してもかまいません。 このレベルでログを監視して、潜在的な問題を示す可能性のある繰り返し警告を確認できます。 たとえば、接続文字列をローテーションしたが、アプリケーションの更新を忘れたとします。

  Debug ログ レベルでログを有効にするには、次の例を appsettings.json ファイルに追加します。 この例は、他のすべてのログ レベルにも適用されます。

  "Logging": {
      "LogLevel": {
          "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
      }
  }
  

• ログ カテゴリは Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh です。これは各ログの前に表示されます。 各ログ レベルのログの例を次に示します。

  dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'
  
  info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Setting updated. Key:'ExampleKey'
  
  warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      A refresh operation failed while resolving a Key Vault reference.
  Key vault error. ErrorCode:'SecretNotFound' Key:'ExampleKey' Label:'ExampleLabel' Etag:'6LaqgBQM9C_Do2XyZa2gAIfj_ArpT52-xWwDSLb2hDo' SecretIdentifier:'https://examplevault.vault.azure.net/secrets/ExampleSecret'
  

ILogger の使用は、ASP.NET アプリケーションで推奨される方法であり、ILoggerFactory のインスタンスが存在する場合はログ ソースとして優先度付けされます。 ただし、ILoggerFactory が使用できない場合は、.NET Core アプリの手順に従ってログを有効にして構成することもできます。 詳細については、「.NET Core および ASP.NET Core でのログ記録」を参照してください。

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

この記事で作成したリソースを継続して使用しない場合は、ここで作成したリソース グループを削除して課金されないようにしてください。

1. Azure portal にサインインし、 [リソース グループ] を選択します。
2. [名前でフィルター] ボックスにリソース グループの名前を入力します。
3. 結果一覧でリソース グループ名を選択し、概要を表示します。
4. [リソース グループの削除] を選択します。
5. リソース グループの削除の確認を求めるメッセージが表示されます。 確認のためにリソース グループの名前を入力し、 [削除] を選択します。

しばらくすると、リソース グループとそのすべてのリソースが削除されます。

次のステップ

このチュートリアルでは、App Configuration から動的に構成設定を更新できるように ASP.NET Core Web アプリを設定しました。 App Configuration へのアクセスを効率化する Azure マネージド ID を使用する方法については、次のチュートリアルに進んでください。