Antwoordcaching in ASP.NET Core

Door Rick Anderson en Kirk Larkin

Voorbeeldcode bekijken of downloaden (hoe download je)

De reactiecache vermindert het aantal aanvragen dat een client of proxy doet aan een webserver. De reactiecache vermindert ook de hoeveelheid werk die de webserver uitvoert om een antwoord te genereren. Het opslaan van reacties in cache wordt in de headers ingesteld.

Met het kenmerk ResponseCache worden headers voor antwoordcaching ingesteld. Clients en tussenliggende proxy's moeten de headers respecteren voor het opslaan van antwoorden in de cache onder RFC 9111: HTTP-caching.

Gebruik Response Caching Middleware voor caching aan de serverzijde die voldoet aan de HTTP 1.1-cachespecificatie. De middleware kan de ResponseCacheAttribute eigenschappen gebruiken om het cachegedrag aan de serverzijde te beïnvloeden.

Middleware voor het opslaan van antwoorden in cache:

• Hiermee kunt u serverreacties opslaan in cache op basis van HTTP-cacheheaders. Implementeert de standaard semantiek voor HTTP-caching. Caches op basis van HTTP-cacheheaders, zoals proxyservers dat doen.
• Is doorgaans niet nuttig voor UI-apps zoals Razor Pagina's, omdat browsers in het algemeen aanvraagheaders instellen die caching voorkomen. Uitvoercache, die beschikbaar is in .NET 7 of hoger, biedt voordelen voor UI-apps. Met uitvoercache bepaalt de configuratie wat onafhankelijk van HTTP-headers in de cache moet worden opgeslagen.
• Kan nuttig zijn voor openbare GET- of HEAD-API-aanvragen van clients waar aan de voorwaarden voor caching wordt voldaan.

Als u antwoordcaching wilt testen, gebruikt u Fiddler-of een ander hulpprogramma waarmee aanvraagheaders expliciet kunnen worden ingesteld. Het expliciet instellen van headers heeft de voorkeur voor het testen van caching. Zie Probleemoplossing voor meer informatie.

Http-gebaseerde reactiecaching

RFC 9111: HTTP Caching beschrijft hoe internetcaches zich moeten gedragen. De primaire HTTP-header die wordt gebruikt voor caching, is Cachebeheer, dat wordt gebruikt om cacherichtlijnen op te geven. De instructies bepalen het cachegedrag wanneer verzoeken van clients naar servers gaan en wanneer reacties van servers naar clients terugkeren. Aanvragen en antwoorden worden verplaatst via proxyservers en proxyservers moeten ook voldoen aan de http 1.1-cachespecificatie.

In de volgende tabel worden algemene Cache-Control richtlijnen weergegeven.

Richtlijn	Handeling
publiek	In een cache kan het antwoord worden opgeslagen.
privé	Het antwoord mag niet worden opgeslagen door een gedeelde cache. Een privécache kan het antwoord opslaan en opnieuw gebruiken.
max-age	De client accepteert geen antwoord waarvan de leeftijd groter is dan het opgegeven aantal seconden. Voorbeelden: max-age=60 (60 seconden), max-age=2592000 (1 maand)
geen cache	Bij aanvragen: een cache mag geen opgeslagen reactie gebruiken om aan de aanvraag te voldoen. De oorspronkelijke server genereert het antwoord voor de client opnieuw en de middleware werkt het opgeslagen antwoord in de cache bij. Bij antwoorden: Het antwoord mag niet worden gebruikt voor een volgende aanvraag zonder validatie op de oorspronkelijke server.
no-store	Bij aanvragen: een cache mag de aanvraag niet opslaan. Bij antwoorden: een cache mag geen deel van het antwoord opslaan.

Andere cacheheaders die een rol spelen in caching, worden weergegeven in de volgende tabel.

Koptekst	Functie
Leeftijd	Een schatting van de hoeveelheid tijd in seconden sinds het antwoord is gegenereerd of gevalideerd op de oorspronkelijke server.
Verloopt	De tijd waarna een antwoord als verouderd wordt beschouwd.
Pragma	Bestaat voor achterwaartse compatibiliteit met HTTP/1.0-caches voor het instellen van no-cache gedrag. Als de Cache-Control koptekst aanwezig is, wordt de Pragma koptekst genegeerd.
Variëren	Hiermee geeft u op dat een antwoord in de cache niet mag worden verzonden, tenzij alle Vary headervelden overeenkomen in zowel de oorspronkelijke aanvraag van het antwoord in de cache als de nieuwe aanvraag.

HTTP-caching respecteert de richtlijnen van request Cache-Control

RFC 9111: HTTP-caching (sectie 5.2. Cache-Control) vereist een cache om een geldige Cache-Control header te respecteren die door de client wordt verzonden. Een client kan aanvragen indienen met een no-cache headerwaarde en de server dwingen een nieuw antwoord te genereren voor elke aanvraag.

Het altijd respecteren van headers van clientaanvragen Cache-Control is logisch als u het doel van HTTP-caching beschouwt. In de officiële specificatie is caching bedoeld om de latentie en netwerkoverhead te verminderen van het voldoen aan aanvragen in een netwerk van clients, proxy's en servers. Het is niet noodzakelijkerwijs een manier om de belasting op een bronserver te reguleren.

Er is geen ontwikkelaarscontrole over dit cachinggedrag wanneer u de Response Caching Middleware gebruikt, omdat de middleware voldoet aan de officiële cache-specificatie. Ondersteuning voor uitvoercaching om de belasting van de server beter te beheren, is toegevoegd in .NET 7. Zie uitvoercachevoor meer informatie.

Attribuut ResponseCache

ResponseCacheAttribute specificeert de parameters die nodig zijn voor het instellen van passende headers in de antwoordcache.

Waarschuwing

Cache uitschakelen voor inhoud die informatie bevat voor geverifieerde clients. Caching mag alleen worden ingeschakeld voor inhoud die niet wordt gewijzigd op basis van de identiteit van een gebruiker of of een gebruiker is aangemeld.

VaryByQueryKeys varieert het opgeslagen antwoord op basis van de waarden van de opgegeven lijst met querysleutels. Wanneer een enkele waarde voor * wordt opgegeven, varieert de middleware per aanvraagqueryreeksparameter.

Middleware voor antwoordcaching moet zijn ingeschakeld om de VaryByQueryKeys eigenschap in te stellen. Anders wordt er een runtime-uitzondering gegenereerd. Er is geen bijbehorende HTTP-header voor de VaryByQueryKeys eigenschap. De eigenschap is een HTTP-functie die wordt verwerkt door Middleware voor antwoordcaching. Opdat de middleware een in cache opgeslagen reactie kan leveren, moeten de queryreeks en de waarde van de queryreeks overeenkomen met een eerder verzoek. Denk bijvoorbeeld aan de volgorde van aanvragen en resultaten die worden weergegeven in de volgende tabel:

Aanvraag	Geretourneerd van
http://example.com?key1=value1	Serverapparaat
http://example.com?key1=value1	Middleware
http://example.com?key1=NewValue	Serverapparaat

De eerste aanvraag wordt geretourneerd door de server en in de cache opgeslagen in middleware. De tweede aanvraag wordt geretourneerd door middleware omdat de queryreeks overeenkomt met de vorige aanvraag. De derde aanvraag bevindt zich niet in de middlewarecache omdat de querytekenreekswaarde niet overeenkomt met een vorige aanvraag.

De ResponseCacheAttribute wordt gebruikt voor het configureren en maken van (via IFilterFactory) een Microsoft.AspNetCore.Mvc.Internal.ResponseCacheFilter. Het ResponseCacheFilter voert het werk uit van het bijwerken van de juiste HTTP-headers en -functies van het antwoord. Het filter:

• Hiermee verwijdert u eventuele bestaande headers voor Vary, Cache-Controlen Pragma.
• Schrijft de juiste headers op basis van de eigenschappen die zijn ingesteld in ResponseCacheAttribute.
• Hiermee werkt u de HTTP-functie voor het opslaan van antwoorden in de cache bij als VaryByQueryKeys deze is ingesteld.

Variëren

Deze koptekst wordt alleen geschreven wanneer de VaryByHeader eigenschap is ingesteld. De eigenschap is ingesteld op de waarde van de Vary eigenschap. In het volgende voorbeeld wordt de VaryByHeader eigenschap gebruikt:

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

Bekijk de antwoordheaders met Fiddler of een ander hulpprogramma. De antwoordheaders zijn onder andere:

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

De voorgaande code vereist het toevoegen van de Middleware-services AddResponseCaching voor antwoordcaching aan de serviceverzameling en het configureren van de app voor het gebruik van de middleware met de UseResponseCaching extensiemethode.

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 en Location.None

NoStore overschrijft de meeste andere eigenschappen. Wanneer deze eigenschap is ingesteld op true, wordt de Cache-Control header ingesteld op no-store. Als Location is ingesteld op None:

• Cache-Control is ingesteld op no-store,no-cache.
• Pragma is ingesteld op no-cache.

Als NoStorefalse is en LocationNone is, Cache-Control, en Pragma zijn ingesteld op no-cache.

NoStore is doorgaans ingesteld op true voor foutpagina's. Hieronder worden antwoordheaders gegenereerd die de client instrueren het antwoord niet op te slaan.

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

De voorgaande code bevat de volgende headers in het antwoord:

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

Om de ResponseCacheAttribute toe te passen op alle MVC-controllerreacties of Razor Pages-paginareacties van de app, voegt u deze toe met een MVC-filter of Razor Pages-filter.

In een MVC-app:

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

Zie voor een benadering die van toepassing is op Razor Pagina-apps, Toevoegen ResponseCacheAttribute aan de algemene MVC-filterlijst is niet van toepassing op Razor Pagina's (dotnet/aspnetcore #18890). Het voorbeeld in de opmerking over het probleem is geschreven voor apps die gericht zijn op ASP.NET Core vóór de release van Minimale API's op 6.0. Voor apps van versie 6.0 of hoger moet u de serviceregistratie in het voorbeeld wijzigen van builder.Services.AddSingleton... naar Program.cs.

Locatie en duur

Om caching in te schakelen, moet Duration op een positieve waarde zijn ingesteld en moet Location de standaardinstelling Any of Client zijn. Het framework stelt de Cache-Control header in op de locatiewaarde, gevolgd door max-age van het antwoord.

LocationDe opties van Any en Client vertalen zich respectievelijk naar Cache-Control headerwaarden van public en private. Zoals vermeld in de sectie NoStore en Location.None, stelt het instellen van Location op None zowel de kopteksten Cache-Control als Pragma in op no-cache.

Location.Any (Cache-Control ingesteld op public) geeft aan dat de client of een tussenliggende proxy de waarde in de cache kan opslaan, inclusief Middleware voor antwoordcaching.

Location.Client (Cache-Control ingesteld op private) geeft aan dat alleen de client de waarde in de cache mag opslaan. Geen tussenliggende cache mag de waarde opslaan, inclusief Middleware voor antwoordcaching.

Headers voor cachebeheer bieden richtlijnen voor clients en tussenliggende proxy's wanneer en hoe reacties in de cache worden opgeslagen. Er is geen garantie dat clients en proxy's RFC 9111 respecteren: HTTP Caching. Response Caching Middleware volgt altijd de regels voor caching die door de specificatie zijn opgesteld.

In het volgende voorbeeld ziet u de headers die worden geproduceerd door de instelling in te stellen Duration en de standaardwaarde Location te behouden:

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

De voorgaande code bevat de volgende headers in het antwoord:

Cache-Control: public,max-age=10

Cacheprofielen

In plaats van instellingen voor antwoordcache te dupliceren op veel kenmerken van controlleractie, kunnen cacheprofielen worden geconfigureerd als opties bij het instellen van MVC/Razor Pages. Waarden die zijn gevonden in een cacheprofiel waarnaar wordt verwezen, worden gebruikt als de standaardinstellingen ResponseCacheAttribute en worden overschreven door alle eigenschappen die zijn opgegeven in het kenmerk.

In het volgende voorbeeld ziet u een cacheprofiel van 30 seconden:

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();

De volgende code verwijst naar het Default30 cacheprofiel:

[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());
}

Het resulterende headerrespons van het Default30 cacheprofiel bevat:

Cache-Control: public,max-age=30

Het [ResponseCache] kenmerk kan worden toegepast op:

• Razor Pagina: Attributen kunnen niet worden toegepast op handlermethoden. Browsers die worden gebruikt met UI-apps verhinderen het opslaan van reacties in cache.
• MVC-controllers.
• MVC-actiemethoden: kenmerken op methodeniveau overschrijven de instellingen die zijn opgegeven in kenmerken op klasseniveau.

Met de volgende code wordt het [ResponseCache] kenmerk toegepast op controllerniveau en methodeniveau:

[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());
}

Aanvullende bronnen

• Antwoorden opslaan in caches
• Cachebeheer
• Cache in het geheugen in ASP.NET Core
• Gedistribueerde caching in ASP.NET Core
• Wijzigingen detecteren met wijzigingstokens in ASP.NET Core
• Response caching middleware in ASP.NET kern
• Cache Tag Helper in ASP.NET Core MVC
• Helper voor gedistribueerde cachetags in ASP.NET Core