共用方式為

.NET Aspire Azure Key Vault 整合

  • 發行項

在本文中，您將瞭解如何使用 .NET AspireAzure Key Vault 整合。 Aspire.Azure.Key.Vault 整合連結庫可用來在 DI 容器中註冊 SecretClient，以連線到 Azure Key Vault。 它也會啟用對應的健康檢查、日誌記錄和遙測。

開始使用

若要開始使用 .NET AspireAzure Key Vault 整合，請安裝 📦Aspire。Azure。Security.KeyVaultclient-consuming 專案中的 NuGet 套件，也就是使用 Azure Key Vaultclient的應用程式專案。

dotnet add package Aspire.Azure.Security.KeyVault

如需詳細資訊，請參閱 dotnet add package 或 在 .NET 應用程式中管理套件相依性。

範例使用方式

下列各節說明各種範例用法。

將機密資訊新增至配置

在 client專案的 Program.cs 檔案中，呼叫 AddAzureKeyVaultSecrets 擴充功能，將 Azure Key Vault 中的機密資訊新增至應用程式的設定。 方法會採用連接名稱參數。

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

然後，您可以透過一般 IConfiguration API 擷取機密。 例如，若要從服務擷取秘密：

public class ExampleService(IConfiguration configuration)
{
    string secretValue = configuration["secretKey"];
    // Use secretValue ...
}

使用 SecretClient

或者，您可以使用 SecretClient 按需提取機密信息。 在 client取用專案的 Program.cs 檔案中，呼叫 AddAzureKeyVaultClient 擴展名，以註冊 SecretClient，以透過相依性插入容器使用。

builder.AddAzureKeyVaultClient("secrets");

接著，您可以使用依賴注入來擷取 SecretClient 實體。 例如，若要從服務擷取 client：

public class ExampleService(SecretClient client)
{
    // Use client...
}

應用程式主機使用方式

若要將 Azure Key Vault 主機支援新增至您的 IDistributedApplicationBuilder，請在 應用程式主機 專案中安裝 📦Aspire.Hosting.AzureKeyVault NuGet 套件。

dotnet add package Aspire.Hosting.Azure.KeyVault

在應用程式主機專案中，註冊 Azure Key Vault 整合，並使用下列方法取用服務：

var builder = DistributedApplication.CreateBuilder(args);

var secrets = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureKeyVault("secrets")
    : builder.AddConnectionString("secrets");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(secrets)

上述程式代碼會根據執行內容，有條件地將 Azure Key Vault 資源新增至專案。 如果應用程式主機以發佈模式執行，則會新增資源，否則會將連接字串新增至現有的資源。

配置

.NET Aspire Azure Key Vault 整合提供多個選項，可根據專案的需求和慣例來設定 SecretClient。

使用組態提供者

.NET Aspire Azure Key Vault 整合支援 Microsoft.Extensions.Configuration。 它會使用 Aspire:Azure:Security:KeyVault 金鑰，從 appsettings.json 或其他組態檔載入 AzureSecurityKeyVaultSettings。

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "VaultUri": "YOUR_VAULT_URI",
          "DisableHealthChecks": false,
          "DisableTracing": true,
          "ClientOptions": {
            "DisableChallengeResourceVerification": true
          }
        }
      }
    }
  }
}

如果您在 appsettings.json 檔案的 [Aspire:Azure:Security:KeyVault] 區段中設定組態，您可以直接呼叫 方法 AddAzureKeyVaultSecrets 而不傳遞任何參數。

使用內聯委派

您也可以傳遞 Action<AzureSecurityKeyVaultSettings> 委派來設定部分或所有內嵌選項，例如設定 VaultUri：

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static settings => settings.VaultUri = new Uri("YOUR_VAULTURI"));

提示

AddAzureKeyVaultSecrets API 名稱造成一點混淆。 方法用於配置 SecretClient，而不是將秘密新增到配置設定中。

您也可以使用 Action<IAzureClientBuilder<SecretClient, SecretClientOptions>> 委派來設定 SecretClientOptions，這是 AddAzureKeyVaultSecrets 方法的第二個參數。 例如，若要設定 KeyClientOptions.DisableChallengeResourceVerification 標識碼來識別 client：

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.DisableChallengeResourceVerification = true))

組態選項

下列可設定的選項會透過 AzureSecurityKeyVaultSettings 類別公開：

名字 描述
VaultUri client 運作之保存庫的 URI。 在 Azure 入口網站中顯示為「DNS 名稱」。
Credential 用於對 Azure Key Vault進行驗證的憑證。
DisableHealthChecks 一個布林值，表示是否已停用 Key Vault 的健康檢查。
DisableTracing 一個布爾值，指出 OpenTelemetry 追蹤是否被停用。

健康檢查

根據預設，.NET.NET Aspire 整合默認會為所有服務啟用 健康檢查。 如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

.NET Aspire Azure Key Vault 整合包含下列健康檢查：

  • 新增 AzureKeyVaultSecretsHealthCheck 健康檢查，這會嘗試連線並查詢 Key Vault
  • 與 /health HTTP 端點整合，該端點規定所有已註冊的健康檢查必須通過，應用程式才會被視為準備好接受流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和計量組態，有時稱為 可檢視性要素。 如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。 視支援服務而定，某些整合可能只支援其中一些功能。 例如，某些整合支援記錄和追蹤，但不支援計量。 您也可以使用 組態 一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire Azure Key Vault 整合會使用下列記錄類別：

  • Azure.Core
  • Azure.Identity

追蹤

.NET Aspire Azure Key Vault 整合會使用 OpenTelemetry發出下列追蹤活動：

  • Azure.Security.KeyVault.Secrets.SecretClient

指標

.NET Aspire Azure Key Vault 整合目前因 Azure SDK 的限制，預設狀態下不支援度量標準。

另請參閱