.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.KeyVault 使用 client项目中的 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.Azure.KeyVault 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。 它从 appsettings.json 或其他配置文件中使用 Aspire:Azure:Security:KeyVault 密钥加载 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>> 委托（AddAzureKeyVaultSecrets 方法的第二个参数）设置 SecretClientOptions。 例如，设置 KeyClientOptions.DisableChallengeResourceVerification ID 来识别 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。 - 与
/healthHTTP 终结点集成，该终结点指定所有已注册的健康检查都必须通过，应用才会被视为准备好接受流量。
可观测性和遥测
.NET .NET Aspire 集成会自动设置日志记录、追踪和指标配置，这些配置有时被称为可观测性支柱。 有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。 根据支持服务，某些集成可能仅支持其中一些功能。 例如，某些集成支持日志记录和跟踪，但不支持指标。 也可以使用 配置 部分中介绍的技术禁用遥测功能。
伐木
.NET Aspire Azure Key Vault 集成使用以下日志类别：
Azure.CoreAzure.Identity
追踪
.NET Aspire Azure Key Vault 集成将使用 OpenTelemetry发出以下跟踪活动：
- “Azure。Security.KeyVault.Secrets.SecretClient”
指标
由于 Azure SDK 的限制，.NET AspireAzure Key Vault 集成目前目前不支持指标。
