在 ASP.NET Core 應用程式中使用適用於 .NET 的 Azure SDK

發行項
11/16/2024

適用於 .NET 的 Azure SDK 可讓 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 的連結庫。

在前面的各節中，您將探索如何實作使用這些連結庫的 ASP.NET Core 應用程式。

向 DI 服務集合註冊 Azure SDK 用戶端

適用於 .NET 的 Azure SDK 用戶端連結庫提供服務用戶端，以將您的應用程式連線到 Azure 服務，例如 Azure Blob 儲存體和 Azure 金鑰保存庫。在應用程式的檔案中 Program.cs 向相依性容器註冊這些服務，以透過相依性插入加以使用。

完成下列步驟以註冊您需要的服務：

新增 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 服務功能的特定子群組提供其他子元件。您可以透過 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 的相依性插入。

使用 Microsoft Entra ID 進行驗證

使用 Microsoft Entra ID 進行令牌型驗證是向 Azure 服務驗證要求的建議方法。為了授權這些要求， Azure 角色型訪問控制（RBAC）會根據使用者的 Microsoft Entra 身分識別和指派的角色來管理對 Azure 資源的存取。

針對上述令牌型驗證支援使用 Azure 身分識別連結庫。連結庫提供類別，例如 DefaultAzureCredential 簡化設定安全連線。 DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應該使用哪個方法。此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法，而不需要實作環境特有的程式碼。如需這些主題的詳細資訊，請流覽 Azure SDK for .NET 檔的驗證一節。

注意

許多 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 服務客戶端支援設定來變更其預設行為。有兩種方式可以設定服務用戶端：

JSON 組態檔通常是建議的方法，因為它們可簡化環境間應用程式部署的管理差異。
當您註冊服務用戶端時，可以套用內嵌程式代碼組態。例如，在 [ 註冊用戶端和子用戶端] 區段中，您明確將 URI 變數傳遞至用戶端建構函式。

IConfiguration 優先順序規則會受到 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 範例中:
- 最上層索引鍵名稱、 KeyVaultServiceBus和 Storage是任意名稱，用來參考程式碼中的組態區段。您將將這些名稱傳遞至 AddClient 擴充方法，以設定指定的用戶端。所有其他索引鍵名稱都會對應至特定的用戶端選項，並以不區分大小寫的方式執行 JSON 串行化。
- KeyVault:VaultUri、 ServiceBus:Namespace和索引鍵值分別對應至、 ServiceBusClient(String)和 BlobServiceClient(Uri, TokenCredential, BlobClientOptions) Storage:ServiceUri 建構函式多載的SecretClient(Uri, TokenCredential, SecretClientOptions)自變數。會使用建構函式的 TokenCredential 變體，因為預設 TokenCredential 是透過 UseCredential(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.csConfigureDefaults，呼叫擴充方法以擷取預設設定，並將其套用至您的服務用戶端：

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"));
});

設定記錄

適用於 .NET 的 Azure SDK 用戶端連結庫可以記錄用戶端連結庫作業，以監視對 Azure 服務的要求和回應。用戶端連結庫也可以記錄各種其他事件，包括重試、令牌擷取，以及來自各種客戶端的服務特定事件。當您使用 AddAzureClients 擴充方法註冊 Azure SDK 用戶端時， AzureEventSourceLogForwarder 會向相依性插入容器註冊。會將 AzureEventSourceLogForwarder 記錄訊息從 Azure SDK 事件來源轉送至 ILoggerFactory ，讓您能夠使用標準 ASP.NET Core 記錄組態進行記錄。

下表描述適用於 .NET 的 Azure SDK 如何描述 EventLevel 對應至 ASP.NET CoreLogLevel。如需這些主題和其他案例的詳細資訊，請參閱使用適用於 .NET 的 Azure SDK 和 Azure SDK for .NET 的相依性插入進行記錄。

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"
  }
}

共用方式為