適用於 Azure Redis 快取的 ASP.NET 輸出快取提供者

Redis 輸出快取提供者為輸出快取資料的程序外儲存體機制。 此資料特別適用於完整 HTTP 回應 (頁面輸出快取)。 提供者插入 ASP.NET 4 中導入的新輸出快取提供者擴充點。

如需 ASP.NET Core 應用程式，請參閱 在 .NET 8 中使用 Redis 在 ASP.NET 核心中輸出快取。

若要使用 Redis 輸出快取提供者，請先設定您的快取，然後使用「Redis 輸出快取提供者 NuGet 封裝」設定 ASP.NET 應用程式。 本文提供設定應用程式使用 Redis 輸出快取提供者的指引。 如需建立和設定 Azure 受控 Redis 實例的詳細資訊（預覽版）實例，請參閱 建立快取。

在 Redis 中儲存 ASP.NET 核心頁面輸出

如需完整的功能規格，請參閱 ASP.NET 核心輸出快取。

如需示範使用方式的範例應用程式，請參閱 使用 Redis 輸出快取和 Azure OpenAI 的 .NET 8 Web 應用程式。

在 Redis 中儲存 ASP.NET 頁面輸出

若要在 Visual Studio 中，使用 Azure Cache for Redis 工作階段狀態 NuGet 套件來設定用戶端應用程式，請從 [工具] 功能表，依序選取 [NuGet 套件管理員] 和 [套件管理員主控台]。

從 Package Manager Console 視窗執行下列命令：

Install-Package Microsoft.Web.RedisOutputCacheProvider

Redis 輸出快取提供者 NuGet 套件相依於 StackExchange.Redis 套件。 如果您的項目中沒有 StackExchange.Redis 套件，則會安裝它。 如需「Redis 輸出快取提供者 NuGet 套件」的詳細資訊，請參閱 RedisOutputCacheProvider (英文) NuGet 頁面。

NuGet 封裝會下載和加入必要的組件參考，並將下列區段加入您的 web.config 檔案。 此區段包含讓您的 ASP.NET 應用程式使用 Redis 輸出快取提供者所需的設定。

<caching>
  <outputCache defaultProvider="MyRedisOutputCache">
    <providers>
      <add name="MyRedisOutputCache" type="Microsoft.Web.Redis.RedisOutputCacheProvider"
           host=""
           accessKey=""
           ssl="true" />
    </providers>
  </outputCache>
</caching>

使用 Microsoft Azure 入口網站中快取的值，設定第一個資料行中的屬性。 並設定您要的其他值。 如需關於存取快取屬性的指示，請參閱設定 Azure Cache for Redis 設定。

屬性	類型	預設	描述
_host*	字串	"localhost"	Redis 伺服器 IP 位址或主機名稱
port	正整數	6379 (non-TLS/SSL) 6380 (TLS/SSL) 10000 for Redis Enterprise 和 Azure 受控 Redis （預覽）	Redis 伺服器連接埠
accessKey	string	""	啟用 Redis 授權後，Redis 伺服器的密碼。 此值預設為空字串，這表示工作階段狀態提供者在連線到 Redis 伺服器時不會使用任何密碼。 如果您的 Redis 伺服器位於可公開存取的網路，例如 Azure Cache for Redis，請務必啟用 Redis 授權改善安全性，並提供安全的密碼。
ssl	boolean	false	是否透過 TLS 連線 Redis 伺服器。 此值預設為 false，因為 Redis 預設不支援 TLS。 如果您使用 Azure Cache for Redis (預設支援 SSL)，請務必將此值設為 true 以改善安全性。 新的快取預設停用非 TLS 連接埠。 若要使用非 TLS 連接埠，請指定此設定為 true。 如需啟用非 TLS 連接埠的詳細資訊，請參閱設定快取文章中的存取連接埠一節。
databaseIdNumber	正整數	0	此屬性只能透過 web.config 或 AppSettings 指定。 指定要使用的 Redis 資料庫。
connectionTimeoutInMilliseconds	正整數	由 StackExchange.Redis 提供	建立 StackExchange.Redis.ConnectionMultiplexer 時，用來設定 ConnectTimeout。
operationTimeoutInMilliseconds	正整數	由 StackExchange.Redis 提供	建立 StackExchange.Redis.ConnectionMultiplexer 時，用來設定 SyncTimeout。
connectionString (有效的 StackExchange.Redis 連接字串)	string	不適用	AppSettings 或 web.config 的參數參考，亦或有效的 StackExchange.Redis 連接字串。 此屬性可以提供「主機」、「連接埠」、accessKey、ssl 和其他 StackExchange.Redis 屬性的值。 如需深入了解 connectionString，請參閱屬性附註一節中的設定 connectionString。
settingsClassName settingsMethodName	string string	不適用	這些屬性只能透過 web.config 或 AppSettings 指定。 使用這些屬性提供連接字串。 _settingsClassName* 應該是組件限定類別名稱，其中包含 settingsMethodName 所指定的方法。 settingsMethodName 指定的方法應該是公用、靜態且無效 (不接受參數)，並使用字串傳回類別。 此方法會傳回實際的連接字串。
loggingClassName loggingMethodName	string string	不適用	這些屬性只能透過 web.config 或 AppSettings 指定。 您可以提供工作階段狀態/輸出快取的記錄，及 StackExchange.Redis 的記錄，然後使用這些屬性偵錯您的應用程式。 loggingClassName 應該是組件限定類別名稱，並包含 loggingMethodName 指定的方法。 loggingMethodName 指定的方法應該是公用、靜態且無效 (不接受參數)，並使用 System.IO.TextWriter 傳回類別。
applicationName	string	目前進度的模組名稱或「/」	僅限 SessionStateProvider 此屬性只能透過 web.config 或 AppSettings 指定。 在 Redis 快取中使用的應用程式名稱前置詞。 客戶可能會針對不同的用途使用相同的 Redis 快取。 為了確保工作階段金鑰不會衝突，它的前面可以加上應用程式名稱。
throwOnError	boolean	true	僅限 SessionStateProvider 此屬性只能透過 web.config 或 AppSettings 指定。 錯誤發生時是否擲回例外狀況。 如需 throwOnError 的詳細資訊，請參閱屬性附註一節中的 throwOnError 附註」。
retryTimeoutInMilliseconds	正整數	5000	僅限 SessionStateProvider 此屬性只能透過 web.config 或 AppSettings 指定。 作業失敗時重試的時間長度。 如果此值小於 operationTimeoutInMilliseconds，則提供者不會重試。 如需 retryTimeoutInMilliseconds 的詳細資訊，請參閱屬性附註一節中的 retryTimeoutInMilliseconds 附註」。
redisSerializerType	string	不適用	指定實作 Microsoft.Web.Redis 類別的組件限定類別名稱。 序列化程式與包含自訂邏輯的序列化程式，可將值序列化並還原序列化。 如需詳細資訊，請參閱屬性附註一節中的關於 redisSerializerType。

屬性附註

設定 connectionString

connectionString 的值會作為金鑰，從 AppSettings 擷取實際的連接字串 (如果 AppSettings 有這類字串)。 如果在 AppSettings 內找不到，則會使用 connectionString 的值會作為索引鍵，從 web.config ConnectionString 區段擷取實際連接字串，如果該區段存在。 如果 AppSettings 或 web.config ConnectionString 區段中沒有連接字串，則建立 StackExchange.Redis.ConnectionMultiplexer 時，會使用 connectionString 的常值作為連接字串。

下列範例說明使用 connectionString 的方式。

範例 1

<connectionStrings>
    <add name="MyRedisConnectionString" connectionString="mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False" />
</connectionStrings>

在 web.config 中，使用索引鍵作為參數值，而不是實際值。

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             connectionString = "MyRedisConnectionString"/>
    </providers>
</sessionState>

範例 2

<appSettings>
    <add key="MyRedisConnectionString" value="mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False" />
</appSettings>

在 web.config 中，使用索引鍵作為參數值，而不是實際值。

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             connectionString = "MyRedisConnectionString"/>
    </providers>
</sessionState>

範例 3

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             connectionString = "mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False"/>
    </providers>
</sessionState>

throwOnError 的注意事項

目前，如果工作階段作業期間發生錯誤，則工作階段狀態提供者會擲回例外狀況。 擲回例外狀況會關閉應用程式。

此行為已修改，其支援現有 ASP.NET 工作階段狀態提供者使用者的期望，同時允許您對例外狀況採取行動。 錯誤發生時，其預設行為與其他 ASP.NET 工作階段狀態提供者一致，仍會擲回例外狀況。 現有程式碼的運作應與之前相同。

如果您將 throwOnError 設為 false，則發生錯誤時不會擲回例外狀況，而是以無訊息方式失敗。 若要查看是否有錯誤，如果是，請探索例外狀況是什麼，即檢查靜態屬性 Microsoft.Web.Redis.RedisSessionStateProvider.LastException。

retryTimeoutInMilliseconds 的注意事項

retryTimeoutInMilliseconds 設定提供部分邏輯，以簡化網路或其他問題導致工作階段失敗必須重試的案例。 此外，retryTimeoutInMilliseconds 設定讓您可以控制重試逾時或完全退出重試。

如果您 將 retryTimeoutInMilliseconds 設定為一個數，例如 2000，當工作階段作業失敗時，它會重試 2,000 毫秒，再將它視為錯誤。 若要為工作階段狀態提供者套用此重試邏輯，請直接設定逾時。 第一次重試會在 20 毫秒後發生，在大部分發生網路問題的案例中，20 毫秒很充足。 之後，其會每秒重試一次，直到逾時為止。逾時後，其會再重試一次，以確保不會一秒 (最長) 截斷逾時。

如果您認為不需要重試，或要自行處理重試邏輯，請將 retryTimeoutInMilliseconds 設為 0。 例如，在與應用程式相同的機器上執行 Redis 伺服器時，您可能不想重試。

關於 redisSerializerType

根據預設，在 Redis 上儲存值的序列化會以二進位格式完成，而二進位格式是由 BinaryFormatter 類別提供。 使用 redisSerializerType 指定實作 Microsoft.Web.Redis.ISerializer 類別的組件限定類別名稱，並使用自訂邏輯將值序列化或還原序列化。 例如，以下是使用 JSON.NET 的 JSON 序列化程式類別：

namespace MyCompany.Redis
{
    public class JsonSerializer : ISerializer
    {
        private static JsonSerializerSettings _settings = new JsonSerializerSettings() { TypeNameHandling = TypeNameHandling.All };

        public byte[] Serialize(object data)
        {
            return Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(data, _settings));
        }

        public object Deserialize(byte[] data)
        {
            if (data == null)
            {
                return null;
            }
            return JsonConvert.DeserializeObject(Encoding.UTF8.GetString(data), _settings);
        }
    }
}

假設此類別是在名為 MyCompanyDll 的組件中定義，則您可以將 redisSerializerType 參數設為使用此組件：

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             redisSerializerType = "MyCompany.Redis.JsonSerializer,MyCompanyDll"
             ... />
    </providers>
</sessionState>

輸出快取指示詞

將 OutputCache 指示詞新增至每一個您要快取輸出的頁面。

<%@ OutputCache Duration="60" VaryByParam="*" %>

在上一個範例中，已快取的頁面資料會留在快取中 60 秒，而且會對每一個參數組合快取不同版本的頁面。 如需 OutputCache 指示詞的詳細資訊，請參閱 @OutputCache。

執行這些步驟後，應用程式會設為使用 Redis 輸出快取提供者。

協力廠商輸出快取提供者

• NCache
• Apache Ignite

相關內容

請參閱適用於 Azure Redis 快取的 ASP.NET 工作階段狀態提供者。