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

Redis 輸出快取提供者是輸出快取數據的跨進程儲存機制。 此數據特別適用於完整的 HTTP 回應（頁面輸出快取）。 提供者會插入 ASP.NET 4 中引進的新輸出快取提供者擴充點。

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

若要使用 Redis 輸出快取提供者，請先設定快取，然後使用 Redis 輸出快取提供者 NuGet 套件來設定 ASP.NET 應用程式。 本文提供設定應用程式以使用 Redis 輸出快取提供者的指引。 如需建立和設定 Azure Cache for Redis 實例的詳細資訊，請參閱 建立快取。

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

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

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

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

若要使用 Azure Cache for Redis 工作階段狀態 NuGet 套件在 Visual Studio 中設定用戶端應用程式，請從 [工具] 選單選取 [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 設定。

屬性	類型	預設	描述
_主機*	字串	“localhost”	Redis 伺服器 IP 位址或主機名
port	正整數	6379 （非 TLS/SSL） 6380 （TLS/SSL）	Redis 伺服器埠
accessKey	字串	""	啟用 Redis 授權時，Redis 伺服器密碼。 此值預設為空字串，這表示會話狀態提供者在連線到 Redis 伺服器時不會使用任何密碼。 如果您的 Redis 伺服器位於 Azure Cache for Redis 等可公開存取的網路中，請務必啟用 Redis 授權來改善安全性，並提供安全的密碼。
Ssl	boolean	false	是否要透過TLS連線到 Redis 伺服器。 根據預設，此值為 false ，因為 Redis 預設不支援 TLS。 如果您使用默認支援 SSL 的 Azure Cache for Redis，請務必將此值設定為 true，以改善安全性。 新的快取預設會停用非 TLS 埠。 針對此設定指定 true 以使用非 TLS 埠。 如需啟用非 TLS 埠的詳細資訊，請參閱設定快取一文中的存取埠一節。
databaseIdNumber	正整數	0	此屬性只能透過 web.config 或 App 指定 設定。 指定要使用的 Redis 資料庫。
connectionTimeoutInMilliseconds	正整數	由 StackExchange.Redis 提供	用來在建立 StackExchange.Redis.連線 時設定 連線 TimeoutionMultiplexer。
operationTimeoutInMilliseconds	正整數	由 StackExchange.Redis 提供	用來設定建立 StackExchange.Redis.連線 時的 SyncTimeoutionMultiplexer。
connectionString （有效的 StackExchange.Redis 連接字串）	字串	不適用	App 設定 或 web.config 的參數參考，或是有效的 StackExchange.Redis 連接字串。 此屬性可以提供主機、埠、accessKey、ssl 和其他 StackExchange.Redis 屬性的值。 如需 connectionString 的進一步瞭解，請參閱<屬性注意事項>一節中的設定 connectionString。
settingsClassName settingsMethodName	字串 字串	不適用	這些屬性只能透過 web.config 或 App 指定 設定。 使用這些屬性來提供 連接字串。 _settingsClassName* 應該是包含 settingsMethodName 所指定方法的元件限定類別名稱。 settingsMethodName 所指定的方法應該是 public、static 和 void（不接受任何參數），並具有字串的傳回類型。 這個方法會傳回實際的 連接字串。
loggingClassName loggingMethodName	字串 字串	不適用	這些屬性只能透過 web.config 或 App 設定 來指定。 使用這些屬性來偵錯您的應用程式，方法是提供來自會話狀態/輸出快取的記錄，以及來自 StackExchange.Redis 的記錄。 loggingClassName 應該是元件限定類別名稱，其中包含loggingMethodName所指定的方法。 loggingMethodName 所指定的方法應該是 public、static 和 void（不接受任何參數），且傳回類型為 System.IO.TextWriter。
applicationName	字串	目前進程的模組名稱或 “/”	僅 SessionStateProvider 此屬性只能透過 web.config 或 App 設定 指定。 要用於 Redis 快取的應用程式名稱前置詞。 客戶可能會針對不同的用途使用相同的 Redis 快取。 為了確保會話金鑰不會衝突，它可以前面加上應用程式名稱。
throwOnError	boolean	true	僅 SessionStateProvider 此屬性只能透過 web.config 或 App 設定 指定。 是否要在發生錯誤時擲回例外狀況。 如需 throwOnError 的詳細資訊，請參閱屬性附注一節中 throwOnError 的附注。
retryTimeoutInMilliseconds	正整數	5000	僅 SessionStateProvider 此屬性只能透過 web.config 或 App 設定 來指定。 作業失敗時重試的時間長度。 如果此值小於 operationTimeoutInMilliseconds，則提供者不會重試。 如需 retryTimeoutInMilliseconds 的詳細資訊，請參閱屬性附註一節中的 retryTimeoutInMilliseconds 附注。
redisSerializerType	字串	不適用	指定實作 Microsoft.Web.Redis 之類別的元件限定型別名稱。 串行化程式和 ，其中包含串行化和還原串行化值的自定義邏輯。 如需詳細資訊，請參閱屬性附注一節中的 About redisSerializerType。

屬性附註

設定 connectionString

connectionString 的值是用來從 App 擷取實際 連接字串 的索引鍵 設定，如果 App 中存在這類字串 設定。 如果在 App 內找不到 設定，則 connectionString 的值會作為索引鍵，以從 web.config 連線 ionString 區段擷取實際 連接字串，如果該區段存在。 如果 App 中不存在 連接字串 設定 或 web.config 連線 ionString 區段，connectionString 的常值會在建立 StackExchange.Redis.連線 時作為 連接字串ionMultiplexer。

下列範例說明如何使用 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 毫秒之後發生，這在大部分情況下發生網路故障時就已足夠。 之後，它會每隔一秒重試一次，直到逾時為止。在逾時之後，它會再重試一次，以確保不會將逾時時間減去（最多）一秒。

如果您不認為需要重試，或想要自行處理重試邏輯，請將 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 Cache for Redis 的 ASP.NET 工作階段狀態提供者。