快速入門:在 .NET Core 中使用 Azure Managed Redis。

這個 .NET 8 控制台應用程式示範如何使用 Microsoft Entra ID 認證連接 Azure Managed Redis。 核心價值主張是無 密碼認證 並具備自動令牌更新,提供安全且現代化的 Redis 連線方式。

跳至 GitHub 上的程式碼

將 GitHub 上的 Microsoft.Azure.StackExchangeRedis 儲存庫複製到本地。

Prerequisites

  • .NET 8.0 SDK。
  • 在你的 Azure 訂閱中配置一個 Azure Managed Redis 實例。
  • 你的 Azure 使用者或服務主體必須在快取中新增為 Redis 使用者。 在 Azure 入口網站,點到資源選單的 認證 ,選擇 使用者或服務主體,並新增你的身份。
  • Azure CLI 用於本地開發驗證。

必備的 NuGet 套件

Package Purpose
Microsoft.Azure.StackExchangeRedis 擴充函式庫,為 StackExchange 新增 Microsoft Entra ID 認證功能。Redis
Azure.Identity 提供 DefaultAzureCredential 及其他 Azure 身份識別體系實作
StackExchange.Redis 底層的 Redis 客戶端(作為相依性被納入)
Microsoft.Extensions.Logging.Console 診斷用的主控台日誌

驗證方法

該擴充支援多種身份類型,每種類型都有對應 ConfigureForAzure*() 的擴展方法:

  1. DefaultAzureCredential - 推薦的方法。 它會串連多個憑證來源(環境變數、管理身份、Azure CLI 認證、Visual Studio 憑證等等),並使用第一個有效的憑證來源。 它非常適合同時執行本地和 Azure 的程式碼。

  2. 使用者指派受管理識別 - 適用於 Azure 託管應用程式,您透過提供用戶端 ID 明確指定要使用的受管理識別。

  3. System-Assigned 受管理身份 - 適用於使用自動指派給資源的身份的Azure託管應用程式。

  4. 服務主體(密碼) - 用戶端 ID、租戶 ID 及用於自動化或 CI 情境的密碼。

  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. 重新驗證 ——它會用新的令牌重新驗證連線,而不丟棄指令。

為了提高可觀察性,你可以訂閱代幣事件:

Event Purpose
TokenRefreshed 新代幣取得
TokenRefreshFailed 代幣刷新失敗(仍在使用舊代幣)
ConnectionReauthenticated 連線成功重新認證
ConnectionReauthenticationFailed 連線重新驗證失敗

RESP3 與 RESP2 協議

樣本使用 RESP3 (Protocol = RedisProtocol.Resp3),因為:

  • RESP2 會為互動式指令和發佈/訂閱建立獨立連線。
  • 只有互動式連線會被主動重新認證。
  • 當 Pub/sub 連線的 token 到期時會關閉,導致短暫中斷。
  • RESP3 將所有數據多路复用到同一個連線上,避免這些中斷。

Azure 必備條件

  1. 建立一個 Azure 管理的 Redis 實例。
  2. 在「資料存取設定」中啟用 Microsoft Entra ID 認證。
  3. 請以 Redis 使用者身份加入並擁有適當的權限(資料擁有者、資料貢獻者等)。
  4. 在本機執行az login以使用您的 Entra ID 帳戶進行驗證。

基本 Redis 概念

概念 Description
ConnectionMultiplexer 單例,線程安全的 Redis 連線池。 只建立一次,然後在應用程式的整個生命週期內重複使用。
IDatabase 用於執行指令(StringGet、StringSetHashGet等等)的介面。
端點格式 endpoint:10000(TLS)適用於 Azure Managed Redis。

執行範例

az login
cd sample
dotnet run

輸入你的 Redis 端點(例如 <your-redis-name>.<region>.redis.azure.net:10000),選擇驗證方法 1 (DefaultAzureCredential),每當命令成功時,觀察 + 字元每秒印出。 讓它運行超過 60 分鐘,以驗證自動更新權杖是否有效。

生產考量

Setting 樣本值 生產價值
AbortOnConnectFail true false (啟動時重試)
BacklogPolicy FailFast Default (在暫態故障期間將指令排入佇列)
連線壽命 示範循環 辛格爾頓經由DIIConnectionMultiplexer()

本範例提供完整參考實作,適用於任何使用 Azure Managed Redis 的 .NET 應用程式中安全且無密碼的 Entra ID 認證。