Azure 託管 Redis 範例 - ASP.NET Core 網路 API

適用於: ✅ Azure Managed Redis

本範例展示了如何透過 Microsoft Entra ID 認證流程 DefaultAzureCredential ，將 ASP.NET Core Web API 連接到 Azure Managed Redis。該應用程式避免傳統的連線字串驗證，改採基於憑證的 Microsoft Entra ID 存取，這符合現代安全最佳實務。

該應用程式是一個最小 ASP.NET Core 8.0 Web API，具備：

在啟動時建立安全且認證的 Azure Managed Redis 連線。
它公開了一個簡單的 REST 端點，用於讀寫快取中的資料。
透過依賴注入示範正確的 Redis 連線生命週期管理。

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

先決條件

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

必備的 NuGet 套件

Package	目標
`Microsoft.Azure.StackExchangeRedis`	StackExchange.Redis 的擴充方法，使 Microsoft Entra ID 憑證認證能支援 Azure Managed Redis
`StackExchange.Redis`	.NET 底層的 Redis 用戶端函式庫
`Azure.Identity`	提供 `DefaultAzureCredential` 及其他用於 Azure 服務認證的憑證類型
`Swashbuckle.AspNetCore`	Swagger/OpenAPI 對 API 文件與測試的支援

安裝主要套件：

dotnet add package Microsoft.Azure.StackExchangeRedis

這個套件會引入 StackExchange.Redis 和 Azure.Identity 作為依賴。

設定

應用程式會從設定讀取 Redis 端點。更新 appsettings.Development.json：

{
  "Redis": {
    "Endpoint": "<your-redis-name>.<region>.redis.azure.net:10000"
  }
}

備註

Azure Managed Redis 預設使用 port 10000 。端點格式如下 <cache-name>.<region>.redis.azure.net:10000。

認證流程

本機開發

在本地執行應用程式前，請先使用 Azure 進行認證：

az login

DefaultAzureCredential 會自動拾取你的 Azure CLI 憑證，並利用它為 Redis 資源獲取一個存取權杖。此方法消除了本地管理或輪換秘密的需求。

生產環境

在 Azure 託管環境如 App Service、Container Apps 和 AKS， DefaultAzureCredential 會使用：

管理身份 - 系統指派或使用者指派
工作負載識別 - 適用於 Kubernetes 情境
環境變數 - 用於服務主體認證

你不需要更改程式碼。同樣 DefaultAzureCredential 的系統也能無縫地適應環境。

Architecture

Redis 服務（`Services/Redis.cs`）

該 Redis 類別管理連線生命週期：

var options = new ConfigurationOptions()
{
    EndPoints = { endpoint },
    LoggerFactory = _loggerFactory,
};

await options.ConfigureForAzureWithTokenCredentialAsync(new DefaultAzureCredential());

_connection = await ConnectionMultiplexer.ConnectAsync(options);

重點︰

ConfigureForAzureWithTokenCredentialAsync 是從 Microsoft.Azure.StackExchangeRedis 中建立基於憑證認證的擴充方法
DefaultAzureCredential 自動處理代幣的取得與更新
應用程式會在啟動時建立一個連線，並在所有請求間共享該連線。

依賴注入（`Program.cs`）

應用程式會將 Redis 服務註冊為單一執行個體，並在啟動期間初始化：

builder.Services.AddSingleton<Redis>();

// Initialize Redis connection
using (var scope = app.Services.CreateScope())
{
    var redis = scope.ServiceProvider.GetRequiredService<Redis>();
    var endpoint = app.Configuration.GetValue<string>("Redis:Endpoint");
    await redis.ConnectAsync(endpoint);
}

API 控制器（`Controllers/SampleController.cs`）

控制器注入服務 Redis 並示範基本快取操作：

GET /Sample：讀取快取中上一次造訪的時間戳，並更新目前時間

執行應用程式

確保你已取得認證：
```
az login
```
更新appsettings.Development.json中的 Redis 端點。
執行應用程式：
```
dotnet run
```
請導航到 https://localhost:<port>/swagger 以進入 Swagger 介面。

預期的輸出

在呼叫GET /Sample端點時：

第一個請求：

Previous visit was at: 
(Empty value since no previous visit exists)

**Subsequent requests:**
Previous visit was at: 2026-01-30T14:23:45
(Returns the ISO 8601 formatted timestamp of the previous request)

控制台日誌顯示：

info: Microsoft.Azure.StackExchangeRedis.Sample.AspNet.Controllers.SampleController
      Handled GET request. Previous visit time: 2026-01-30T14:23:45

重要實作詳細數據

代幣刷新：函式庫會 Microsoft.Azure.StackExchangeRedis 自動在代幣到期前刷新，所以你不需要手動處理刷新。
連線韌性：來自 ConnectionMultiplexer StackExchange.Redis 的系統自行管理重連邏輯。
資源清理： Redis 服務實作 IDisposable 在應用程式關閉時正確關閉連線。
日誌整合：Redis 用戶端可與 .NET 的ILoggerFactory一起使用，提供統一的日誌輸出。

故障排除

問題	解決辦法
`No connection is available`	驗證端點格式與埠口（`10000`）。確保 Redis 實例已經配置好且可存取。
`AuthenticationFailedException`	執行 `az login` 以刷新憑證。在資源選單的認證選項中，確認你的身份是否被加入為 Redis 使用者。
`Unauthorized`	請確保你的 Microsoft Entra ID 身份在 Azure Managed Redis 實例中被新增為 Redis 使用者。如需詳細資訊，請參閱使用 Microsoft Entra ID 進行快取驗證。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-02-03

共用方式為