快速入门：在 .NET Core 中使用 Azure 托管 Redis

此 .NET 8 控制台应用程序演示如何使用 Microsoft Entra ID 身份验证连接到 Azure 托管 Redis。 核心价值主张是使用自动令牌刷新进行 无密码身份验证 ，提供安全的新式 Redis 连接方法。

跳转到 GitHub 查看代码

克隆 GitHub 上的 Microsoft.Azure.StackExchangeRedis 存储库。

先决条件

• .NET 8.0 SDK。
• 在 Azure 订阅中预配的 Azure 托管 Redis 实例。
• Azure 用户或服务主体必须作为 Redis 用户被添加到缓存中。 在 Azure 门户中，转到“资源”菜单上的 “身份验证 ”，选择 “用户或服务主体”，然后添加标识。
• 用于本地开发身份验证的 Azure CLI。

所需的 NuGet 软件包

Package	目的
Microsoft.Azure.StackExchangeRedis	将 Microsoft Entra ID 身份验证添加到 StackExchange.Redis 的扩展库
Azure.Identity	提供 DefaultAzureCredential 和其他 Azure 标识实现
StackExchange.Redis	作为依赖项引入的底层 Redis 客户端
Microsoft.Extensions.Logging.Console	用于诊断的控制台日志记录

身份验证方法

该扩展支持多个标识类型，每个类型都有相应的 ConfigureForAzure*() 扩展方法：

1. DefaultAzureCredential - 建议的方法。 它链接多个凭据源（环境变量、托管标识、Azure CLI 身份验证、Visual Studio 凭据等），并使用第一个有效凭据源。 它非常适合在本地和 Azure 中运行的代码。

2. 用户分配的托管标识 - 对于 Azure 托管的应用，可通过提供其客户端 ID 显式指定要使用的托管标识。

3. 系统分配的托管标识 - 适用于使用自动分配给资源的标识的 Azure 托管应用。

4. 服务主体（机密） - 自动或 CI 方案的客户端 ID、租户 ID 和机密。

5. 服务主体（证书） - 用于提高安全性的客户端 ID、租户 ID 和 X.509 证书。

本地运作方式DefaultAzureCredential

在本地开发时， DefaultAzureCredential 尝试使用以下方法进行身份验证：

az login

此方法使用 Microsoft Entra ID 帐户登录到 Azure CLI。 SDK 会检测缓存的凭据，并使用它们来获取令牌。 您必须通过 Azure 门户中“资源”菜单下的“身份验证”，将您的 Microsoft Entra ID 用户配置为 Azure 托管Redis 资源的 Redis 用户。

关键实现模式

连接配置：

ConfigurationOptions configurationOptions = new()
{
    Protocol = RedisProtocol.Resp3,  // Recommended for seamless re-auth
    LoggerFactory = loggerFactory,
    AbortOnConnectFail = true,       // Fail fast (use false in production)
    BacklogPolicy = BacklogPolicy.FailFast
};

Entra ID 设置：

await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(new DefaultAzureCredential());
var connection = await ConnectionMultiplexer.ConnectAsync(configurationOptions);

基本 Redis 操作：

var database = connection.GetDatabase();
await database.StringSetAsync("key", "value");
var value = await database.StringGetAsync("key");

令牌生命周期和自动重新身份验证

该扩展会自动处理 OAuth2 令牌生命周期：

1. 初始获取 - 它在连接之前获取令牌。
2. 主动刷新 - 令牌过期（大约一小时）之前，它会在后台获取一个新的令牌。
3. 重新身份验证 - 无需删除命令即可重新验证与新令牌的连接。

为实现可观测性，你可以订阅令牌事件：

事件	目的
TokenRefreshed	获取的新令牌
TokenRefreshFailed	令牌刷新失败（仍在使用旧令牌）
ConnectionReauthenticated	连接已成功重新进行身份验证
ConnectionReauthenticationFailed	连接重新身份验证失败

RESP3 与 RESP2 协议

此示例使用 RESP3 （Protocol = RedisProtocol.Resp3），因为：

• RESP2 为互动命令和发布/订阅创建单独的连接。
• 仅交互式连接会主动重新进行身份验证。
• 发布/订阅连接在令牌过期时关闭，导致短暂中断。
• RESP3 在一个连接上多路复用所有内容，避免这些中断。

Azure 先决条件

1. 创建 Azure 托管 Redis 实例。
2. 在“数据访问配置”下启用Microsoft Entra ID 身份验证。
3. 将您的身份添加为具有适当权限的 Redis 用户（数据拥有者、数据贡献者等）。
4. 运行 az login 在本地使用 Entra ID 帐户进行身份验证。

基本 Redis 概念

概念	Description
ConnectionMultiplexer	面向 Redis 的单例、线程安全的连接池。 创建一次，并在应用生存期内重复使用它。
IDatabase	用于执行命令的接口（StringGet、StringSet、HashGet等）。
终结点格式	endpoint:10000 （TLS） 用于 Azure 托管 Redis。

运行示例

az login
cd sample
dotnet run

输入 Redis 终结点（例如 <your-redis-name>.<region>.redis.azure.net:10000），选择身份验证方法 1（DefaultAzureCredential），并观看命令成功时每秒打印的 + 字符。 让它运行超过 60 分钟来验证自动令牌刷新是否正常工作。

生产注意事项

设置	示例值	生产价值
AbortOnConnectFail	true	false （启动时重试）
BacklogPolicy	FailFast	Default（在暂时性故障期间排队命令）
连接生存期	演示循环	通过 DI (IConnectionMultiplexer) 实现单例

此示例提供了使用 Azure 托管 Redis 的任何 .NET 应用程序中安全无密码的 Entra ID 身份验证的完整参考实现。

相关内容

• 连接复原能力
• 最佳做法开发