.NET Aspire Redis輸出快取整合 ®^*

發行項
12/12/2024

了解如何使用 .NET AspireRedis 的輸出快取整合功能。 Aspire.StackExchange.Redis.OutputCaching client 整合用於將由 Redisserver 支援的 ASP.NET Core 輸出快取提供者註冊到 docker.io/library/redis 容器映像。

學習如何使用 .NET AspireRedis 輸出快取整合。 Aspire.StackExchange.Redis.OutputCaching client 整合用於註冊由 Garnetserver 支援的 ASP.NET Core 輸出快取提供者，並依賴於 ghcr.io/microsoft/garnet 容器映像。

瞭解如何使用 .NET AspireRedis 輸出緩存整合。 Aspire.StackExchange.Redis.OutputCaching client 整合用於註冊由 Valkeyserver 支援的 ASP.NET Core 輸出快取提供者到 docker.io/valkey/valkey 容器映像。

主機整合

託管整合 Redis 將 Redis 資源建模為 RedisResource 類型。若要存取此類型和 API，您可以使用 NuGet 套件，將其新增至 .Hosting. 應用程式主機專案。

.NET CLI
PackageReference

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 容器中的主機上掛載到 Windows 的 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 資源

在應用程式主機專案中，於 builder 實例上呼叫 AddGarnet 以新增 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...

重要

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

數據系結掛接依賴主計算機的文件系統，在容器重新啟動時保存 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 CLI
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 Aspire Stack Exchange Redis 輸出快取 client 整合，請在 client消費專案中安裝 📦Aspire。StackExchange。Redis。OutputCaching NuGet 套件，也就是使用輸出快取的應用程式專案 client。

.NET CLI
PackageReference

dotnet add package Aspire.StackExchange.Redis.OutputCaching

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

新增輸出快取

在 client使用的項目的 Program.cs 檔案中，於任何 IHostApplicationBuilder 調用 AddRedisOutputCache 擴展方法，以註冊輸出快取所需的服務。

builder.AddRedisOutputCache(connectionName: "cache");

提示

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

提示

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

提示

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

藉由呼叫 UseOutputCache(IApplicationBuilder)，將中間件新增至要求處理管線：

var app = builder.Build();

app.UseOutputCache();

針對最低 API 應用程式，請設定端點以透過呼叫 CacheOutput來執行快取，或套用 OutputCacheAttribute，如下列範例所示：

app.MapGet("/cached", () => "Hello world!")
   .CacheOutput();

app.MapGet(
    "/attribute",
    [OutputCache] () => "Hello world!");

對於具有控制器的應用程式，請將 [OutputCache] 屬性套用至動作方法。針對 Razor Pages 應用程式，將屬性套用至 Razor 頁面類別。

配置

.NET Aspire Stack Exchange Redis 輸出快取集成提供多個選項，根據專案的需求和慣例來設定 Redis 連線。

使用連接字串

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

builder.AddRedisOutputCache(connectionName: "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> configurationSettings 委派來直接在程式碼中設定部分或所有選項，例如使用程式碼來停用健康檢查：

builder.AddRedisOutputCache(
    "cache",
    static settings => settings.DisableHealthChecks  = true);

您也可以使用 AddRedisOutputCache 方法的 Action<ConfigurationOptions> configureOptions 委派參數來設定 ConfigurationOptions。例如，設定連線逾時，可以這樣做：

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

健康檢查

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

.NET Aspire Stack Exchange Redis 的輸出快取整合處理以下事項：

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

可檢視性和遙測

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

伐木

.NET Aspire Stack Exchange Redis 輸出快取整合會使用下列記錄類別：

Aspire.StackExchange.Redis
Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

追蹤

.NET Aspire Stack Exchange Redis 的輸出快取整合會透過 OpenTelemetry發出下列追蹤活動：

OpenTelemetry.Instrumentation.StackExchangeRedis

指標

.NET Aspire Stack Exchange Redis 輸出快取整合目前由於 StackExchange.Redis 函式庫的限制，預設不支援度量。

Azure Redis 主機托管整合

若要將 Redis 資源部署至 Azure，請安裝 📦Aspire.Hosting.Azure.Redis 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 Redis 輸出 client

預設情況下，當您在主機整合 Redis 中呼叫 AddAzureRedis 時，它會配置 📦 MicrosoftAzureStackExchangeRedis 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.AddRedisOutputCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

如需詳細資訊，請參閱 MicrosoftAzureStackExchangeRedis 儲存庫。

另請參閱

*：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 整合

新增輸出快取

配置

使用連接字串

使用組態提供者

使用內嵌委派

健康檢查

可檢視性和遙測

伐木

追蹤

指標

Azure Redis 主機托管整合

新增 Azure Cache for Redisserver 資源

新增 Azure Cache for Redis 輸出 client

另請參閱

其他資源

共用方式為

.NET Aspire Redis輸出快取整合 ®*

主機整合

新增 Redis 資源

使用 Redis Insights 新增 Redis 資源

使用 Redis 指揮官新增 Redis 資源

新增包含數據量的 Redis 資源

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

新增具有持續性 Redis 資源

新增 Garnet 資源

新增帶有數據量的 Garnet 資源

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

新增具有持續性的 Garnet 資源

新增 Valkey 資源

新增具有數據量的 Valkey 資源

新增 Valkey 資源並使用資料綁定掛載

新增具有持續性的 Valkey 資源

主機整合健康檢查

Client 整合

新增輸出快取

配置

使用連接字串

使用組態提供者

使用內嵌委派

健康檢查

可檢視性和遙測

伐木

追蹤

指標

Azure Redis 主機托管整合

新增 Azure Cache for Redisserver 資源

新增 Azure Cache for Redis 輸出 client

另請參閱

其他資源

.NET Aspire Redis輸出快取整合 ®^*