.NET Aspire Redis®^* 分散式快取整合

發行項
12/15/2024

瞭解如何使用 .NET AspireRedis 分散式緩存整合。 Aspire.StackExchange.Redis.DistributedCaching 連結庫可用來向 docker.io/library/redis 容器映像註冊 Redisserver 支援的 IDistributedCache 提供者。

瞭解如何使用 .NET AspireRedis 分散式快取整合。 Aspire.StackExchange.Redis.DistributedCaching 庫可以用來註冊由 Garnetserver 支援的 IDistributedCache 提供者，並依據 ghcr.io/microsoft/garnet 的容器映像設置。

瞭解如何使用 .NET AspireRedis 分散式快取整合技術。 Aspire.StackExchange.Redis.DistributedCaching 連結庫可用來向 docker.io/valkey/valkey 容器映像註冊由 Valkeyserver 支援的 IDistributedCache 提供者。

主機託管整合

主機集成 Redis 將 Redis 資源建模為 RedisResource 類型。若要存取此類型和 API，以便將它新增至 📦Aspire專案中的Redis NuGet 套件，在應用程式主機中。

.NET CLI
套件參考

dotnet add package Aspire.Hosting.Redis

<PackageReference Include="Aspire.Hosting.Redis"
                  Version="*" />

如需詳細資訊，請參閱 dotnet add package 或管理 .NET 應用程式中的套件相依性。

新增 Redis 資源

在應用程式主機專案中，呼叫 builder 實例上的 AddRedis，以新增 Redis 資源：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

當 .NET.NET Aspire 將容器映射新增至應用程式主機時，如上述範例中的 docker.io/Redis/Redis 映射所示，它會在本機計算機上建立新的 Redis 實例。 Redis 資源的參考（cache 變數）會新增至 ExampleProject。

WithReference 方法會在名為 "cache"的 ExampleProject 中設定連接。如需詳細資訊，請參閱容器資源生命週期。

提示

如果您想要連線到現有的 Redis 實例，請改為呼叫 AddConnectionString。如需詳細資訊，請參閱參考現有資源。

使用 Redis Insights 新增 Redis 資源

若要將 Redis Insights 新增至 Redis 資源，請呼叫 WithRedisInsight 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisInsight();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

Redis Insights 是一種免費的圖形化介面，可透過 AI 助理 Redis Copilot 協助，分析所有作業系統和 Redis 部署 Redis 數據。 .NET .NET Aspire 將另一個容器映像新增至執行指揮官應用程式的應用程式主機 docker.io/redis/redisinsight。

注意

若要為 RedisInsightResource 鏈設定主機埠，請呼叫 WithHostPort API 並提供所需的埠號碼。

使用 Redis 指揮官新增 Redis 資源

若要將 Redis 指揮官新增至 Redis 資源，請呼叫 WithRedisCommander 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisCommander();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

Redis 指揮官是一個 Node.js Web 應用程式，可用來檢視、編輯和管理 Redis 資料庫。 .NET .NET Aspire 將另一個容器映像新增至執行指揮官應用程式的應用程式主機 docker.io/rediscommander/redis-commander。

提示

若要設定 RedisCommanderResource 鏈的主機埠，請呼叫 WithHostPort API，並提供所需的埠號碼。

新增 Redis 資源並包含數據量

若要將數據磁碟區新增至 Redis 資源，請在 Redis 資源上呼叫 WithDataVolume 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

數據磁碟區可用來將 Redis 數據保存在其容器生命週期之外。數據磁碟區會掛接在 Redis 容器中的 /data 路徑，且未提供 name 參數時，會隨機產生名稱。如需數據磁碟區的詳細資訊，以及它們為何優先於系結掛接的詳細資訊，請參閱 Docker 檔：磁碟區。

使用數據系結掛接新增 Redis 資源

若要將數據系結掛接新增至 Redis 資源，請呼叫 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataBindMount(
                       source: @"C:\Redis\Data",
                       isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

重要

相較於磁碟區，數據系結掛接的功能有限，可提供更佳的效能、可移植性和安全性，使其更適合生產環境。不過，綁定掛載允許直接存取和修改主機系統上的檔案，這使其非常適合需要即時變更的開發和測試工作。

數據系結裝載依賴主計算機的檔案系統，在容器重新啟動時保存 Redis 數據。資料綁定掛載在 Redis 容器中主機上的 C:\Redis\Data 路徑（或 Unix上的 /Redis/Data）。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

新增具有持續性 Redis 資源

若要為 Redis 資源新增持久性，請呼叫 WithPersistence 方法並使用資料卷或資料綁定掛載：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

前述程式碼透過以指定的間隔和閾值捕獲 Redis 數據的快照，增加 Redis 資源的持續性。 interval 是快照集匯出與 keysChangedThreshold 之間的時間，是觸發快照集所需的密鑰變更作業數目。如需持久性的詳細資訊，請參閱 Redis 文件：持久性。

Garnet 託管整合會將 Garnet 資源模型化為 GarnetResource 類型。若要存取此類型和 API，使您能將其新增至 📦Aspire。Hosting.Garnet NuGet 套件於應用程式主機專案中。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Garnet

<PackageReference Include="Aspire.Hosting.Garnet"
                  Version="*" />

如需詳細資訊，請參閱 dotnet add package 或在 .NET 應用程式中管理套件相依性。

新增 Garnet 資源

在應用程式主機專案中，呼叫 AddGarnet 於 builder 實例上以新增 Garnet 資源：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

當 .NET.NET Aspire 將容器映射新增至應用程式主機時，如上述範例中的 ghcr.io/microsoft/garnet 映像所示，它會在本機計算機上建立新的 Garnet 實例。 Garnet 資源的參照（cache 變數）新增至 ExampleProject。

WithReference 方法會在名為 "cache"的 ExampleProject 中設定連接。如需詳細資訊，請參閱容器資源生命週期。

提示

如果您想要連線到現有的 Garnet 實例，請改為呼叫 AddConnectionString。如需詳細資訊，請參閱參考現有資源。

新增資料容量的 Garnet 資源

若要將數據量新增至 Garnet 資源，請在 Garnet 資源上呼叫 AddGarnet 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

數據磁碟區用來將 Garnet 資料保存在其容器生命週期之外。資料卷會掛載在 Garnet 容器中的 /data 路徑，當未提供 name 參數時，會隨機生成名稱。如需有關資料磁碟區的詳情，以及它們為何優於系結掛接的詳情，請參閱 Docker 文件：磁碟區。

使用數據系結掛接新增 Garnet 資源

若要將數據系結掛接新增至 Garnet 資源，請呼叫 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataBindMount(
                       source: @"C:\Garnet\Data",
                       isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

重要

相較於磁碟區，數據系結掛接的功能有限，可提供更佳的效能、可移植性和安全性，使其更適合生產環境。不過，bind mounts 允許直接存取和修改主機系統上的檔案，非常適合用於開發和測試中需要即時變更的情況。

數據系結掛接依賴主計算機的文件系統，在容器重新啟動時保存 Garnet 數據。數據系結掛接會掛接在 Windows 上的 C:\Garnet\Data （或 Unix上的 /Garnet/Data ）路徑上，位於 Garnet 容器中的主電腦上。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

新增具持久性的 Garnet 資源

若要將持續性新增至 Garnet 資源，請使用資料磁碟區或數據綁定掛載來呼叫 WithPersistence 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

上述程式碼會在指定的間隔和閾值下擷取 Garnet 數據的快照，將持續性新增至 Redis 資源。 interval 是快照集匯出與 keysChangedThreshold 之間的時間，是觸發快照集所需的密鑰變更作業數目。如需了解更多關於資料保存的資訊，請參閱 Redis 檔案：保存性。

Valkey 主機整合將 Valkey 資源建模為 ValkeyResource 類型。若要存取此類型和 API，可讓您將它新增至 📦Aspire。Hosting.Valkey 應用程式主機專案中的 NuGet 套件。

.NET 命令行界面
PackageReference

dotnet add package Aspire.Hosting.Valkey

<PackageReference Include="Aspire.Hosting.Valkey"
                  Version="*" />

如需詳細資訊，請參閱 dotnet add package 或管理 .NET 應用程式中的套件相依性。

新增 Valkey 資源

在應用程式主機專案中，呼叫 builder 實例上的 AddValkey 以新增 Valkey 資源：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

當 .NET.NET Aspire 將容器映像檔新增至應用程式主機時，如上述範例中所示的 docker.io/valkey/valkey 映像檔，它會在本地電腦上建立新的 Valkey 實例。將 Valkey 資源的參考（cache 變數）新增到 ExampleProject。

WithReference 方法會在名為 "cache"的 ExampleProject 中設定連接。如需詳細資訊，請參閱容器資源生命週期。

提示

如果您想要連線到現有的 Valkey 實例，請改為呼叫 AddConnectionString。如需詳細資訊，請參閱參考現有資源。

使用數據量來新增 Valkey 資源

若要將數據磁碟區新增至 Valkey 資源，請在 Valkey 資源上呼叫 AddValkey 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

數據磁碟區用來將 Valkey 數據保存在其容器生命週期之外。數據磁碟區會掛接在 Valkey 容器中的 /data 路徑，且未提供 name 參數時，會隨機產生名稱。如需數據磁碟區的詳細資訊，以及它們為何優先於系結掛接的詳細資訊，請參閱 Docker 檔：磁碟區。

使用數據系結掛接新增 Valkey 資源

若要將數據系結掛接新增至 Valkey 資源，請呼叫 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataBindMount(
                       source: @"C:\Valkey\Data",
                       isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

重要

相較於磁碟區，數據系結掛接的功能有限，可提供更佳的效能、可移植性和安全性，使其更適合生產環境。不過，綁定掛載允許直接存取和修改主機系統上的檔案，非常適合用於需要即時變更的開發和測試。

數據系結掛接依賴主計算機的文件系統，在容器重新啟動時保存 Valkey 數據。數據掛載會掛載於 Windows 上的 C:\Valkey\Data 路徑（或 Unix上的 /Valkey/Data 路徑），位於 Valkey 容器中的主機上。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

新增具有持續性的 Valkey 資源

若要將持續性新增至 Valkey 資源，請使用資料磁碟區或資料綁定掛載來呼叫 WithPersistence 函式：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

上述程式碼透過在指定的時間間隔和閾值下對 Valkey 數據進行快照擷取，為 Redis 資源新增持久性。 interval 是快照集匯出與 keysChangedThreshold 之間的時間，是觸發快照集所需的密鑰變更作業數目。如需持久性的詳細資訊，請參閱 Redis 檔案：持久性。

主機整合健康檢查

託管整合 Redis 會自動為適當的資源類型新增健康檢查。健康檢查會確認 server 正在運行中，且可以建立與其的連線。

裝載整合依賴 📦 AspNetCore.HealthChecks。Redis NuGet 套件。

Client 整合

若要開始使用 .NET AspireRedis 分散式快取整合，請在 client使用者專案中安裝 📦Aspire.StackExchange.Redis.DistributedCaching NuGet 套件，也就是使用 Redis 分散式快取 client的應用程式專案。

.NET 命令行介面
PackageReference

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

<PackageReference Include="Aspire.StackExchange.Redis.DistributedCaching"
                  Version="*" />

新增 Redisclient

在 client專案的 Program.cs 檔案中，呼叫 AddRedisDistributedCache 延伸模組來註冊分散式快取所需的服務，並新增 IDistributedCache 以便透過相依性注入容器來使用。

builder.AddRedisDistributedCache(connectionName: "cache");

提示

connectionName 參數必須符合在應用程式主專案中新增 Redis 資源時所使用的名稱。如需詳細資訊，請參閱添加 Redis 資源。

提示

connectionName 參數必須符合在應用程式主機專案中新增 Garnet 資源時所使用的名稱。如需詳細資訊，請參閱新增 Garnet 資源。

提示

connectionName 參數必須符合在應用程式主機專案中新增 Valkey 資源時所使用的名稱。如需詳細資訊，請參閱新增 Valkey 資源（）。

接著，您可以使用依賴注入來擷取 IDistributedCache 實例。例如，若要從一個服務擷取快取：

public class ExampleService(IDistributedCache cache)
{
    // Use cache...
}

如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

新增索引鍵 Redisclient

在某些情況下，您可能想要以不同的連線名稱註冊多個 IDistributedCache 實例。若要註冊特定的 Redis 用戶端，請呼叫 AddKeyedRedisDistributedCache 方法：

builder.AddKeyedRedisDistributedCache(name: "chat");
builder.AddKeyedRedisDistributedCache(name: "product");

然後，您可以使用依賴注入來擷取 IDistributedCache 實例。例如，若要從範例服務擷取連線：

public class ExampleService(
    [FromKeyedServices("chat")] IDistributedCache chatCache,
    [FromKeyedServices("product")] IDistributedCache productCache)
{
    // Use caches...
}

如需鍵控服務的詳細資訊，請參閱 .NET 相依性插入：鍵控服務。

配置

.NET Aspire Redis 分散式快取整合提供多個選項，依據專案需求與慣例配置 Redis 連線。

使用連接字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 builder.AddRedisDistributedCache時提供連接字串的名稱：

builder.AddRedisDistributedCache("cache");

然後，連接字串將會從 [ConnectionStrings 組態] 區段擷取：

{
  "ConnectionStrings": {
    "cache": "localhost:6379"
  }
}

如需如何格式化此連接字串的詳細資訊，請參閱 Stack Exchange Redis 組態檔。

使用組態提供者

.NET Aspire Stack Exchange Redis 整合支援 Microsoft.Extensions.Configuration。它會使用 Aspire:StackExchange:Redis 鍵從組態載入 StackExchangeRedisSettings。以下為設定部分選項的範例 appsettings.json：

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

如需完整的 Redisclient 整合 JSON 架構，請參閱 Aspire。StackExchange。Redis/ConfigurationSchema。json。

使用內聯委派

您也可以傳遞 Action<StackExchangeRedisSettings> 委派函式來直接設定部分或全部選項，例如設定 DisableTracing：

builder.AddRedisDistributedCache(
    "cache",
    settings => settings.DisableTracing = true);

您也可以使用 AddRedisDistributedCache 方法的 Action<ConfigurationOptions> configureOptions 委派參數來設定 ConfigurationOptions。例如，將連線超時設定為：

builder.AddRedisDistributedCache(
    "cache",
    static settings => settings.ConnectTimeout = 3_000);

健康檢查

根據預設，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

.NET Aspire Redis 分散式快取整合會處理下列事項：

新增 StackExchange.Redis 健康情況檢查、嘗試開啟連線，並在失敗時擲回。
與 /health HTTP 端點整合，該端點指定所有已註冊的健康檢查必須通過，應用程式才會被視為已準備好接收流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和度量配置，有時稱為 可觀測性的支柱。如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。視支援服務而定，某些整合可能只支援其中一些功能。例如，某些整合支援記錄和追蹤，但不支援計量。您也可以使用組態一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire Redis 分散式快取整合會使用下列日誌類別：

Aspire.StackExchange.Redis
Microsoft.Extensions.Caching.StackExchangeRedis

追蹤

.NET Aspire Redis 分散式快取整合會使用 OpenTelemetry發出下列追蹤活動：

OpenTelemetry.Instrumentation.StackExchangeRedis

指標

.NET Aspire Redis 分散式快取整合目前預設不支援計量，這是因為 StackExchange.Redis 程式庫的限制。

Azure Redis 主機整合

若要將 Redis 資源部署至 Azure，請安裝 📦Aspire主機AzureRedis NuGet 套件：

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Redis

<PackageReference Include="Aspire.Hosting.Azure.Redis"
                  Version="*" />

新增 Azure Cache for Redisserver 資源

安裝 .NET Aspire 主機 AzureRedis 套件之後，請在應用程式主機專案中呼叫 AddAzureRedis 擴展方法：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cache);

對 AddAzureRedis 的上述呼叫將 Redisserver 資源配置為 Azure Cache for Redis。

重要

根據預設，AddAzureRedis 會設定 Microsoft Entra ID 驗證。這需要變更需要連線到這些資源的應用程式，例如 client 介接。

新增分散式 Azure Cache for Redisclient

根據預設，當您在 Redis 裝載整合中呼叫 AddAzureRedis 時，它會配置 📦 的 MicrosoftAzure.StackExchangeRedis NuGet 套件以啟用驗證：

.NET CLI（命令列介面）
PackageReference

dotnet add package Microsoft.Azure.StackExchangeRedis

<PackageReference Include="Microsoft.Azure.StackExchangeRedis"
                  Version="*" />

您可以使用 client 整合和 Microsoft.Azure.StackExchangeRedis來取用 Redis 連線。請考慮下列配置程式代碼：

var azureOptionsProvider = new AzureOptionsProvider();

var configurationOptions = ConfigurationOptions.Parse(
    builder.Configuration.GetConnectionString("cache") ?? 
    throw new InvalidOperationException("Could not find a 'cache' connection string."));

if (configurationOptions.EndPoints.Any(azureOptionsProvider.IsMatch))
{
    await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(
        new DefaultAzureCredential());
}

builder.AddRedisDistributedCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

如需詳細資訊，請參閱 MicrosoftAzure.StackExchangeRedis 資料庫。

另請參閱

*：Redis 是 Redis 有限公司的註冊商標。任何權利都保留給 Redis 有限公司。Microsoft 的使用僅作參考用途，且不表示 Redis 與 Microsoft 之間有任何贊助、認可或合作關係。返回頂端？

共用方式為

.NET Aspire Redis®^* 分散式快取整合

主機託管整合

新增 Redis 資源

使用 Redis Insights 新增 Redis 資源

使用 Redis 指揮官新增 Redis 資源

新增 Redis 資源並包含數據量

使用數據系結掛接新增 Redis 資源

新增具有持續性 Redis 資源

新增 Garnet 資源

新增資料容量的 Garnet 資源

使用數據系結掛接新增 Garnet 資源

新增具持久性的 Garnet 資源

新增 Valkey 資源

使用數據量來新增 Valkey 資源

使用數據系結掛接新增 Valkey 資源

新增具有持續性的 Valkey 資源

主機整合健康檢查

Client 整合

新增 Redisclient

新增索引鍵 Redisclient

配置

使用連接字串

使用組態提供者

使用內聯委派

健康檢查

可檢視性和遙測

伐木

追蹤

指標

Azure Redis 主機整合

新增 Azure Cache for Redisserver 資源

新增分散式 Azure Cache for Redisclient

另請參閱

其他資源

共用方式為

.NET Aspire Redis®* 分散式快取整合

主機託管整合

新增 Redis 資源

使用 Redis Insights 新增 Redis 資源

使用 Redis 指揮官新增 Redis 資源

新增 Redis 資源並包含數據量

使用數據系結掛接新增 Redis 資源

新增具有持續性 Redis 資源

新增 Garnet 資源

新增資料容量的 Garnet 資源

使用數據系結掛接新增 Garnet 資源

新增具持久性的 Garnet 資源

新增 Valkey 資源

使用數據量來新增 Valkey 資源

使用數據系結掛接新增 Valkey 資源

新增具有持續性的 Valkey 資源

主機整合健康檢查

Client 整合

新增 Redisclient

新增索引鍵 Redisclient

配置

使用連接字串

使用組態提供者

使用內聯委派

健康檢查

可檢視性和遙測

伐木

追蹤

指標

Azure Redis 主機整合

新增 Azure Cache for Redisserver 資源

新增分散式 Azure Cache for Redisclient

另請參閱

其他資源

.NET Aspire Redis®^* 分散式快取整合