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

[アーティクル]
02/20/2024

App Configuration .NET プロバイダーライブラリは、アプリケーションを再起動させることなく必要に応じて構成を更新することをサポートします。このチュートリアルでは、自分が作成するコードに、構成の動的更新を実装する方法について説明します。これは、クイックスタートで紹介されているアプリに基づいています。先に進む前に、「App Configuration を使用して .NET アプリを作成する」を完了しておく必要があります。

このチュートリアルの手順は、任意のコードエディターを使用して実行できます。推奨のエディターは Visual Studio Code です (Windows、macOS、および Linux プラットフォームで使用できます)。

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

App Configuration ストアへの変更に合わせて構成を更新するように .NET アプリを設定します。
最新の構成をアプリケーションに取り込む。

前提条件

Azure サブスクリプションをお持ちでない場合は、開始する前に Azure 無料アカウントを作成してください。

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

アクティビティドリブン構成の更新

Program.cs を開き、ファイルを次のコードで更新します。

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(TimeSpan.FromSeconds(10));
            });

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

// Wait for the user to press Enter
Console.ReadLine();

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

ConfigureRefresh メソッドでは、変更の監視のために App Configuration ストア内のキーが登録されます。 Register メソッドには、登録済みのキーが変更された場合にすべての構成値を更新するかどうかを示すために使用できる、省略可能なブール型パラメーター refreshAll があります。この例では、キー TestApp:Settings:Message のみが更新されます。 SetCacheExpiration メソッドでは、構成の変更を確認するために新しい要求が App Configuration に対して行われるまでに経過する必要がある最小時間を指定します。この例では、既定の有効期限である 30 秒をオーバーライドし、デモンストレーションの目的で代わりに 10 秒を指定しています。

ConfigureRefresh メソッドを単独で呼び出しても、構成は自動的に更新されません。インターフェイス IConfigurationRefresher から TryRefreshAsync メソッドを呼び出して、更新をトリガーします。この設計は、アプリケーションがアイドル状態の場合でも App Configuration に要求が送信されるのを回避することを目的としています。 TryRefreshAsync 呼び出しは、アプリケーションをアクティブとみなす場所に含める必要があります。たとえば、受信メッセージ、注文、複雑なタスクの反復を処理するときなどです。また、アプリケーションが常にアクティブである場合は、タイマー内に含めることができます。この例では、Enter キーを押すたびに TryRefreshAsync を呼び出します。何らかの理由で呼び出し TryRefreshAsync が失敗した場合でも、アプリケーションではキャッシュされた構成が引き続き使用されます。構成されたキャッシュの有効期限が切れて、TryRefreshAsync 呼び出しがアプリケーションアクティビティによって再度トリガーされると、もう 1 回試行されます。 TryRefreshAsync の呼び出しは、構成されたキャッシュの有効期限が過ぎる前には操作を実行しないので、頻繁に呼び出された場合でも、パフォーマンスへの影響は最小限になります。

依存関係の挿入を使った構成の更新

前のコードでは、IConfigurationRefresher のインスタンスを手動で保存して TryRefreshAsync を呼び出しています。また、依存関係の挿入を使ってサービスを解決している場合は、以下の手順を参照できます。

IServiceCollection 上で AddAzureAppConfiguration を呼び出すことで、必要な App Configuration サービスを登録します。

Program.cs に次のコードを追加します。
```
// Existing code in Program.cs
// ... ...

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();
```

サービスコレクションから IConfigurationRefresherProvider のインスタンスを解決し、その各リフレッシャー上で TryRefreshAsync を呼び出すことで、構成を更新します。

class SampleConfigRefresher
{
    private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;

    public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
    {
        _refreshers = refresherProvider.Refreshers;
    }

    public async Task RefreshConfiguration()
    {
        foreach (var refresher in _refreshers)
        {
            _ = refresher.TryRefreshAsync();
        }
    }
}

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

ConnectionString という名前の環境変数に、App Configuration ストアへのアクセスキーを設定します。 Windows コマンドプロンプトを使用する場合は、次のコマンドを実行してコマンドプロンプトを再起動し、変更が反映されるようにします。
```
 setx ConnectionString "connection-string-of-your-app-configuration-store"
```
Windows PowerShell を使用する場合は、次のコマンドを実行します。
```
 $Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
macOS または Linux を使用する場合は、次のコマンドを実行します。
```
 export ConnectionString='connection-string-of-your-app-configuration-store'
```
次のコマンドを実行して、コンソールアプリをビルドします。
```
 dotnet build
```
ビルドが正常に完了したら、次のコマンドを実行して、アプリをローカルで実行します。
```
 dotnet run
```
Azure portal にサインインします。 [すべてのリソース] を選択し、クイックスタートで作成した App Configuration ストアインスタンスを選択します。
[Configuration Explorer]\(構成エクスプローラー) を選択して次のキーの値を更新します。

Key 値

TestApp:Settings:Message Azure App Configuration からのデータ - 更新済み
Enter キーを押して更新をトリガーし、コマンドプロンプトウィンドウまたは PowerShell ウィンドウに更新された値を表示します。

Note

更新操作の構成を指定するときに SetCacheExpiration メソッドを使ってキャッシュの有効期限を 10 秒に設定したため、構成設定の値は、その設定の前回の更新から少なくとも 10 秒が経過した場合にのみ更新されます。

Key	値
TestApp:Settings:Message	Azure App Configuration からのデータ - 更新済み

ログ記録と監視

ログは構成の更新時に出力され、App Configuration ストアから取得されたキー値と、アプリケーションに加えられた構成変更に関する詳細情報を含んでいます。 ASP.NET Core アプリケーションがある場合は、ASP.NET Core のログ記録と監視に関するこちらの手順を参照してください。それ以外の場合は、Azure SDK を使用したログ記録の手順に従ってログを有効にすることができます。

ログは、さまざまなイベントレベルで出力されます。既定のレベルは Informational です。

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

Verbose イベントレベルでログ記録を有効にするには、次の例のように EventLevel.Verbose パラメーターを指定します。これらの手順は、他のすべてのイベントレベルにも適用されます。この例では、Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh カテゴリのみのログも有効にします。

using var listener = new AzureEventSourceListener((eventData, text) =>
{
    if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
    {
        Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
    }
}, EventLevel.Verbose);

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

[Verbose] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

[Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Setting updated. Key:'ExampleKey'

[Warning] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
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'

注意

ログ記録は、次のいずれかのパッケージのバージョン 6.0.0 以降を使用している場合に利用できます。

Microsoft.Extensions.Configuration.AzureAppConfiguration
Microsoft.Azure.AppConfiguration.AspNetCore
Microsoft.Azure.AppConfiguration.Functions.Worker

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

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

重要

リソースグループを削除すると、元に戻すことができません。リソースグループとそのすべてのリソースは完全に削除されます。間違ったリソースグループやリソースをうっかり削除しないようにしてください。この記事のリソースを、保持したい他のリソースを含むリソースグループ内に作成した場合は、リソースグループを削除する代わりに、各リソースをそれぞれのペインから個別に削除します。

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

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

次のステップ

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

マネージド ID の統合

次の方法で共有

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

前提条件

アクティビティドリブン構成の更新

依存関係の挿入を使った構成の更新

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

ログ記録と監視

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

アクティビティ ドリブン構成の更新

依存関係の挿入を使った構成の更新

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

ログ記録と監視

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

次のステップ

フィードバック

その他のリソース

アクティビティドリブン構成の更新