Middleware pro ukládání odpovědí do mezipaměti v ASP.NET Core

John Luo a Rick Anderson

Tento článek vysvětluje, jak nakonfigurovat middleware pro ukládání odpovědí do mezipaměti v aplikaci ASP.NET Core. Middleware určuje, kdy se odpovědi dají ukládat do mezipaměti, ukládají odpovědi a obsluhují odpovědi z mezipaměti. Úvod do mezipaměti HTTP a [ResponseCache] atributu najdete v tématu Ukládání odpovědí do mezipaměti.

Middleware pro ukládání odpovědí do mezipaměti umožňuje ukládání odpovědí serveru do mezipaměti na základě hlaviček protokolu HTTP Cache-Control.

• Chování při ukládání do mezipaměti implementuje standardní sémantiku ukládání do mezipaměti HTTP.

• Ukládání do mezipaměti je založené na hlavičkách mezipaměti HTTP, podobně jako metoda používaná proxy servery.

• Tato forma ukládání do mezipaměti je užitečná pro veřejné požadavky rozhraní GET nebo HEAD API od klientů, u kterých jsou splněny podmínky ukládání do mezipaměti .

• U aplikací uživatelského rozhraní, jako jsou Razor Pages, není ukládání odpovědí do mezipaměti obvykle výhodné. Prohlížeče obvykle nastavují hlavičky požadavků, které brání ukládání do mezipaměti.

  Ukládání výsledků do mezipaměti (dostupné v .NET 7 a novějších verzích) je lepším přístupem pro aplikace uživatelského rozhraní. V tomto scénáři konfigurace určuje, co se má ukládat do mezipaměti nezávisle na hlavičkách HTTP.

Pokud chcete otestovat ukládání odpovědí do mezipaměti, použijte Fiddler nebo jiný nástroj, který může explicitně nastavit hlavičky požadavků. Pro testování ukládání do mezipaměti se explicitně upřednostňuje nastavení hlaviček. Další informace naleznete v části Řešení potíží s middlewarovým ukládáním odpovědí do mezipaměti>.

Configuration

V Program.cs přidejte do kolekce služeb služby middlewaru pro ukládání odpovědí do mezipaměti AddResponseCaching a nakonfigurujte aplikaci tak, aby tento middleware používala pomocí rozšiřující metody UseResponseCaching. UseResponseCaching přidá middleware do kanálu zpracování požadavků:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching();

var app = builder.Build();

app.UseHttpsRedirection();

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

app.UseResponseCaching();

Warning

UseCors musí být volána před UseResponseCaching použitím middlewaru CORS.

Ukázková aplikace přidá hlavičky pro řízení ukládání do mezipaměti při následných požadavcích:

• Cache-Control: Ukládá odpovědi do mezipaměti po dobu až 10 sekund.
• Vary: Nakonfiguruje middleware tak, aby obsluhoval odpověď uloženou v mezipaměti pouze v případě, že hlavička Accept-Encoding následných požadavků odpovídá hlavičce původního požadavku.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching();

var app = builder.Build();

app.UseHttpsRedirection();

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

app.UseResponseCaching();

app.Use(async (context, next) =>
{
    context.Response.GetTypedHeaders().CacheControl =
        new Microsoft.Net.Http.Headers.CacheControlHeaderValue()
        {
            Public = true,
            MaxAge = TimeSpan.FromSeconds(10)
        };
    context.Response.Headers[Microsoft.Net.Http.Headers.HeaderNames.Vary] =
        new string[] { "Accept-Encoding" };

    await next();
});

app.MapGet("/", () => DateTime.Now.Millisecond);

app.Run();

Předchozí hlavičky nejsou zapsány do odpovědi a jsou přepsány při kontroleru, akci nebo Razor stránce:

• Má atribut [ResponseCache]. To platí i v případě, že vlastnost není nastavená. Například vynechání vlastnosti VaryByHeader způsobí odebrání odpovídající hlavičky z odpovědi.

Middleware pro ukládání odpovědí do mezipaměti ukládá do mezipaměti pouze odpovědi serveru, jejichž výsledkem je stavový kód 200 (OK). Middleware ignoruje všechny ostatní odpovědi, včetně chybových stránek.

Warning

Odpovědi obsahující obsah pro ověřené klienty musí být označeny jako neukládatelné do mezipaměti, aby se zabránilo ukládání a obsluhování těchto odpovědí middlewarem. Podrobnosti o tom, jak middleware určuje, jestli je odpověď uložená v mezipaměti, najdete v tématu Podmínky pro ukládání do mezipaměti .

Předchozí kód obvykle nevrací hodnotu uloženou v mezipaměti do prohlížeče. Použijte Fiddler nebo jiný nástroj, který může explicitně nastavit hlavičky požadavků a preferuje se pro testování ukládání do mezipaměti. Další informace najdete v tématu Řešení potíží v tomto článku.

Možnosti

Možnosti ukládání odpovědí do mezipaměti jsou uvedené v následující tabulce.

Option	Description
MaximumBodySize	Největší velikost uložitelná do mezipaměti pro tělo odpovědi v bajtech. Výchozí hodnota je 64 * 1024 * 1024 (64 MB).
SizeLimit	Omezení velikosti middlewaru mezipaměti odpovědí v bajtech. Výchozí hodnota je 100 * 1024 * 1024 (100 MB).
UseCaseSensitivePaths	Určuje, jestli jsou odpovědi uloženy v mezipaměti na cestách s rozlišováním velkých a malých písmen. Výchozí hodnota je false.

Následující příklad nakonfiguruje middleware na:

• Ukládat odpovědi do mezipaměti s velikostí těla menší nebo rovnou 1 024 bajtům
• Uložte odpovědi podle cest citlivých na malá a velká písmena. Například /page1 a /Page1 jsou uloženy samostatně.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching(options =>
{
    options.MaximumBodySize = 1024;
    options.UseCaseSensitivePaths = true;
});

var app = builder.Build();

app.UseHttpsRedirection();

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

app.UseResponseCaching();

app.Use(async (context, next) =>
{
    context.Response.GetTypedHeaders().CacheControl =
        new Microsoft.Net.Http.Headers.CacheControlHeaderValue()
        {
            Public = true,
            MaxAge = TimeSpan.FromSeconds(10)
        };
    context.Response.Headers[Microsoft.Net.Http.Headers.HeaderNames.Vary] =
        new string[] { "Accept-Encoding" };

    await next(context);
});

app.MapGet("/", () => DateTime.Now.Millisecond);

app.Run();

VaryByQueryKeys

Při použití MVC, kontrolerů webového rozhraní API nebo na modelech stránek Razor, atribut [ResponseCache] určuje parametry nezbytné pro nastavení příslušných hlaviček pro ukládání odpovědí do mezipaměti. Jediný parametr atributu [ResponseCache], který striktně vyžaduje middleware, je VaryByQueryKeys, který neodpovídá skutečné hlavičce HTTP. Další informace najdete v tématu Ukládání odpovědí do mezipaměti v ASP.NET Core.

Pokud atribut nepoužíváte [ResponseCache] , ukládání odpovědí do mezipaměti se může lišit pomocí VaryByQueryKeys. Použijte ResponseCachingFeature přímo z HttpContext.Features:

var responseCachingFeature = context.HttpContext.Features.Get<IResponseCachingFeature>();

if (responseCachingFeature != null)
{
    responseCachingFeature.VaryByQueryKeys = new[] { "MyKey" };
}

Použití jediné hodnoty rovné * v VaryByQueryKeys mění mezipaměť podle všech parametrů dotazu požadavku.

Hlavičky HTTP používané middlewarem pro ukládání odpovědí do mezipaměti

Následující tabulka obsahuje informace o hlavičkách HTTP, které ovlivňují ukládání odpovědí do mezipaměti.

Header	Details
Authorization	Odpověď není uložená v mezipaměti, pokud hlavička existuje.
Cache-Control	Middleware bere v úvahu pouze odpovědi na ukládání do mezipaměti označené direktivou public cache. Řízení ukládání do mezipaměti pomocí následujících parametrů: max-age max-stale† min-fresh must-revalidate no-cache no-store only-if-cached soukromý public s-maxage proxy-revalidate‡ †Pokud není zadán max-staležádný limit , middleware nebude provádět žádnou akci. –proxy-revalidate má stejný účinek jako must-revalidate. Další informace naleznete v dokumentu RFC 9111: Požadavkové direktivy.
Pragma	Hlavička Pragma: no-cache v požadavku vytvoří stejný účinek jako Cache-Control: no-cache. Tato hlavička je překryta příslušnými direktivami v Cache-Control hlavičce, pokud je k dispozici. Zvažte zpětnou kompatibilitu s protokolem HTTP/1.0.
Set-Cookie	Odpověď není uložená v mezipaměti, pokud hlavička existuje. Jakýkoli middleware v kanálu zpracování požadavku, který nastaví jeden nebo více souborů cookie, zabrání middlewaru pro ukládání odpovědí do mezipaměti uložit odpověď do mezipaměti (například poskytovatel TempData založený na cookie).
Vary	Hlavička Vary se používá ke změně uložené odpovědi v mezipaměti na základě jiné hlavičky. Například kódováním hlavičky Vary: Accept-Encoding ukládejte odpovědi do mezipaměti, což umožňuje samostatné ukládání odpovědí pro požadavky s hlavičkami Accept-Encoding: gzip a Accept-Encoding: text/plain. Odpověď s hodnotou * hlavičky se nikdy neuloží.
Expires	Odpověď, která je touto hlavičkou považována za zastaralou, není uložena ani načtena, pokud ji nepřepíše jiná Cache-Control hlavička.
If-None-Match	Úplná odpověď se obsluhuje z mezipaměti, pokud hodnota * není platná a hodnota ETag odpovědi neodpovídá žádné z uvedených hodnot. Jinak se vrátí odpověď 304 (Neměněno).
If-Modified-Since	Pokud hlavička If-None-Match není k dispozici, je úplná odpověď poskytována z mezipaměti, pokud je datum uložení odpovědi v mezipaměti novější než zadaná hodnota. Jinak se obsluhuje odpověď 304 – Neupravená.
Date	Při poskytování z mezipaměti je hlavička nastavena middlewarem Date, pokud nebyla uvedena v původní odpovědi.
Content-Length	Při poskytování z mezipaměti je hlavička nastavena middlewarem Content-Length, pokud nebyla uvedena v původní odpovědi.
Age	Hlavička Age odeslaná v původní odpovědi se ignoruje. Middleware vypočítá novou hodnotu při poskytování odpovědi uložené v mezipaměti.

Ukládání do mezipaměti respektuje pokyny Cache-Control

Middleware respektuje pravidla RFC 9111: Ukládání do mezipaměti HTTP (oddíl 5.2. Řízení mezipaměti). Pravidla vyžadují, aby byla v mezipaměti dodržena platná Cache-Control hlavička odeslaná klientem. V rámci specifikace může klient vyžadovat požadavky s no-cache hodnotou hlavičky a vynutit, aby server vygeneroval novou odpověď pro každý požadavek. V současné době neexistuje žádná kontrola nad tímto chováním při ukládání do mezipaměti při použití middlewaru, protože middleware dodržuje oficiální specifikaci ukládání do mezipaměti.

Pokud chcete mít větší kontrolu nad chováním při ukládání do mezipaměti, prozkoumejte další funkce ukládání do mezipaměti ASP.NET Core. Viz následující témata:

• Ukládání do mezipaměti v paměti v ASP.NET Core
• Distribuované ukládání do mezipaměti v ASP.NET Core
• Pomocník značek mezipaměti v ASP.NET Core MVC
• Pomocník značek distribuované mezipaměti v ASP.NET Core

Troubleshooting

Middleware ukládání odpovědí do mezipaměti používá IMemoryCache, který má omezenou kapacitu. Při překročení kapacity je mezipaměť paměti komprimovaná (TriggerOvercapacityCompaction).

Note

Odkazy na referenční zdroj .NET v dokumentaci obvykle otevřou výchozí větev úložiště, která představuje aktuální vývoj další verze .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí mezi větvemi nebo značkami. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Pokud chování při ukládání do mezipaměti neodpovídá očekávání, ověřte, že odpovědi jsou uložené v mezipaměti a že je možné je obsluhovat z mezipaměti. Zkontrolujte příchozí hlavičky požadavku a odchozí hlavičky odpovědi. Povolte protokolování, aby vám pomohlo s laděním.

Při testování a řešení potíží s chováním ukládání do mezipaměti prohlížeč obvykle nastaví hlavičky požadavků, které brání ukládání do mezipaměti. Například prohlížeč může záhlaví nastavit Cache-Control na no-cache nebo max-age=0 při aktualizaci stránky. Fiddler a další nástroje můžou explicitně nastavit hlavičky požadavků a preferují se pro testování ukládání do mezipaměti.

Podmínky ukládání do mezipaměti

• Požadavek musí mít za následek odpověď serveru se stavovým kódem 200 (OK).
• Metoda požadavku musí být GET nebo HEAD.
• Middleware pro ukládání odpovědí do mezipaměti musí být umístěný před middlewarem, který vyžaduje ukládání do mezipaměti. Další informace najdete v tématu ASP.NET Core middleware.
• Záhlaví Authorization nesmí být přítomno.
• Cache-Control parametry hlavičky musí být platné a odpověď musí být označena public a nesmí být označena private.
• Záhlaví Pragma: no-cache nesmí být přítomno, pokud Cache-Control záhlaví není k dispozici, protože Cache-Control záhlaví přepíše hlavičku Pragma , když je k dispozici.
• Záhlaví Set-Cookie nesmí být přítomno.
• Vary parametry hlavičky musí být platné a nerovnají se *.
• Hodnota Content-Length hlavičky (pokud je nastavená) se musí shodovat s velikostí textu odpovědi.
• IHttpSendFileFeature se nepoužívá.
• Odpověď nesmí být zastaralá, jak je uvedeno v hlavičce Expires a direktivách cache max-ages-maxage.
• Ukládání odpovědí do vyrovnávací paměti musí být úspěšné. Velikost odpovědi musí být menší než nakonfigurovaná nebo výchozí SizeLimithodnota . Velikost těla odpovědi musí být menší než nakonfigurovaná nebo výchozí MaximumBodySizehodnota .
• Odpověď musí být uložená v mezipaměti podle dokumentu RFC 9111: Ukládání do mezipaměti HTTP. Například direktiva no-store nesmí existovat v polích hlavičky požadavku nebo odpovědi. Podrobnosti najdete v dokumentu RFC 9111: Ukládání odpovědí do mezipaměti http (oddíl 3: Ukládání odpovědí do mezipaměti .

Note

Antiforgery systém pro generování zabezpečených tokenů, aby se zabránilo útokům CSRF (Cross-Site Request Forgery), nastaví Cache-Control a Pragma hlavičky na no-cache, aby odpovědi nebyly ukládány do mezipaměti. Informace o tom, jak zakázat antiforgery tokeny pro elementy formuláře HTML, naleznete v tématu Prevence útoků XSRF/CSRF (Cross-Site Request Forgery) v ASP.NET Core.

Dodatečné zdroje

• Zobrazení nebo stažení ukázkového kódu (postup stažení)
• Zdroj GitHubu pro IResponseCachingPolicyProvider
• Zdroj GitHubu pro IResponseCachingPolicyProvider
• Spuštění aplikace v ASP.NET Core
• ASP.NET Core middleware
• Ukládání do mezipaměti v paměti v ASP.NET Core
• Distribuované ukládání do mezipaměti v ASP.NET Core
• Detekce změn pomocí tokenů změn v ASP.NET Core
• Ukládání odpovědí do mezipaměti v ASP.NET Core
• Pomocník značek mezipaměti v ASP.NET Core MVC
• Pomocník značek distribuované mezipaměti v ASP.NET Core