使用 Azure.ResourceManager.Redis .NET SDK 管理 Azure Cache for Redis：从缓存创建到密钥轮换的完整指南

• AI 技能
• AI 插件

导读

本文基于 agentic-awesome-skills 仓库中的azure-resource-manager-redis-dotnet技能文档，系统讲解如何通过 Azure Resource Manager（ARM）管理平面 SDK 在 .NET 应用中完成 Azure Cache for Redis 的创建、配置、更新、删除与运维。读完本文，你将掌握ArmClient资源层级导航、10 个核心生命周期工作流（含防火墙规则、补丁计划、导入导出、强制重启等）、SKU 与容量选型，以及如何与StackExchange.Redis数据面 SDK 无缝衔接，直接可落地到真实的 .NET 云资源管理项目中。

一、技能定位：管理面 vs 数据面

在开始编码之前，必须先明确 Azure Cache for Redis 的两类 SDK 边界。本技能文档在第一屏就给出了清晰的划分：

• 管理面（Management Plane）：即本文主角Azure.ResourceManager.Redis，负责"资源本身"的生命周期——创建缓存、配置防火墙规则、管理访问密钥、设置异地复制（geo-replication）、配置补丁计划等。
• 数据面（Data Plane）：即StackExchange.Redis，负责"缓存中的数据"——get/set 键值、pub/sub 发布订阅、streams、Lua 脚本执行等。

从仓库元数据看，该技能在 data/catalog.json 中被归类为category: cloud、risk: critical、source: community，标签为azure/resource/manager/redis/dotnet，其triggers包含azure、resource、manager、redis、dotnet、sdk、net。这意味着当 Agent 的输入中命中这些关键词时，即可自动唤起本技能来完成 Azure Redis 资源的 ARM 管理任务。

仓库中还收录了面向自托管 Redis 服务器的 redis 技能（配置、集群、Sentinel、持久化），与本文的 Azure 托管场景形成互补：前者管"自己部署的 Redis"，后者管"Azure 云上的 Redis 资源"。

二、安装与项目环境

在 .NET 项目中添加两个 NuGet 包即可开始：

dotnet add package Azure.ResourceManager.Redis dotnet add package Azure.Identity

技能文档标注的版本信息如下：

• 当前版本：1.5.1（Stable）
• API 版本：2024-11-01
• 目标框架：.NET 8.0、.NET Standard 2.0

Azure.Identity用于提供DefaultAzureCredential认证，Azure.ResourceManager.Redis则承载全部 Redis 管理操作。值得注意的是.NET Standard 2.0支持意味着该 SDK 也适用于面向 .NET Framework 兼容场景或类库项目的场景，但生产环境仍建议使用 .NET 8.0 及以上的 LTS 版本。

环境变量

SDK 运行时依赖以下环境变量，建议通过 CI/CD 变量或 Key Vault 注入，而非硬编码在源码中：

AZURE_SUBSCRIPTION_ID=<your-subscription-id> # For service principal auth (optional) AZURE_TENANT_ID=<tenant-id> AZURE_CLIENT_ID=<client-id> AZURE_CLIENT_SECRET=<client-secret>

其中AZURE_SUBSCRIPTION_ID是必需项（构造订阅资源用）；当使用服务主体（Service Principal）认证时才需要后三个变量。

三、认证：始终使用 DefaultAzureCredential

管理面 SDK 的认证入口是ArmClient，配合DefaultAzureCredential可以按顺序尝试多种身份来源（环境变量、Azure CLI 登录态、托管身份等），适合本地开发与云端部署的无缝切换：

using Azure.Identity; using Azure.ResourceManager; using Azure.ResourceManager.Redis; // Always use DefaultAzureCredential var credential = new DefaultAzureCredential(); var armClient = new ArmClient(credential); // Get subscription var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID"); var subscription = armClient.GetSubscriptionResource( new ResourceIdentifier($"/subscriptions/{subscriptionId}"));

技能文档强调的核心原则是"永远不要硬编码密钥"——认证凭据的获取交给DefaultAzureCredential，而访问密钥（access keys）则通过 API 动态获取（见下文"获取/轮换访问密钥"）。

四、资源层级（Resource Hierarchy）

ARM SDK 采用层级化的资源模型，所有操作都从ArmClient出发向下导航：

ArmClient └── SubscriptionResource └── ResourceGroupResource └── RedisResource ├── RedisFirewallRuleResource ├── RedisPatchScheduleResource ├── RedisLinkedServerWithPropertyResource ├── RedisPrivateEndpointConnectionResource └── RedisCacheAccessPolicyResource

理解这条层级链是使用本 SDK 的关键：上层资源的Get*方法返回下层资源的集合或单资源句柄，例如resourceGroup.Value.GetAllRedis()拿到缓存集合，cache.Value.GetRedisFirewallRules()拿到防火墙规则集合。这种"从 ArmClient 逐级下钻"的写法贯穿本文全部示例。

五、核心工作流（10 个完整示例）

1. 创建 Redis 缓存

创建是典型的长时间运行操作（LRO），使用CreateOrUpdateAsync并传入RedisCreateOrUpdateContent：

using Azure.ResourceManager.Redis; using Azure.ResourceManager.Redis.Models; // Get resource group var resourceGroup = await subscription .GetResourceGroupAsync("my-resource-group"); // Define cache configuration var cacheData = new RedisCreateOrUpdateContent( location: AzureLocation.EastUS, sku: new RedisSku(RedisSkuName.Standard, RedisSkuFamily.BasicOrStandard, 1)) { EnableNonSslPort = false, MinimumTlsVersion = RedisTlsVersion.Tls1_2, RedisConfiguration = new RedisCommonConfiguration { MaxMemoryPolicy = "volatile-lru" }, Tags = { ["environment"] = "production" } }; // Create cache (long-running operation) var cacheCollection = resourceGroup.Value.GetAllRedis(); var operation = await cacheCollection.CreateOrUpdateAsync( WaitUntil.Completed, "my-redis-cache", cacheData); RedisResource cache = operation.Value; Console.WriteLine($"Cache created: {cache.Data.HostName}");

要点拆解：

• RedisSku(RedisSkuName.Standard, RedisSkuFamily.BasicOrStandard, 1)：三个参数分别是 SKU 名称、家族（Family）、容量（Capacity）。
• EnableNonSslPort = false：关闭 6379 非 SSL 端口，强制走 SSL 连接。
• MinimumTlsVersion = RedisTlsVersion.Tls1_2：最低 TLS 1.2，满足安全合规基线。
• MaxMemoryPolicy = "volatile-lru"：内存淘汰策略，只淘汰设置了过期时间的键（volatile），保留长期缓存。
• Tags：打上environment=production之类的资源标签，便于成本核算与资源分组。

2. 获取缓存详情

读取既有缓存及其连接端点信息：

// Get existing cache var cache = await resourceGroup.Value .GetRedisAsync("my-redis-cache"); Console.WriteLine($"Host: {cache.Value.Data.HostName}"); Console.WriteLine($"Port: {cache.Value.Data.Port}"); Console.WriteLine($"SSL Port: {cache.Value.Data.SslPort}"); Console.WriteLine($"Provisioning State: {cache.Value.Data.ProvisioningState}");

HostName、Port、SslPort是后续构造连接字符串的必备数据，ProvisioningState用于判断缓存是否就绪（Succeeded才能接收数据面连接）。

3. 更新缓存配置

升配、改内存策略等通过UpdateAsync完成（注意：降配不允许，见"常见陷阱"）：

var patchData = new RedisPatch { Sku = new RedisSku(RedisSkuName.Standard, RedisSkuFamily.BasicOrStandard, 2), RedisConfiguration = new RedisCommonConfiguration { MaxMemoryPolicy = "allkeys-lru" } }; var updateOperation = await cache.Value.UpdateAsync( WaitUntil.Completed, patchData);

此处将容量从 1 提升到 2，并把淘汰策略从volatile-lru改为allkeys-lru（允许淘汰所有键，适合纯缓存场景）。

4. 删除缓存

await cache.Value.DeleteAsync(WaitUntil.Completed);

删除是不可逆操作，生产环境执行前务必确认数据已通过导出（见"导入/导出数据"）或持久化保存。

5. 获取访问密钥

var keys = await cache.Value.GetKeysAsync(); Console.WriteLine($"Primary Key: {keys.Value.PrimaryKey}"); Console.WriteLine($"Secondary Key: {keys.Value.SecondaryKey}");

Azure Redis 提供主/次两个密钥，用于构造数据面连接字符串，也是下文密钥轮换的基础。

6. 轮换访问密钥

var regenerateContent = new RedisRegenerateKeyContent(RedisRegenerateKeyType.Primary); var newKeys = await cache.Value.RegenerateKeyAsync(regenerateContent); Console.WriteLine($"New Primary Key: {newKeys.Value.PrimaryKey}");

轮换是安全最佳实践（见"最佳实践"第 10 条）：先用备用密钥更新应用配置，再轮换主密钥，可实现零停机。

7. 管理防火墙规则

按 IP 段精确控制哪些客户端可以访问缓存：

// Create firewall rule var firewallData = new RedisFirewallRuleData( startIP: System.Net.IPAddress.Parse("10.0.0.1"), endIP: System.Net.IPAddress.Parse("10.0.0.255")); var firewallCollection = cache.Value.GetRedisFirewallRules(); var firewallOperation = await firewallCollection.CreateOrUpdateAsync( WaitUntil.Completed, "allow-internal-network", firewallData); // List all firewall rules await foreach (var rule in firewallCollection.GetAllAsync()) { Console.WriteLine($"Rule: {rule.Data.Name} ({rule.Data.StartIP} - {rule.Data.EndIP})"); } // Delete firewall rule var ruleToDelete = await firewallCollection.GetAsync("allow-internal-network"); await ruleToDelete.Value.DeleteAsync(WaitUntil.Completed);

注意示例中省略了规则名称参数name的显式注释，实际调用签名中的第二个参数即为规则名（如"allow-internal-network"），用于后续 Get/Delete。GetAllAsync返回异步迭代器，配合await foreach可流式列出全部规则。

8. 配置补丁计划（仅 Premium SKU）

补丁计划用于指定 Azure 对缓存节点打系统补丁的维护窗口，仅 Premium SKU 支持：

// Patch schedules require Premium SKU var scheduleData = new RedisPatchScheduleData( new[] { new RedisPatchScheduleSetting(RedisDayOfWeek.Saturday, 2) // 2 AM Saturday { MaintenanceWindow = TimeSpan.FromHours(5) }, new RedisPatchScheduleSetting(RedisDayOfWeek.Sunday, 2) // 2 AM Sunday { MaintenanceWindow = TimeSpan.FromHours(5) } }); var scheduleCollection = cache.Value.GetRedisPatchSchedules(); await scheduleCollection.CreateOrUpdateAsync( WaitUntil.Completed, RedisPatchScheduleDefaultName.Default, scheduleData);

RedisPatchScheduleSetting的第一个参数是星期几（RedisDayOfWeek.Saturday），第二个参数是维护窗口起始小时（2表示凌晨 2 点），MaintenanceWindow用TimeSpan指定窗口时长。示例配置了周六、周日凌晨各 5 小时的维护窗口，避开业务高峰。

9. 导入/导出数据（仅 Premium SKU）

Premium 缓存支持基于 Azure Blob Storage 的 RDB 快照导入/导出，用于迁移、备份或复制数据：

// Import data from blob storage var importContent = new ImportRdbContent( files: new[] { "https://mystorageaccount.blob.core.windows.net/container/dump.rdb" }, format: "RDB"); await cache.Value.ImportDataAsync(WaitUntil.Completed, importContent); // Export data to blob storage var exportContent = new ExportRdbContent( prefix: "backup", container: "https://mystorageaccount.blob.core.windows.net/container?sastoken", format: "RDB"); await cache.Value.ExportDataAsync(WaitUntil.Completed, exportContent);

导入时files传入 RDB 文件 URL 数组，格式为"RDB"；导出时prefix是导出文件名前缀，container是带 SAS 令牌的容器 URL——导出要求存储账号启用托管身份或提供具有写权限的 SAS 令牌。

10. 强制重启

var rebootContent = new RedisRebootContent { RebootType = RedisRebootType.AllNodes, ShardId = 0 // For clustered caches }; await cache.Value.ForceRebootAsync(rebootContent);

RebootType支持AllNodes（全部节点）、PrimaryOnly、SecondaryOnly等选项；ShardId仅在启用集群分片（Premium + clustering）时有意义，用于指定重启哪个分片。强制重启会中断服务，务必在维护窗口执行。

六、SKU 与容量参考

Capacity Sizes (Family C - Basic/Standard):

• C0: 250 MB
• C1: 1 GB
• C2: 2.5 GB
• C3: 6 GB
• C4: 13 GB
• C5: 26 GB
• C6: 53 GB

Capacity Sizes (Family P - Premium):

• P1: 6 GB per shard
• P2: 13 GB per shard
• P3: 26 GB per shard
• P4: 53 GB per shard
• P5: 120 GB per shard

选型建议（结合文档与常见实践）：

• 开发/测试：Basic（无 SLA，单节点）。
• 生产缓存：Standard（主备双节点，有 SLA），容量按工作集 + 淘汰策略估算。
• 高可用增强场景：Premium（集群、异地复制、VNet 注入、持久化、补丁计划全部依赖 Premium），P 系列按"每分片容量 × 分片数"计算总容量。

七、关键类型速查

其中RedisLinkedServerWithPropertyResource对应异地复制（Linked Server）能力，RedisCacheAccessPolicyResource对应基于 RBAC 的数据面访问策略，二者均需 Premium SKU。

八、最佳实践清单

技能文档给出 10 条可直接套用的最佳实践：

1. 使用WaitUntil.Completed：必须等操作完成才能继续时使用。
2. 使用WaitUntil.Started：想手动轮询或并行执行多个操作时使用（配合 LRO 的operation.WaitForCompletionAsync()）。
3. 始终使用DefaultAzureCredential——绝不硬编码密钥。
4. 处理RequestFailedException：统一捕获 ARM API 错误。
5. 使用CreateOrUpdateAsync做幂等操作（存在即更新，不存在即创建）。
6. 通过Get*方法导航层级（如cache.GetRedisFirewallRules()），不要在业务代码里手工拼 ARM REST URL。
7. 生产环境需要异地复制/集群/持久化时使用 Premium SKU。
8. 启用最低 TLS 1.2：MinimumTlsVersion = RedisTlsVersion.Tls1_2。
9. 关闭非 SSL 端口：EnableNonSslPort = false提升安全性。
10. 定期轮换密钥：用RegenerateKeyAsync轮换并同步更新连接字符串。

九、错误处理模式

ARM API 的错误统一以RequestFailedException抛出，按 HTTP 状态码分流处理：

using Azure; try { var operation = await cacheCollection.CreateOrUpdateAsync( WaitUntil.Completed, cacheName, cacheData); } catch (RequestFailedException ex) when (ex.Status == 409) { Console.WriteLine("Cache already exists"); } catch (RequestFailedException ex) when (ex.Status == 400) { Console.WriteLine($"Invalid configuration: {ex.Message}"); } catch (RequestFailedException ex) { Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}"); }

• 409 Conflict：资源已存在（可用作幂等判断）。
• 400 Bad Request：配置非法（如 SKU 参数错误、容量超出范围）。
• 其他状态码：输出Status、ErrorCode、Message用于排查。

十、常见陷阱

技能文档列出的 7 个高频踩坑点：

1. 不允许降配（SKU downgrades not allowed）——Premium 不能降到 Standard/Basic。
2. 集群（Clustering）仅 Premium——分片配置只在 Premium SKU 上可用。
3. 异地复制（Geo-replication）仅 Premium——Linked Server 只对 Premium 缓存有效。
4. VNet 注入仅 Premium——虚拟网络支持是 Premium 专属。
5. 补丁计划仅 Premium——维护窗口只能在 Premium 上配置。
6. 缓存名称全局唯一——Redis 缓存名必须在所有 Azure 订阅范围内唯一，创建前建议做名称预检（撞名返回 409）。
7. 预配时间长——缓存创建可能需要 15-20 分钟，异步场景务必用WaitUntil.Started+ 轮询，不要同步阻塞。

十一、与 StackExchange.Redis（数据面）衔接

管理面建好缓存后，用StackExchange.Redis做数据操作，两者通过连接字符串对接：

using StackExchange.Redis; // Get connection info from management SDK var cache = await resourceGroup.Value.GetRedisAsync("my-redis-cache"); var keys = await cache.Value.GetKeysAsync(); // Connect with StackExchange.Redis var connectionString = $"{cache.Value.Data.HostName}:{cache.Value.Data.SslPort},password={keys.Value.PrimaryKey},ssl=True,abortConnect=False"; var connection = ConnectionMultiplexer.Connect(connectionString); var db = connection.GetDatabase(); // Data operations await db.StringSetAsync("key", "value"); var value = await db.StringGetAsync("key");

这段代码完整展示了"管理面创建 + 数据面读写"的协作模式：从RedisResource取HostName/SslPort，从GetKeysAsync()取主密钥，拼出带ssl=True、abortConnect=False的连接串。abortConnect=False意味着即使初始连接失败也不抛异常，由连接池后台重试——这是生产环境的推荐配置。仓库中面向自托管 Redis 的 redis 技能 还提供了数据面常用命令（String/Hash/List/Set/SortedSet、Lua 锁、Sentinel、Cluster）的完整参考，可与本文结合阅读。

十二、相关 SDK 一览

Microsoft.Azure.StackExchangeRedis提供了面向 Azure Redis 的扩展（如基于 AAD/RBAC 的令牌认证），在安全要求更高的场景（配合RedisCacheAccessPolicyResource的 RBAC 访问策略）下推荐使用。

十三、使用边界与限制

作为 Agent 技能，本文档的适用范围需要明确：

• 仅在任务明确匹配本技能范围时使用——即"用 .NET ARM SDK 管理 Azure Cache for Redis 资源"。
• 技能输出不能替代环境特定的验证、测试或专家评审；所有示例代码都应先在非生产订阅中验证再执行。
• 若缺少必需输入（订阅 ID、资源组、权限、安全边界或成功标准），应先向用户澄清再行动，避免在未授权范围内创建或删除云资源。
• 需要强调的是，本仓库定位为"技能目录 + 控制平面"，该技能文件本身是文档型技能（docs-only）——它提供可复制的代码与操作指引，但运行时仍需真实 Azure 订阅与凭据支撑。

总结

本文完整继承了azure-resource-manager-redis-dotnet技能的核心内容：从dotnet add package安装、DefaultAzureCredential认证、ArmClient → Subscription → ResourceGroup → RedisResource层级导航，到创建/查询/更新/删除、密钥管理、防火墙、补丁计划、RDB 导入导出、强制重启共 10 个工作流，再到 SKU 容量表、关键类型表、10 条最佳实践、错误处理与 7 大陷阱，最后串联起与StackExchange.Redis的数据面协作。掌握了这些，你就拥有了用 .NET 代码对 Azure Cache for Redis 进行全生命周期"基础设施即代码"式管理的完整能力。

• AI 技能
• AI 插件