Azure.Data.AppConfiguration 1.5.0

Azure App Configuration .NET 客户端库

Azure App Configuration 是一个受管理的服务，它可以帮助开发人员简单和安全地集中管理其应用程序和功能设置。

使用 App Configuration 客户端库可

• 创建和管理集中存储的应用程序配置设置
• 从特定时间点检索配置设置

源代码 | 包 (NuGet) | API 参考文档 | 产品文档 | 示例

入门指南

安装包

使用 NuGet 安装 .NET Azure App Configuration 客户端库

dotnet add package Azure.Data.AppConfiguration

先决条件

• 一个 Azure 订阅。
• 现有的配置存储。

如果您需要创建配置存储，可以使用Azure门户或Azure CLI。

您可以使用以下命令使用Azure CLI创建配置存储

az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus

验证客户端

为了与应用配置服务交互，您需要创建配置客户端类的实例。要实现这一点，您需要配置存储的连接字符串。

获取凭证

使用以下Azure CLI片段从配置存储中获取连接字符串。

az appconfig credential list --name <config-store-name>

或者，从Azure门户获取连接字符串。

创建ConfigurationClient

一旦您获取了连接字符串的值，您就可以创建ConfigurationClient

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);

使用Azure Active Directory凭据创建ConfigurationClient

客户端订阅密钥身份验证被用于此入门指南中的大多数示例，但您也可以使用Azure Identity库通过Azure Active Directory进行身份验证。要使用下面显示的DefaultAzureCredential提供程序或其他Azure SDK提供的凭据提供程序，请安装Azure.Identity包

dotnet add package Azure.Identity

您还需要注册新的AAD应用程序并通过将"App Configuration Data Reader"或"App Configuration Data Owner"角色分配给您的服务主体来授予权限访问配置存储。

将AAD应用程序的客户端ID、租户ID和客户端机密的值设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。

string endpoint = "<endpoint>";
var client = new ConfigurationClient(new Uri(endpoint), new DefaultAzureCredential());

核心概念

配置设置

配置设置是配置存储中的基本资源。在其最简单的形式中，它是一个键和一个值。然而，还有其他属性，如可修改的内容类型和标签字段，允许以不同的方式解释或关联值。

配置设置的标签属性提供了一种将配置设置分开到不同维度的途径。这些维度是用户定义的，可以采取任何形式。用于标签的一些常见维度示例包括地区、语义版本或环境。许多应用程序都有一些必需的配置键，这些键的值随应用程序在不同维度上的存在而变化。

例如，MaxRequests可能在"NorthAmerica"中为100，在"WestEurope"中为200。通过创建一个名为MaxRequests的配置设置，带有"NorthAmerica"标签，另一个只有不同的值，带有"WestEurope"标签，应用程序可以在这两个维度中无缝检索配置设置。

Azure应用配置允许用户创建配置存储的时间点快照，从而使他们能够将设置视为一致版本。此功能使应用程序能够保持对配置的一致视图，确保由于读取更新而不会发生某些设置的个人版本不匹配。快照是不可变的，确保在出现问题时可以自信地将配置回滚到最后已知良好的配置。

线程安全性

我们保证所有客户端实例方法都是线程安全的，并且相互独立（参见指南）。这确保了重用客户端实例的建议始终是安全的，即使在多线程环境下。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

以下部分提供了一些代码片段，涵盖了一些最常见的配置服务任务。请注意，对于这两者都提供了同步和异步方法。

• 创建配置设置
• 检索配置设置
• 更新现有配置设置
• 删除配置设置
• 创建快照
• 检索快照
• 存档快照
• 恢复快照
• 检索所有快照

创建配置设置

创建一个将存储在配置存储中的配置设置。存储配置设置有两种方式

• AddConfigurationSetting仅在设置在存储中不存在时创建设置。
• SetConfigurationSetting如果设置不存在或覆盖现有设置。

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
var settingToCreate = new ConfigurationSetting("some_key", "some_value");
ConfigurationSetting setting = client.SetConfigurationSetting(settingToCreate);

检索配置设置

通过调用GetConfigurationSetting检索之前存储的配置设置。本片段假设配置存储中存在设置"some_key"。

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
ConfigurationSetting setting = client.GetConfigurationSetting("some_key");

更新现有配置设置

通过调用SetConfigurationSetting更新现有配置设置。本片段假设配置存储中存在设置"some_key"。

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
ConfigurationSetting setting = client.SetConfigurationSetting("some_key", "new_value");

删除配置设置

通过调用DeleteConfigurationSetting删除现有配置设置。本片段假设配置存储中存在设置"some_key"。

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
client.DeleteConfigurationSetting("some_key");

创建快照

要创建一个快照，需要实例化ConfigurationSnapshot类并指定筛选器以确定哪些配置设置应该包含在内。创建过程是一个长时间运行的操作（LRO），可以通过调用CreateSnapshot方法实现。

var settingsFilter = new List<ConfigurationSettingsFilter> { new ConfigurationSettingsFilter("some_key") };
var settingsSnapshot = new ConfigurationSnapshot(settingsFilter);

var snapshotName = "some_snapshot";
var operation = client.CreateSnapshot(WaitUntil.Completed, snapshotName, settingsSnapshot);
var createdSnapshot = operation.Value;
Console.WriteLine($"Created configuration snapshot: {createdSnapshot.Name}, Status: {createdSnapshot.Status}");

检索快照

一旦创建了一个配置快照，就可以使用GetSnapshot方法检索它。

var snapshotName = "some_snapshot";
ConfigurationSnapshot retrievedSnapshot = client.GetSnapshot(snapshotName);
Console.WriteLine($"Retrieved configuration snapshot: {retrievedSnapshot.Name}, status: {retrievedSnapshot.Status}");

存档快照

要存档快照，可以使用ArchiveSnapshot方法。此操作将快照的状态更新为存档。

var snapshotName = "some_snapshot";
ConfigurationSnapshot archivedSnapshot = client.ArchiveSnapshot(snapshotName);
Console.WriteLine($"Archived configuration snapshot: {archivedSnapshot.Name}, status: {archivedSnapshot.Status}");

恢复快照

可以使用RecoverSnapshot方法恢复存档快照。此操作将快照的状态更新为准备就绪。

var snapshotName = "some_snapshot";
ConfigurationSnapshot recoveredSnapshot = client.RecoverSnapshot(snapshotName);
Console.WriteLine($"Recovered configuration snapshot: {recoveredSnapshot.Name}, status: {recoveredSnapshot.Status}");

检索所有快照

要检索所有快照，可以使用GetSnapshots方法。

var count = 0;
foreach (var item in client.GetSnapshots(new SnapshotSelector()))
{
    count++;
    Console.WriteLine($"Retrieved configuration snapshot: {item.Name}, status {item.Status}");
}
Console.WriteLine($"Total number of snapshots retrieved: {count}");

故障排除

有关诊断各种故障场景的详细信息，请参阅我们的故障排除指南。

下一步

更多示例代码

这个GitHub仓库中提供了多个App Configuration客户端库示例。这包括

• 你好世界：创建和删除配置设置。
• 异步你好世界扩展带标签：异步地创建、更新和删除配置设置，并使用标签。
• 设置配置为只读：将配置设置为只读，然后将其恢复为读写状态。
• 读取修订历史记录：读取已更改的配置设置的修订历史记录。
• 如果设置已更改则获取设置：通过使用条件请求仅在设置与本地副本不同时检索设置，以节省带宽。
• 如果设置未更改则更新设置：通过使用乐观并发来防止丢失更新，仅在您的本地更新已应用到配置存储中资源的同一版本时更新设置。
• 配置设置快照：创建、检索和更新配置设置快照的状态。
• 创建模拟客户端：为测试模拟客户端。

有关更多详细信息，请参阅示例README。

贡献

有关构建、测试和对此库做出贡献的详细信息，请参阅App Configuration CONTRIBUTING.md。

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权并实际上向我们授予使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

当您提交拉取请求时，CLA-bot 将自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签，评论）。只需遵循机器人提供的说明即可。您在整个使用我们的CLA的所有仓库中只需这样做一次。

本项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题解答或通过[email protected]联系以提出任何额外的问题或评论。