你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 密钥保管库机密客户端库 - 版本 4.5.0

项目
04/03/2023

Azure 密钥保管库是一种云服务，提供密码和数据库连接字符串等机密的安全存储。

使用 Azure 密钥保管库机密客户端库，可以安全地存储和控制对令牌、密码、API 密钥和其他机密的访问。此库提供创建、检索、更新、删除、清除、备份、还原和列出机密及其版本的操作。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 密钥保管库机密客户端库：

dotnet add package Azure.Security.KeyVault.Secrets

先决条件

一个 Azure 订阅。
现有的 Azure 密钥保管库。如果需要创建 Azure 密钥保管库，可以使用 Azure 门户或 Azure CLI。
使用 RBAC (建议) 或访问控制授权现有 Azure 密钥保管库。

如果使用 Azure CLI，请将和 <your-key-vault-name> 替换为<your-resource-group-name>自己的唯一名称：

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

验证客户端

若要与 Azure 密钥保管库服务交互，需要创建 SecretClient 类的实例。需要 保管库 URL（可能在门户中显示为“DNS 名称”）和用于实例化客户端对象的凭据。

下面显示的示例使用， DefaultAzureCredential它适用于大多数方案，包括本地开发和生产环境。此外，建议在生产环境中使用托管标识进行身份验证。可以在 Azure 标识文档中找到有关不同身份验证方式及其相应凭据类型的详细信息。

若要使用如下所示的 DefaultAzureCredential 提供程序或 Azure SDK 提供的其他凭据提供程序，必须先安装 Azure.Identity 包：

dotnet add package Azure.Identity

实例化要 DefaultAzureCredential 传递给客户端的。如果多个客户端将使用相同的标识进行身份验证，则可以将令牌凭据的同一实例用于这些客户端。

// Create a new secret client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new SecretClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new secret using the secret client.
KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

// Retrieve a secret using the secret client.
secret = client.GetSecret("secret-name");

关键概念

KeyVaultSecret

是 KeyVaultSecret Azure 密钥保管库中的基本资源。从开发人员的角度来看，Azure 密钥保管库 API 接受机密值并将其作为字符串返回。

SecretClient

在 SecretClient SDK 中提供同步和异步操作，允许根据应用程序的用例选择客户端。初始化后，SecretClient可以与 Azure 密钥保管库中的机密进行交互。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且相互独立， (准则) 。这可确保重用客户端实例的建议始终是安全的，即使跨线程也是如此。

其他概念

示例

Azure.Security.KeyVault.Secrets 包支持同步和异步 API。

以下部分提供了使用client上面创建的几个代码片段，涵盖了一些最常见的 Azure 密钥保管库机密服务相关任务：

异步示例

异步创建机密
异步列出机密
异步删除机密

创建机密

SetSecretKeyVaultSecret创建要存储在 Azure 密钥保管库中的。如果已存在同名的机密，则会创建该机密的新版本。

KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Properties.Version);
Console.WriteLine(secret.Properties.Enabled);

检索机密

GetSecret检索以前存储在 Azure 密钥保管库中的机密。

KeyVaultSecret secret = client.GetSecret("secret-name");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

更新现有机密

UpdateSecretProperties更新以前存储在 Azure 密钥保管库中的机密。仅更新机密的属性。若要更新值，请调用 SecretClient.SetSecret 同名的机密。

KeyVaultSecret secret = client.GetSecret("secret-name");

// Clients may specify the content type of a secret to assist in interpreting the secret data when its retrieved.
secret.Properties.ContentType = "text/plain";

// You can specify additional application-specific metadata in the form of tags.
secret.Properties.Tags["foo"] = "updated tag";

SecretProperties updatedSecretProperties = client.UpdateSecretProperties(secret.Properties);

Console.WriteLine(updatedSecretProperties.Name);
Console.WriteLine(updatedSecretProperties.Version);
Console.WriteLine(updatedSecretProperties.ContentType);

删除机密

StartDeleteSecret启动长时间运行的操作，以删除以前存储在 Azure 密钥保管库中的机密。可以立即检索机密，而无需等待操作完成。如果未为 Azure 密钥保管库启用软删除，此操作将永久删除机密。

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

DeletedSecret secret = operation.Value;
Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

删除和清除机密

在尝试清除或恢复机密之前，需要等待长时间运行的操作完成。可以通过在循环中调用 UpdateStatus 来执行此操作，如下所示：

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedSecret secret = operation.Value;
client.PurgeDeletedSecret(secret.Name);

列出机密

此示例列出指定 Azure 密钥保管库中的所有机密。列出所有机密时，不会返回值。需要调用 SecretClient.GetSecret 才能检索值。

Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

异步创建机密

异步 API 与其同步 API 相同，但返回具有异步方法的典型“Async”后缀，并返回 Task。

此示例使用指定的可选参数在 Azure 密钥保管库中创建机密。

KeyVaultSecret secret = await client.SetSecretAsync("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

异步列出机密

列出机密不依赖于等待 GetPropertiesOfSecretsAsync 方法，但返回 AsyncPageable<SecretProperties> 可与语句一起使用的 await foreach ：

AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

异步删除机密

在清除机密之前异步删除机密时，可以等待 WaitForCompletionAsync 操作的方法。默认情况下，此循环无限期，但可以通过传递 CancellationToken来取消它。

DeleteSecretOperation operation = await client.StartDeleteSecretAsync("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
await operation.WaitForCompletionAsync();

DeletedSecret secret = operation.Value;
await client.PurgeDeletedSecretAsync(secret.Name);

疑难解答

有关如何诊断各种故障方案的详细信息，请参阅故障排除指南。

常规

使用 .NET SDK 与 Azure 密钥保管库机密客户端库交互时，服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。

例如，如果尝试检索 Azure 密钥保管库中不存在的机密，则会返回错误404，指示 Not Found。

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

你会注意到记录了其他信息，例如操作的客户端请求 ID。

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"SecretNotFound","message":"Secret not found: some_secret"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

后续步骤

在此 GitHub 存储库中提供了多个 Azure 密钥保管库机密客户端库示例。这些示例提供了使用 Azure 密钥保管库时经常遇到的其他方案的示例代码：

Sample1_HelloWorld.md - 用于使用 Azure 密钥保管库，包括：
- 创建机密
- 获取现有机密
- 更新现有机密
- 删除机密
Sample2_BackupAndRestore.md - 包含使用 Azure 密钥保管库机密的代码片段，包括：
- 备份和恢复机密
Sample3_GetSecrets.md - 使用 Azure 密钥保管库机密的示例代码，包括：
- 创建机密
- 列出密钥保管库中的所有机密
- 更新密钥保管库中的机密
- 列出指定机密的版本
- 从密钥保管库中删除机密
- 列出密钥保管库中删除的机密

其他文档

有关 Azure 密钥保管库的更多文档，请参阅 API 参考文档。
有关密钥客户端库，请参阅密钥客户端库。
有关证书客户端库，请参阅证书客户端库。

供稿

有关生成、测试和参与这些库的详细信息，请参阅 CONTRIBUTING.md 。

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

曝光数

通过