ASP.NET Core アプリで Azure SDK for .NET を使用する

[アーティクル]
11/16/2024

Azure SDK for .NET を使用すると、ASP.NET Core アプリをさまざまな Azure サービスと統合できます。この記事では、ベストプラクティスと、ASP.NET Core アプリで Azure SDK for .NET を採用する手順について説明します。学習内容は次のとおりです。

依存関係の挿入用にサービスを登録します。
パスワードやシークレットを使用せずに Azure に対して認証します。
一元化された標準化された構成を実装します。
ログ記録や再試行など、一般的な Web アプリの懸念事項を構成します。

一般的な Azure SDK クライアントライブラリを調べる

ASP.NET Azure サービスに接続するコアアプリは、通常、次の Azure SDK クライアントライブラリによって異なります。

Microsoft.Extensions.Azure は、依存関係挿入サービスコレクションにクライアントを登録するヘルパーメソッドを提供し、ログ記録の設定、DI サービスの有効期間の処理、認証資格情報の管理など、さまざまな懸念事項を処理します。
Azure.Identity では、Azure SDK 全体で Microsoft Entra ID 認証のサポートが有効になります。 TokenCredential 実装のセットを提供して、Microsoft Entra 認証をサポートする Azure SDK クライアントを構築します。
Azure.<service-namespace>Azure.Storage.Blobs や Azure.Messaging.ServiceBus などのライブラリは、特定の Azure サービスに接続して使用するのに役立つサービスクライアントとその他の種類を提供します。これらのライブラリの完全なインベントリについては、Azure.Core を使用 Librariesを参照してください。

前のセクションでは、これらのライブラリを使用する ASP.NET Core アプリケーションを実装する方法について説明します。

AZURE SDK クライアントを DI サービスコレクションに登録する

Azure SDK for .NET クライアントライブラリは、アプリを Azure Blob Storage や Azure Key Vault などの Azure サービスに接続するためのサービスクライアントを提供します。これらのサービスをアプリの Program.cs ファイルの依存関係コンテナーに登録して、 dependency インジェクションで使用できるようにします。

必要なサービスを登録するには、次の手順を実行します。

Microsoft.Extensions.Azure パッケージを追加します。
```
dotnet add package Microsoft.Extensions.Azure
```

関連する Azure.* サービスクライアントパッケージを追加します。

dotnet add package Azure.Security.KeyVault.Secrets
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Messaging.ServiceBus

アプリのProgram.cs ファイルで、Microsoft.Extensions.Azure ライブラリから AddAzureClients 拡張メソッドを呼び出して、各 Azure サービスと通信するクライアントを登録します。一部のクライアントライブラリでは、Azure サービス機能の特定のサブグループに対して追加の subclients が提供されます。このようなサブクライアントは、 AddClient 拡張メソッドを使用して依存関係の挿入に登録できます。

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

登録済みクライアントを ASP.NET Core アプリコンポーネント、サービス、または API エンドポイントに挿入します。

最小限の API
Blazor

app.MapGet("/reports", async (
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory) =>
{
    // Create the named client
    ServiceBusSender serviceBusSender = senderFactory.CreateClient("queue1");

    await serviceBusSender.SendMessageAsync(new ServiceBusMessage("Hello world"));

    // Use the blob client
    BlobContainerClient containerClient
        = blobServiceClient.GetBlobContainerClient("reports");

    List<BlobItem> reports = new();
    await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
    {
        reports.Add(blobItem);
    }

    return reports;
})
.WithName("GetReports");

@page "/"
@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models
@using Azure.Messaging.ServiceBus
@using Microsoft.Extensions.Azure;

<h1>Reports</h1>

<ul>
    @foreach (var report in reports)
    {
        <li>@report.Name</li>
    }
</ul>

@code {
    List<BlobItem> reports = new();

    private BlobServiceClient _blobServiceClient;
    private ServiceBusSender _serviceBusSender;

    public Home(
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory)
    {
         _blobServiceClient = blobServiceClient;
        _serviceBusSender = senderFactory.CreateClient("queue1");
    }

詳細については、Azure SDK for .NET を使用した Dependency インジェクションを参照してください。

Microsoft Entra ID を使用して認証する

Microsoft Entra ID を使用したトークンベースの認証は、Azure サービスへの要求を認証するための推奨される方法です。これらの要求を承認するために、 Azure ロールベースのアクセス制御 (RBAC) は、ユーザーの Microsoft Entra ID と割り当てられたロールに基づいて Azure リソースへのアクセスを管理します。

前述のトークンベースの認証サポートには、 Azure Identity ライブラリを使用します。このライブラリには、セキュリティで保護された接続の構成を簡略化するための DefaultAzureCredential などのクラスが用意されています。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。このアプローチを採用すると、環境固有のコードを実装することなく、異なる環境 (ローカルと運用環境) で異なる認証方法をアプリに使用できます。これらのトピックの詳細については、Azure SDK for .NET ドキュメントの「 Authentication 」セクションを参照してください。

Note

多くの Azure サービスでは、キーを使用して要求を承認することもできます。ただし、この方法は慎重に使用する必要があります。開発者は、セキュリティで保護されていない場所にアクセス・キーを公開しないように注意する必要があります。アクセスキーを持つすべてのユーザーは、関連付けられている Azure リソースに対する要求を承認できます。

Azure.Identity パッケージを追加します。
```
dotnet add package Azure.Identity
```
アプリのProgram.cs ファイルで、Microsoft.Extensions.Azure ライブラリから UseCredential 拡張メソッドを呼び出して、登録されているすべての Azure サービスクライアントの共有DefaultAzureCredential インスタンスを設定します。
```
builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});
```
DefaultAzureCredential は、現在の環境で使用可能な資格情報を検出し、それらを使用して Azure サービスに対する認証を行います。 DefaultAzureCredentialが資格情報をスキャンする順序と場所については、「DefaultAzureCredential の概要を参照してください。共有 DefaultAzureCredential インスタンスを使用すると、基になるトークンキャッシュが確実に使用されます。これにより、新しいトークンの要求が少ないため、アプリケーションの回復性とパフォーマンスが向上します。

構成の適用

Azure SDK サービスクライアントは、既定の動作を変更するための構成をサポートします。サービスクライアントを構成するには、次の 2 つの方法があります。

JSON 構成ファイルは、環境間のアプリデプロイの違いを簡単に管理できるため、一般に推奨されるアプローチです。
インラインコード構成は、サービスクライアントを登録するときに適用できます。たとえば、クライアントとサブクライアントの登録セクションでは、URI 変数をクライアントコンストラクターに明示的に渡しました。

IConfiguration優先順位規則は、Configuration Providers ドキュメントで詳しく説明されているMicrosoft.Extensions.Azure拡張メソッドによって尊重されます。

適切な環境に JSON ファイル構成を使用するようにアプリを更新するには、次のセクションの手順を実行します。開発設定には appsettings.Development.json ファイル、運用環境の設定には appsettings.Production.json ファイルを使用します。 ClientOptions クラスのパブリックプロパティである名前の構成設定を JSON ファイルに追加できます。

登録済みサービスを構成する

強調表示されたサービス構成を使用して、アプリ内の appsettings.<environment>.json ファイルを更新します。
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}
```
上記の JSON の例では、次のように指定されています。
- 最上位のキー名 ( KeyVault、 ServiceBus、および Storage) は、コードから構成セクションを参照するために使用される任意の名前です。これらの名前を拡張メソッド AddClient 渡して、特定のクライアントを構成します。他のすべてのキー名は特定のクライアントオプションにマップされ、JSON シリアル化は大文字と小文字を区別せずに実行されます。
- KeyVault:VaultUri、ServiceBus:Namespace、およびStorage:ServiceUriのキー値は、それぞれ、SecretClient(Uri, TokenCredential, SecretClientOptions)、ServiceBusClient(String)、およびBlobServiceClient(Uri, TokenCredential, BlobClientOptions)コンストラクターのオーバーロードの引数にマップされます。 UseCredential(TokenCredential) メソッド呼び出しを介して既定値 TokenCredential が設定されるため、コンストラクターの TokenCredential バリアントが使用されます。

Program.cs ファイルを更新して、IConfigurationを使用して JSON ファイル構成を取得し、サービス登録に渡します。

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

Azure の既定値と再試行を構成する

既定の Azure クライアント構成をグローバルに、または特定のサービスクライアントに対して変更できます。たとえば、さまざまな再試行設定が必要な場合や、別のサービス API バージョンを使用する場合です。再試行の設定はグローバルに、またはサービスごとに行うことができます。

登録されているすべての Azure クライアントが使用する新しい既定の再試行ポリシーなど、既定の Azure 設定を設定するように構成ファイルを更新します。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

Program.cs ファイルで、ConfigureDefaults拡張メソッドを呼び出して既定の設定を取得し、サービスクライアントに適用します。

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

    // Register a subclient for each Azure Service Bus Queue
    string[] queueNames = [ "queue1", "queue2" ];
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    clientBuilder.UseCredential(new DefaultAzureCredential());

    // Set up any default settings
    clientBuilder.ConfigureDefaults(
        builder.Configuration.GetSection("AzureDefaults"));
});

ログの構成

Azure SDK for .NET クライアントライブラリでは、クライアントライブラリ操作をログに記録して、Azure サービスへの要求と応答を監視できます。クライアントライブラリでは、再試行、トークン取得、さまざまなクライアントからのサービス固有のイベントなど、さまざまなイベントをログに記録することもできます。 AddAzureClients拡張メソッドを使用して Azure SDK クライアントを登録すると、AzureEventSourceLogForwarderが依存関係挿入コンテナーに登録されます。 AzureEventSourceLogForwarderは、Azure SDK イベントソースからログメッセージをILoggerFactoryに転送して、ログ記録に標準の ASP.NET Core ログ記録構成を使用できるようにします。

次の表は、Azure SDK for .NET の EventLevel を ASP.NET Core の LogLevel にマップする方法を示しています。これらのトピックとその他のシナリオの詳細については、「 .NET 用 Azure SDK を使用したログ記録および Azure SDK for .NET を使用した Dependency インジェクションを参照してください。

Azure SDK `EventLevel`	ASP.NET Core `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

構成認証セクションで説明されているのと同じ JSON 構成を使用して、既定のログレベルやその他の設定を変更できます。たとえば、次のようにLogging:LogLevel:Azure.Messaging.ServiceBus キーを設定して、ServiceBusClientログレベルをDebugに切り替えます。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

次の方法で共有

ASP.NET Core アプリで Azure SDK for .NET を使用する

一般的な Azure SDK クライアントライブラリを調べる

AZURE SDK クライアントを DI サービスコレクションに登録する

Microsoft Entra ID を使用して認証する

構成の適用

登録済みサービスを構成する

Azure の既定値と再試行を構成する

ログの構成

その他のリソース

次の方法で共有

ASP.NET Core アプリで Azure SDK for .NET を使用する

一般的な Azure SDK クライアント ライブラリを調べる

AZURE SDK クライアントを DI サービス コレクションに登録する

Microsoft Entra ID を使用して認証する

構成の適用

登録済みサービスを構成する

Azure の既定値と再試行を構成する

ログの構成

その他のリソース

一般的な Azure SDK クライアントライブラリを調べる

AZURE SDK クライアントを DI サービスコレクションに登録する