ASP.NET Core 中的回應快取

作者：Rick Anderson 與 Kirk Larkin

回應快取可減少用戶端或 Proxy 對 Web 伺服器發出的要求數目。 回應快取也可減少 Web 伺服器執行以產生回應的工作量。 回應快取是在標頭中設定。

ResponseCache 屬性可設定回應快取標頭。 用戶端及中介代理應尊重 RFC 9111：HTTP 快取 規範下的快取回應標頭。

對於遵循 HTTP 1.1 快取規範的伺服器端快取，請使用 響應快取中介軟體。 該中介軟體可使用 ResponseCacheAttribute 屬性來影響伺服器端的快取行為。

回應快取中介軟體允許基於 HTTP Cache-Control 標頭對伺服器回應進行快取。

• 快取行為實作標準的 HTTP 快取語意。

• 快取是基於類似代理伺服器使用的方法的 HTTP 快取標頭。

• 這種快取形式對於滿足 快取條件 的客戶端公開的 GET 或 HEAD API 請求非常有用。

• 對於像 Pages 這類 Razor UI 應用程式，回應快取通常沒什麼幫助。 瀏覽器通常會設定請求標頭以防止快取。

  Output caching（.NET 7 及以後版本提供）是 UI 應用中更好的方法。 在這種情況下，設定會決定要快取哪些內容，獨立於 HTTP 標頭之外。

要測試回應快取，可以使用 Fiddler 或其他能明確設定請求標頭的工具。 明確設定標頭是測試快取的慣用方式。 欲了解更多資訊，請參閱 回應快取中介軟體 > 故障排除。

檢視或下載範例程式碼 \(英文\) (如何下載)

基於 HTTP 的回應快取

RFC 9111：HTTP 快取規範描述了網際網路快取應如何運作。 用於快取的主要 HTTP 標頭是 Cache-Control (用來指定快取指示詞)。 指令控制快取行為，當請求從客戶端傳送到伺服器，回應從伺服器返回客戶端時。 要求和回應會透過 Proxy 伺服器移動，而 Proxy 伺服器也必須符合「HTTP 1.1 快取」的規範。

下表顯示常見的 Cache-Control 指示詞。

Directive	Action
public	快取可以儲存回應。
private	共享快取不得儲存回應。 私有快取可以儲存並重複使用回應。
max-age	用戶端不接受其時齡大於指定秒數的回應。 範例： max-age=60 （60秒）、 max-age=2592000 （一個月）
no-cache	對於要求：快取不得使用儲存的回應來滿足要求。 源伺服器會重新產生用戶端的回應，而中介軟體會更新其快取中所儲存的回應。 對於回應：若未在原始伺服器上進行驗證，回應不得用於後續的要求。
no-store	針對請求：快取不得儲存該請求。 對於回應：快取不得儲存回應的任何部分。

下表顯示其他在快取中發揮作用的快取標頭。

Header	Function
Age	提供自回應在原始伺服器產生或成功驗證以來，所花費的時間（秒數）估計。
Expires	指定在何時之後，回應會被視為過時。
Pragma	存在是為了向下相容 HTTP 1.0 快取，用於設定 no-cache 行為。 如果存在 Cache-Control 標頭，則會忽略 Pragma 標頭。
Vary	指定除非快取回應的原始要求和新要求中的所有 Vary 標頭欄位都相符，否則不得傳送快取的回應。

HTTP 型的快取遵從請求的 Cache-Control 指令

RFC 9111：HTTP 快取（第 5.2 節 Cache-Control）規範要求快取必須尊重客戶端傳送的有效Cache-Control標頭。 用戶端可以使用 no-cache 標頭值來發出要求，並強制伺服器為每個要求產生新的回應。

如果您考慮 HTTP 快取的目的，則始終遵循用戶端 Cache-Control 要求標頭是有意義的。 根據官方的規範，快取的目的是為了降低滿足網路上用戶端、Proxy 和伺服器要求時的延遲和網路負荷。 它不一定是控制原始伺服器上的負載的方法。

使用 響應快取中介 軟體時，開發者無法控制這種快取行為，因為中介軟體遵循官方快取規範。 .NET 7 及以後的版本支援輸出快取，以更好地控制伺服器負載。 如需詳細資訊，請參閱輸出快取。

ResponseCache 屬性

該 ResponseCacheAttribute 類別指定在回應快取中設定適當標頭所需的參數。

Warning

請針對包含已驗證用戶端資訊的內容停用快取。 只有針對不會因為使用者的身分識別或是否登入而變更的內容才應啟用快取。

此 VaryByQueryKeys 特性會將儲存的回應隨所給查詢鍵列表的值變化。 當提供通配符星號（*）的單一值時，中介軟體會根據所有請求查詢字串參數來調整回應。

必須啟用回應快取中介軟體，才能設定 VaryByQueryKeys 屬性。 否則，會拋出執行階段例外狀況。 VaryByQueryKeys 屬性沒有對應的 HTTP 標頭。 此屬性是由回應快取中介軟體處理的 HTTP 功能。 為了讓中介軟體提供快取的回應，查詢字串和查詢字串值必須符合先前的請求。 例如，請思慮下表中所示的要求和結果順序。

Request	傳回自
http://example.com?key1=value1	Server
http://example.com?key1=value1	Middleware
http://example.com?key1=NewValue	Server

伺服器回傳第一個請求，中介軟體則快取該請求。 中介軟體回傳第二個請求，因為查詢字串與前一個（第一個）請求相符。 第三個要求不在中介軟體快取中，因為查詢字串值不符合先前的要求。

ResponseCacheAttribute 類別用於配置並建立（透過 IFilterFactory 介面）Microsoft.AspNetCore.Mvc.Internal.ResponseCacheFilter。 ResponseCacheFilter 會執行更新回應的適當 HTTP 標頭和功能的工作。 篩選：

• 移除 Vary、Cache-Control 和 Pragma 的任何現有標頭。
• 根據 ResponseCacheAttribute 中所設定的屬性寫出適當的標頭。
• 如果 VaryByQueryKeys 設定了該屬性，則更新回應快取 HTTP 功能。

Vary 標頭

只有在設定 VaryByHeader 屬性時才會寫入此標頭。 該屬性會被設定為Vary屬性的值。 下列範例使用了 VaryByHeader 屬性：

[ApiController]
public class TimeController : ControllerBase
{
    [Route("api/[controller]")]
    [HttpGet]
    [ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]
    public ContentResult GetTime() => Content(
                      DateTime.Now.Millisecond.ToString());

請使用 Fiddler 或其他工具來檢視回應標頭。 回應標頭包括：

Cache-Control: public,max-age=30
Vary: User-Agent

前述程式碼需要將回應快取中介軟體 AddResponseCaching 服務方法加入服務集合中。 程式碼用擴充功能方法設定應用程式使用中介軟體 UseResponseCaching 。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddResponseCaching();

var app = builder.Build();

app.UseHttpsRedirection();

// UseCors must be called before UseResponseCaching
//app.UseCors();

app.UseResponseCaching();

app.UseAuthorization();

app.MapControllers();

app.Run();

無商店與地點。無物業

該 NoStore 屬性覆蓋大多數其他屬性。 當此屬性設為 true 時，Cache-Control 標頭會設定為 no-store。 若屬性 Location 設定為 None：

• Cache-Control標頭設為 no-store,no-cache。
• Pragma標頭設為 no-cache。

若 NoStore 屬性設為 false ，且 Location 屬性設為 None，則 Cache-Control 和 Pragma 標頭設為 no-cache。

NoStore這個屬性通常會設定為true錯誤頁面。 以下程式碼產生回應標頭，指示用戶端不要儲存回應。

[Route("api/[controller]/ticks")]
[HttpGet]
[ResponseCache(Location = ResponseCacheLocation.None, NoStore = true)]
public ContentResult GetTimeTicks() => Content(
                  DateTime.Now.Ticks.ToString());

上面的程式碼會在回應中包含下列標頭：

Cache-Control: no-store,no-cache
Pragma: no-cache

若要將 ResponseCacheAttribute 套用至應用程式的所有 MVC 控制器或 Razor 頁面回應，請新增屬性，並使用 MVC 過濾器 或 Razor 頁面過濾器。

在 MVC 應用程式中，請新增以下程式碼：

builder.Services.AddControllersWithViews().AddMvcOptions(options => 
    options.Filters.Add(
        new ResponseCacheAttribute
        {
            NoStore = true, 
            Location = ResponseCacheLocation.None
        }));

關於適用於 Razor 頁面應用程式的方法，請參見 GitHub dotnet/aspnetcore issue #18890） - 將 ResponseCacheAttribute 加入 MVC 全域過濾器清單不適用於 Razor Pages。 本期評論範例適用於 ASP.NET Core於 Minimal APIS（ASP.NET Core 6.0 版本）發布之前的應用程式。 針對 6.0 及以後版本的應用程式，請將範例中使用的服務註冊改為 builder.Services.AddSingleton...Program.cs 檔案中的服務註冊。

位置與持續時間特性

要啟用快取， Duration 屬性必須設定為正值，且 Location 必須是 Any （預設值）或 Client。 架構會將 Cache-Control 標頭設為回應的位置 (Location) 的值，後面接著 max-age。

Location和 Any 的Client屬性選項分別轉換為 Cache-Control 和 public的private標頭值。 如NoStore 和 Location.None 章節所述，設定Location屬性為None時，會將Cache-Control 和Pragma 標頭都設為no-cache。

Location.Any（Cache-Control 設為 public）屬性設定表示，用戶端或任何中繼 Proxy都可以快取此值，包括回應快取中介軟體。

屬性設定Location.Client（Cache-Control 設定為 private）表示只有客戶端能快取該值。 不應有任何中介快取快取該值，包括 回應快取中介軟體。

快取控制標頭為客戶端與中介代理提供何時以及如何快取回應的指引。 無法保證用戶端和代理會遵守 RFC 9111：HTTP 快取 規範。 回應快取中介軟體 始終遵循規範中所訂定的快取規則。

以下範例展示了設定 Duration 屬性並保留預設 Location 屬性值所產生的標頭：

[Route("api/[controller]/ms")]
[HttpGet]
[ResponseCache(Duration = 10, Location = ResponseCacheLocation.Any, NoStore = false)]
public ContentResult GetTimeMS() => Content(
                  DateTime.Now.Millisecond.ToString());

上面的程式碼會在回應中包含下列標頭：

Cache-Control: public,max-age=10

快取配置檔

與其重複許多控制器動作屬性的回應快取設定，可以在設定 MVC 頁面或 Razor 頁面時設定快取設定檔作為選項。 在參考快取設定檔中找到的值會被用作預設值。ResponseCacheAttribute 在屬性上指定的任何屬性值都會覆寫參考的快取設定檔值。

以下的範例展示了一個 30 秒的快取配置：

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching();
builder.Services.AddControllers(options =>
{
    options.CacheProfiles.Add("Default30",
        new CacheProfile()
        {
            Duration = 30
        });
});

var app = builder.Build();

app.UseHttpsRedirection();

// UseCors must be called before UseResponseCaching
//app.UseCors();

app.UseResponseCaching();

app.UseAuthorization();

app.MapControllers();

app.Run();

下列程式碼引用了該 Default30 的快取設定檔：

[ApiController]
[ResponseCache(CacheProfileName = "Default30")]
public class Time2Controller : ControllerBase
{
    [Route("api/[controller]")]
    [HttpGet]
    public ContentResult GetTime() => Content(
                      DateTime.Now.Millisecond.ToString());

    [Route("api/[controller]/ticks")]
    [HttpGet]
    public ContentResult GetTimeTicks() => Content(
                      DateTime.Now.Ticks.ToString());
}

該 Default30 的快取設定檔所產生的標頭回應包括：

Cache-Control: public,max-age=30

你可以將 [ResponseCache] 屬性套用到 Razor 頁面、MVC 控制器和 MVC 動作方法。

在 Razor Pages 中，你無法對處理方法套用屬性，因為搭配 UI 應用程式的瀏覽器會阻止回應快取。 在 MVC 動作方法中，方法層級的屬性會覆蓋類別層級屬性中指定的設定。

下列程式碼會在控制器層級和方法層級套用 [ResponseCache] 屬性：

[ApiController]
[ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]
public class Time4Controller : ControllerBase
{
    [Route("api/[controller]")]
    [HttpGet]
    public ContentResult GetTime() => Content(
                      DateTime.Now.Millisecond.ToString());

    [Route("api/[controller]/ticks")]
    [HttpGet]
    public ContentResult GetTimeTicks() => Content(
                  DateTime.Now.Ticks.ToString());

    [Route("api/[controller]/ms")]
    [HttpGet]
    [ResponseCache(Duration = 10, Location = ResponseCacheLocation.Any, NoStore = false)]
    public ContentResult GetTimeMS() => Content(
                      DateTime.Now.Millisecond.ToString());
}

相關內容

• 將回應儲存在快取中 - RFC 9111：HTTP 快取（第 3 節）
• Cache-Control- RFC 9111：HTTP 快取（第 5.2 節）
• ASP.NET Core 中的記憶體快取
• ASP.NET Core 中的分散式快取
• 在 ASP.NET Core 中的響應快取中介軟體