.NET Aspire Azure Key Vault 集成

2025-06-30

包含： 托管集成 —&— Client 集成

Azure Key Vault 是一项云服务，用于安全地存储和访问机密。 .NET AspireAzure Key Vault 集成使你能够从 Azure Key Vault 应用程序连接到 .NET 实例。

托管集成

托管集成 Azure Key Vault 将 Key Vault 资源建模为 AzureKeyVaultResource 类型。若要访问此类型和 API 以在应用主机项目中表达它们，请安装 📦Aspire.Hosting.Azure.KeyVault NuGet 包：

.NET CLI
包引用

dotnet add package Aspire.Hosting.Azure.KeyVault

<PackageReference Include="Aspire.Hosting.Azure.KeyVault"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或管理 .NET 应用程序中的包依赖项。

添加 Azure Key Vault 资源

在应用主机项目中，对生成器实例调用 AddAzureKeyVault 以添加 Azure Key Vault 资源：

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddAzureKeyVault("key-vault");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyVault);

// After adding all resources, run the app...

WithReference 方法在 ExampleProject 中配置一个名为 "key-vault"的连接。

重要

默认情况下，AddAzureKeyVault 配置 Key Vault 管理员内置角色。

提示

调用 AddAzureKeyVault时，它会隐式调用 AddAzureProvisioning，这增加了在应用启动期间动态生成 Azure 资源的支持。应用程序必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置。

预配生成的 Bicep

如果你不熟悉 Bicep，它是一种领域专用语言，用于定义 Azure 资源。使用 .NET.NET Aspire，您不需要手动编写 Bicep，预配 API 会为您自动生成 Bicep。发布应用时，生成的 Bicep 文件将会与清单文件一同输出。添加 Azure Key Vault 资源时，会生成以下 Bicep：

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: take('keyvault-${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    tenantId: tenant().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
  }
  tags: {
    'aspire-resource-name': 'key-vault'
  }
}

output vaultUri string = key_vault.properties.vaultUri

output name string = key_vault.name

前述的 Bicep 是一个配置 Azure Key Vault 资源的模块。此外，在单独的模块中为 Azure 资源创建角色分配：

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param key_vault_outputs_name string

param principalType string

param principalId string

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: key_vault_outputs_name
}

resource key_vault_KeyVaultSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
    principalType: principalType
  }
  scope: key_vault
}

生成的 Bicep 是一个起点，并受到 C# 中预配基础结构变化的影响。对 Bicep 文件进行的自定义将直接被覆盖，因此请通过 C# 预配 API 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。这类型通过使用 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API 提供用于配置 Azure 资源的流畅 API 来允许自定义生成的 Bicep。例如，可以配置 sku、RBAC、tags等。以下示例演示如何自定义 Azure Key Vault 资源：

builder.AddAzureKeyVault("key-vault")
    .ConfigureInfrastructure(infra =>
    {
        var keyVault = infra.GetProvisionableResources()
                            .OfType<KeyVaultService>()
                            .Single();

        keyVault.Properties.Sku = new()
        {
            Family = KeyVaultSkuFamily.A,
            Name = KeyVaultSkuName.Premium,
        };
        keyVault.Properties.EnableRbacAuthorization = true;
        keyVault.Tags.Add("ExampleKey", "Example value");
    });

前面的代码：

链接对 ConfigureInfrastructure API 的调用：
- infra 参数是 AzureResourceInfrastructure 类型的实例。
- 通过调用 GetProvisionableResources() 方法检索可预配资源。
- 单个 KeyVaultService 资源已被检索。
- Sku 属性设置为新的 KeyVaultSku 实例。
- KeyVaultProperties.EnableRbacAuthorization 属性设置为 true。
- 标记将添加到资源中，其键为 ExampleKey，值为 Example value。

还有更多配置选项可用于自定义 Key Vault 资源。有关详细信息，请参阅 Azure.Provisioning.KeyVault 和 Azure。预配自定义。

连接到现有 Azure Key Vault 实例

你可能想连接到一个现有的 Azure AI Key Vault 实例。你可以链接调用以标注你的 AzureKeyVaultResource 现有资源：

var builder = DistributedApplication.CreateBuilder(args);

var existingKeyVaultName = builder.AddParameter("existingKeyVaultName");
var existingKeyVaultResourceGroup = builder.AddParameter("existingKeyVaultResourceGroup");

var keyvault = builder.AddAzureKeyVault("ke-yvault")
                    .AsExisting(existingKeyVaultName, existingKeyVaultResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyvault);

// After adding all resources, run the app...

有关将 Azure Key Vault 资源视为现有资源的详细信息，请参阅 “使用现有 Azure 资源”。

注释

或者，可以选择向应用主机添加连接字符串，而不是表示 Azure Key Vault 资源。此方法属于弱类型，不适用于角色分配或基础结构自定义。有关详细信息，请参阅添加包含连接字符串的现有 Azure 资源。

Client 集成

若要开始进行 .NET AspireAzure Key Vault 客户端集成，请在使用客户端的项目中安装 📦Aspire.Microsoft.Azure.Security.KeyVault NuGet 包，此项目是使用 Azure Key Vault 客户端的应用程序项目。

.NET CLI
包引用

dotnet add package Aspire.Azure.Security.KeyVault

<PackageReference Include="Aspire.Azure.Security.KeyVault"
                  Version="*" />

客户端集成提供两种方法来从 Azure Key Vault访问密钥。

使用 IConfiguration 或 IOptions<T> 模式将机密添加到应用配置。
使用 SecretClient 按需检索机密。

将机密添加到配置

在客户端使用项目的 Program.cs 文件中，对 AddAzureKeyVaultSecrets 调用 IConfiguration 扩展方法，将机密添加为应用的配置的一部分。该方法采用连接名称参数。

builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault");

注释

AddAzureKeyVaultSecrets API 名称引起了一点混淆。该方法用于根据给定的连接名称配置 SecretClient，它不用于向配置添加机密。

提示

connectionName 参数必须与在应用主机项目中添加 Azure Key Vault 资源时使用的名称匹配。有关详细信息，请参阅添加 Azure Key Vault 资源。

然后，你可以通过普通的 IConfiguration API 检索基于机密的配置值，甚至可以通过绑定到具有选项模式的强类型的类来进行检索。若要从已向依赖项注入容器注册的示例服务类检索机密，请考虑以下代码片段：

检索 `IConfiguration` 实例

public class ExampleService(IConfiguration configuration)
{
    // Use configuration...
    private string _secretValue = configuration["SecretKey"];
}

前面的示例假定你还注册了 IConfiguration 实例用于依赖项的注入。有关详细信息，请参阅 .NET中的依赖关系注入。

检索 `IOptions<T>` 实例

public class ExampleService(IOptions<SecretOptions> options)
{
    // Use options...
    private string _secretValue = options.Value.SecretKey;
}

前面的示例假定你已配置 SecretOptions 类以用于选项模式。有关详细信息，请参阅 .NET中的选项模式。

以下方案可以选择使用其他 AddAzureKeyVaultSecrets API 参数：

Action<AzureSecurityKeyVaultSettings>? configureSettings：以内联方式设置部分或全部选项。
Action<SecretClientOptions>? configureClientOptions：以内联方式设置 SecretClientOptions。
AzureKeyVaultConfigurationOptions? options：以内联方式配置 AzureKeyVaultConfigurationOptions。

添加 Azure 机密客户端

或者，你可以直接使用 SecretClient 来按需检索机密。这需要略有不同的注册 API。

在客户端使用项目的 Program.cs 文件中，调用 AddAzureKeyVaultClient 实例上的 IHostApplicationBuilder 扩展，以注册 SecretClient，以便通过依赖项注入容器使用。

builder.AddAzureKeyVaultClient(connectionName: "key-vault");

提示

connectionName 参数必须与在应用主机项目中添加 Azure Key Vault 资源时使用的名称匹配。有关详细信息，请参阅添加 Azure Key Vault 资源。

将 SecretClient 添加到生成器后，可以使用依赖项注入获取 SecretClient 实例。例如，若要从示例服务检索客户端，请将其定义为构造函数参数，并确保 ExampleService 类注册到依赖项注入容器：

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

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加有密钥的 Azure Key Vault 客户端

在某些情况下，可能需要使用不同的连接名称注册多个 SecretClient 实例。若要注册密钥 Azure Key Vault 客户端，请调用 AddKeyedAzureKeyVaultClient 方法：

builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles");
builder.AddKeyedAzureKeyVaultClient(name: "admin-portal");

然后，可以使用依赖项注入检索 SecretClient 实例。例如，若要从示例服务检索客户端：

public class ExampleService(
    [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient,
    [FromKeyedServices("admin-portal")] SecretClient adminPortalClient)
{
    // Use clients...
}

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

.NET AspireAzure Key Vault 集成提供了多个选项，用于根据项目的要求和约定配置 SecretClient。

使用配置提供程序

.NET AspireAzure Key Vault 集成支持 Microsoft.Extensions.Configuration。它使用 Aspire:Azure:Security:KeyVault 密钥从 appsettings.json 或其他配置文件中加载 AzureSecurityKeyVaultSettings。

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

有关完整的 Azure Key Vault 客户端集成 JSON 架构，请参阅 Aspire.Azure.Security.KeyVault/ConfigurationSchema.json。

如果在 Aspire:Azure:Security:KeyVault 文件的 appsettings.json 节中设置了配置，只需调用方法 AddAzureKeyVaultSecrets 即可不传递任何参数。

使用内联委托

你还可以传递 Action<AzureSecurityKeyVaultSettings> 委托，从而以内联方式设置部分或全部选项，例如用于设置 AzureSecurityKeyVaultSettings.VaultUri：

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI"));

你还可以通过 Action<SecretClientOptions> 委托来设置 SecretClientOptions，这是 AddAzureKeyVaultSecrets 方法的可选参数。例如，将 KeyClientOptions.DisableChallengeResourceVerification 设置为 ID 来标识客户端：

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureClientOptions: options => options.DisableChallengeResourceVerification = true))

配置选项

以下可配置选项通过 AzureSecurityKeyVaultSettings 类公开：

名字	描述
AzureSecurityKeyVaultSettings.Credential	用于向 Azure Key Vault 进行身份验证的凭据。
AzureSecurityKeyVaultSettings.DisableHealthChecks	一个指示是否禁用 Key Vault 运行状况检查的布尔值。
AzureSecurityKeyVaultSettings.DisableTracing	一个布尔值，用于指示 OpenTelemetry 跟踪是否被禁用。
AzureSecurityKeyVaultSettings.VaultUri	客户端操作的保管库的 URI。在 Azure 门户中显示为“DNS 名称”。

Client 集成运行状况检查

默认情况下，所有服务的.NET.NET Aspire客户端集成都启用了状态检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

.NET AspireAzure Key Vault 集成包括以下运行状况检查：

添加 AzureKeyVaultSecretsHealthCheck 运行状况检查，该检查尝试连接并查询 Key Vault
与 /health HTTP 终结点集成，该终结点指定所有已注册的健康检查都必须通过，应用才会被视为准备好接受流量。

可观测性和遥测

.NET.NET Aspire 集成会自动设置日志记录、追踪和指标配置，这些配置有时被称为可观测性支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

日志记录

.NET AspireAzure Key Vault 集成使用以下日志类别：

Azure.Core
Azure.Identity

跟踪

.NET AspireAzure Key Vault 集成将使用 OpenTelemetry 生成以下跟踪活动：

Azure.Security.KeyVault.Secrets.SecretClient

指标

由于 .NET Aspire SDK 的限制，Azure Key VaultAzure 集成目前目前不支持指标。