Azure 密钥保管库 .NET 2.0 - 发行说明和迁移指南Azure Key Vault .NET 2.0 - Release Notes and Migration Guide

09/15/2020

以下信息有助于迁移到 C# 和 .NET 的 Azure Key Vault 库版本 2.0。The following information helps migrating to the 2.0 version of the Azure Key Vault library for C# and .NET. 针对早期版本所编写的应用需进行更新，以支持最新版本。Apps written for earlier versions need to be updating to support the latest version. 为完全支持新增和改进的功能（如 Key Vault 证书），这些更改是必需的。These changes are needed to fully support new and improved features, such as Key Vault certificates.

Key Vault 证书Key Vault certificates

Key Vault 证书管理 x509 证书，并支持以下行为：Key Vault certificates manage x509 certificates and supports the following behaviors:

通过 Key Vault 创建过程创建证书，或导入现有证书。Create certificates through a Key Vault creation process or import existing certificate. 这包括自签名证书和证书颁发机构 (CA) 生成的证书。This includes both self-signed and Certificate Authority (CA) generated certificates.
安全地存储和管理 x509 证书存储，无需使用私钥材料进行交互。Securely store and manage x509 certificate storage without interaction using private key material.
定义指导 Key Vault 管理证书生命周期的策略。Define policies that direct Key Vault to manage the certificate lifecycle.
为生命周期事件提供联系信息，如过期警告和续订通知。Provide contact information for lifecycle events, such as expiration warnings and renewal notifications.
使用选定的证书颁发者（Key Vault 合作伙伴 X509 证书提供者和证书颁发机构）自动续订证书。* 支持来自备用（非合作伙伴）提供者和证书颁发机构的支持证书（不支持自动续订）。Automatically renew certificates with selected issuers (Key Vault partner X509 certificate providers and certificate authorities).* Support certificate from alternate (non-partner) provides and certificate authorities (does not support auto-renewal).

.NET 支持.NET support

Azure Key Vault .NET 库 2.0 版不支持 .NET 4.0.NET 4.0 is not supported by the 2.0 version of the Azure Key Vault .NET library
Azure Key Vault .NET 库 2.0 版支持 .NET Framework 4.5.2.NET Framework 4.5.2 is supported by the 2.0 version of the Azure Key Vault .NET library
Azure Key Vault .NET 库 2.0 版支持 .NET Standard 1.4.NET Standard 1.4 is supported by the 2.0 version of the Azure Key Vault .NET library

命名空间Namespaces

模型的命名空间从 Microsoft.Azure.KeyVault 更改为 Microsoft.Azure.KeyVault.Models。The namespace for models is changed from Microsoft.Azure.KeyVault to Microsoft.Azure.KeyVault.Models.
Microsoft.Azure.KeyVault.Internal 命名空间被弃用。The Microsoft.Azure.KeyVault.Internal namespace is dropped.
以下 Azure SDK 依赖项命名空间的更改The following Azure SDK dependencies namespaces have
- Hyak.Common 现为 Microsoft.Rest 。Hyak.Common is now Microsoft.Rest.
- Hyak.Common.Internals 现为 Microsoft.Rest.Serialization 。Hyak.Common.Internals is now Microsoft.Rest.Serialization.

类型更改Type changes

Secret 更改为 SecretBundleSecret changed to SecretBundle
Dictionary 更改为 IDictionaryDictionary changed to IDictionary
List<T>、字符串 [] 更改为 IList<T>List<T>, string [] changed to IList<T>
NextList 更改为 NextPageLinkNextList changed to NextPageLink

返回类型Return types

KeyList 和 SecretList 将返回 IPage<T> 而不是 ListKeysResponseMessage************KeyList and SecretList now returns IPage<T> instead of ListKeysResponseMessage
生成的 BackupKeyAsync 将返回 BackupKeyResult，其中包含“值”（备份 blob）。The generated BackupKeyAsync now returns BackupKeyResult, which contains Value (back-up blob). 以前，此方法会包装且仅返回值。Previously, the method was wrapped and returned just the value.

异常Exceptions

KeyVaultClientException 更改为 KeyVaultErrorExceptionKeyVaultClientException is changed to KeyVaultErrorException
服务错误从 exception.Error 更改为 exception.Body.Error.Message 。The service error changed from exception.Error to exception.Body.Error.Message.
从 [JsonExtensionData] 的错误消息中删除了其他信息。Removed additional info from the error message for [JsonExtensionData].

构造函数Constructors

构造函数不接受 HttpClient 作为构造函数参数，只接受 HttpClientHandler 或 DelegatingHandler[] 。Instead of accepting an HttpClient as a constructor argument, the constructor only accepts HttpClientHandler or DelegatingHandler[].

下载的包Downloaded packages

客户端在处理 Key Vault 依赖项时，将下载以下包：When a client processes a Key Vault dependency, the following packages are downloaded:

以前的包列表Previous package list

package id="Hyak.Common" version="1.0.2" targetFramework="net45"
package id="Microsoft.Azure.Common" version="2.0.4" targetFramework="net45"
package id="Microsoft.Azure.Common.Dependencies" version="1.0.0" targetFramework="net45"
package id="Microsoft.Azure.KeyVault" version="1.0.0" targetFramework="net45"
package id="Microsoft.Bcl" version="1.1.9" targetFramework="net45"
package id="Microsoft.Bcl.Async" version="1.0.168" targetFramework="net45"
package id="Microsoft.Bcl.Build" version="1.0.14" targetFramework="net45"
package id="Microsoft.Net.Http" version="2.2.22" targetFramework="net45"

当前的包列表Current package list

package id="Microsoft.Azure.KeyVault" version="2.0.0-preview" targetFramework="net45"
package id="Microsoft.Rest.ClientRuntime" version="2.2.0" targetFramework="net45"
package id="Microsoft.Rest.ClientRuntime.Azure" version="3.2.0" targetFramework="net45"

类更改Class changes

已删除 UnixEpoch 类。UnixEpoch class has been removed.
Base64UrlConverter 类重命名为 Base64UrlJsonConverter 。Base64UrlConverter class is renamed to Base64UrlJsonConverter.

其他更改Other changes

在此版本的 API 中，添加了针对暂时性故障配置 KV 操作重试策略的支持。Support for the configuration of KV operation retry policy on transient failures has been added to this version of the API.

Microsoft.Azure.Management.KeyVault NuGetMicrosoft.Azure.Management.KeyVault NuGet

对于返回 vault 的操作，返回类型是包含 Vault 属性的类。For the operations that returned a vault, the return type was a class that contained a Vault property. 返回类型现在为 Vault。The return type is now Vault.
PermissionsToKeys 和 PermissionsToSecrets 现在是 Permissions.Keys 和 Permissions.SecretsPermissionsToKeys and PermissionsToSecrets are now Permissions.Keys and Permissions.Secrets
某些返回类型的更改也适用于控制面板。Certain return types changes apply to the control-plane as well.

Microsoft.Azure.KeyVault.Extensions NuGetMicrosoft.Azure.KeyVault.Extensions NuGet

该包已分解为 Microsoft.Azure.KeyVault.Extensions 和用于加密操作的 Microsoft.Azure.KeyVault.Cryptography。The package is broken up to Microsoft.Azure.KeyVault.Extensions and Microsoft.Azure.KeyVault.Cryptography for the cryptography operations.