Response Caching Middleware in ASP.NET Core

In dit artikel wordt uitgelegd hoe u Middleware voor antwoordcaching configureert in een ASP.NET Core-app. De middleware bepaalt wanneer antwoorden in de cache kunnen worden opgeslagen, reacties worden opgeslagen en antwoorden uit de cache worden verwerkt. Zie [ResponseCache] voor een inleiding tot HTTP-caching en het kenmerk.

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.

Configuration

In Program.cs voegt u de Middleware-services voor antwoordcaching AddResponseCaching toe aan de serviceverzameling en configureert u de app om de middleware te gebruiken met de UseResponseCaching extensiemethode. UseResponseCaching voegt de middleware toe aan de aanvraagverwerkingspijplijn:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching();

var app = builder.Build();

app.UseHttpsRedirection();

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

app.UseResponseCaching();

De voorbeeld-app voegt headers toe om caching te beheren voor volgende aanvragen:

• Cachebeheer: cachebare antwoorden gedurende maximaal 10 seconden in cache opslaan.
• Variëren: hiermee configureert u de middleware om alleen een antwoord in de cache te verwerken als de header Accept-Encoding van volgende aanvragen overeenkomt met die van de oorspronkelijke aanvraag.

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

De voorgaande headers worden niet naar het antwoord geschreven en worden overschreven wanneer een controller, actie of Razor pagina:

• Heeft een kenmerk [ResponseCache]. Dit geldt zelfs als een eigenschap niet is ingesteld. Als u bijvoorbeeld de eigenschap VaryByHeader weglaat, wordt de bijbehorende header uit het antwoord verwijderd.

Response Caching Middleware slaat alleen serverreacties op die resulteren in een statuscode van 200 (OK). Alle andere antwoorden, inclusief foutpagina's, worden genegeerd door de middleware.

De voorgaande code retourneert doorgaans geen waarde in de cache naar een browser. Gebruik Fiddler of een ander hulpprogramma dat expliciet aanvraagheaders kan instellen en de voorkeur heeft voor het testen van caching. Zie Probleemoplossing in dit artikel voor meer informatie.

Options

Opties voor het opslaan van antwoorden in cache worden weergegeven in de volgende tabel.

In het volgende voorbeeld wordt de middleware geconfigureerd om:

• Antwoorden in cache met een grootte van de body kleiner dan of gelijk aan 1024 bytes.
• Sla de antwoorden op hoofdlettergevoelige paden op. Bijvoorbeeld, worden /page1 en /Page1 afzonderlijk opgeslagen.

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

Wanneer u MVC-, web-API-controllers of Razor paginamodellen gebruikt, geeft het [ResponseCache] kenmerk de parameters op die nodig zijn voor het instellen van de juiste headers voor het opslaan van antwoorden in de cache. De enige parameter van het [ResponseCache] kenmerk waarvoor strikt de middleware is vereist, is VaryByQueryKeys, wat niet overeenkomt met een werkelijke HTTP-header. Zie Antwoordcaching in ASP.NET Corevoor meer informatie.

Wanneer u het [ResponseCache] kenmerk niet gebruikt, kan de cache van reacties worden gewijzigd met VaryByQueryKeys. Gebruik de ResponseCachingFeature rechtstreeks vanuit de HttpContext.Features:

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

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

Het gebruik van één waarde die gelijk is aan * in VaryByQueryKeys varieert de cache met alle queryparameters van de aanvraag.

HTTP-headers die worden gebruikt door Response Caching Middleware

De volgende tabel bevat informatie over HTTP-headers die van invloed zijn op het opslaan van reacties in de cache.

Caching respecteert aanvragen Cache-Control instructies

De middleware respecteert de regels van RFC 9111: HTTP Caching (sectie 5.2. Cache-Control). De regels vereisen dat een cache een geldige Cache-Control header die door de client wordt verzonden, naleeft. Onder de specificatie kan een client aanvragen indienen met een no-cache headerwaarde en de server dwingen een nieuw antwoord te genereren voor elke aanvraag. Er is momenteel geen controle voor ontwikkelaars over dit cachinggedrag wanneer de middleware wordt gebruikt, omdat de middleware voldoet aan de officiële cachespecificatie.

Bekijk andere cachefuncties van ASP.NET Core voor meer controle over het cachegedrag. Zie de volgende onderwerpen:

• Cache in het geheugen in ASP.NET Core
• Gedistribueerde caching in ASP.NET Core
• Cache Tag Helper in ASP.NET Core MVC
• Helper voor gedistribueerde cachetags in ASP.NET Core

Troubleshooting

De Response Caching Middleware gebruikt IMemoryCache, die een beperkte capaciteit heeft. Wanneer de capaciteit wordt overschreden, wordt de geheugencache gecomprimeerd (TriggerOvercapacityCompaction).

Als cachinggedrag niet zoals verwacht is, controleert u of antwoorden in de cache kunnen worden opgeslagen en kunnen worden geleverd vanuit de cache. Bekijk de binnenkomende headers van de aanvraag en de uitgaande headers van het antwoord. Schakel logboekregistratie in om hulp te bieden bij foutopsporing.

Bij het testen en oplossen van problemen met cachegedrag worden in een browser meestal aanvraagheaders ingesteld die caching voorkomen. Een browser kan bijvoorbeeld de Cache-Control-koptekst instellen op no-cache of max-age=0 wanneer een pagina wordt vernieuwd. Fiddler en andere hulpprogramma's kunnen expliciet aanvraagheaders instellen en de voorkeur hebben voor het testen van caching.

Voorwaarden voor opslaan in cache

• De aanvraag moet resulteren in een serverantwoord met een statuscode van 200 (OK).
• De aanvraagmethode moet GET of HEAD zijn.
• Middleware voor responscaching moet worden geplaatst vóór middleware die caching vereist. Zie ASP.NET Core Middlewarevoor meer informatie.
• De Authorization koptekst mag niet aanwezig zijn.
• Cache-Control de headerparameters moeten geldig zijn en het antwoord moet gemarkeerd zijn public en niet gemarkeerd private.
• De Pragma: no-cache koptekst mag niet aanwezig zijn als de Cache-Control koptekst niet aanwezig is, omdat de Cache-Control koptekst de koptekst overschrijft wanneer deze Pragma aanwezig is.
• De Set-Cookie koptekst mag niet aanwezig zijn.
• Vary headerparameters moeten geldig zijn en niet gelijk zijn aan *.
• De Content-Length headerwaarde (indien ingesteld) moet overeenkomen met de grootte van de hoofdtekst van het antwoord.
• De IHttpSendFileFeature wordt niet gebruikt.
• Het antwoord mag niet verouderd zijn zoals aangegeven door de Expires header en de cache-richtlijnen max-age en s-maxage.
• Reactiebuffering moet succesvol zijn. De grootte van het antwoord moet kleiner zijn dan de geconfigureerde of standaardwaarde SizeLimit. De hoofdtekstgrootte van het antwoord moet kleiner zijn dan de geconfigureerde of standaardwaarde MaximumBodySize.
• Het antwoord moet in de cache worden opgeslagen volgens RFC 9111: HTTP Caching. De no-store instructie mag bijvoorbeeld niet bestaan in aanvraag- of antwoordheadervelden. Zie RFC 9111: HTTP-caching (sectie 3: Antwoorden opslaan in caches voor meer informatie.

Additional resources

• Voorbeeldcode bekijken of downloaden (hoe download je)
• GitHub-bron voor IResponseCachingPolicyProvider
• GitHub-bron voor IResponseCachingPolicyProvider
• app opstarten in ASP.NET Core
• ASP.NET Core Middleware
• Cache in het geheugen in ASP.NET Core
• Gedistribueerde caching in ASP.NET Core
• Wijzigingen detecteren met wijzigingstokens in ASP.NET Core
• Responsecaching in ASP.NET Core
• Cache Tag Helper in ASP.NET Core MVC
• Helper voor gedistribueerde cachetags in ASP.NET Core

In dit artikel wordt uitgelegd hoe u Middleware voor antwoordcaching configureert in een ASP.NET Core-app. De middleware bepaalt wanneer antwoorden in de cache kunnen worden opgeslagen, reacties worden opgeslagen en antwoorden uit de cache worden verwerkt. Zie [ResponseCache] voor een inleiding tot HTTP-caching en het kenmerk.

Voorbeeldcode bekijken of downloaden (hoe download je)

Configuration

Response Caching Middleware is impliciet beschikbaar voor ASP.NET Core-apps via het gedeelde framework.

In Startup.ConfigureServices voegt u de middleware voor antwoordcaching toe aan de servicescollectie.

public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCaching();
    services.AddRazorPages();
}

Configureer de app voor het gebruik van de middleware met de UseResponseCaching extensiemethode, waarmee de middleware wordt toegevoegd aan de aanvraagverwerkingspijplijn in Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseRouting();
    // UseCors must be called before UseResponseCaching
    // app.UseCors("myAllowSpecificOrigins");

    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.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

De voorbeeld-app voegt headers toe om caching te beheren voor volgende aanvragen:

• Cachebeheer: cachebare antwoorden gedurende maximaal 10 seconden in cache opslaan.
• Variëren: hiermee configureert u de middleware om alleen een antwoord in de cache te verwerken als de header Accept-Encoding van volgende aanvragen overeenkomt met die van de oorspronkelijke aanvraag.

// using Microsoft.AspNetCore.Http;

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

De voorgaande headers worden niet naar het antwoord geschreven en worden overschreven wanneer een controller, actie of Razor pagina:

• Heeft een kenmerk [ResponseCache]. Dit geldt zelfs als een eigenschap niet is ingesteld. Als u bijvoorbeeld de eigenschap VaryByHeader weglaat, wordt de bijbehorende header uit het antwoord verwijderd.

Response Caching Middleware slaat alleen serverreacties op die resulteren in een statuscode van 200 (OK). Alle andere antwoorden, inclusief foutpagina's, worden genegeerd door de middleware.

Options

Opties voor het opslaan van antwoorden in cache worden weergegeven in de volgende tabel.

In het volgende voorbeeld wordt de middleware geconfigureerd om:

• Antwoorden in cache met een grootte van de body kleiner dan of gelijk aan 1024 bytes.
• Sla de antwoorden op hoofdlettergevoelige paden op. Bijvoorbeeld, worden /page1 en /Page1 afzonderlijk opgeslagen.

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

VaryByQueryKeys

Wanneer u MVC-/web-API-controllers of Razor paginamodellen van pagina's gebruikt, geeft het [ResponseCache] kenmerk de parameters op die nodig zijn voor het instellen van de juiste headers voor het opslaan van antwoorden in de cache. De enige parameter van het [ResponseCache] kenmerk waarvoor strikt de middleware is vereist, is VaryByQueryKeys, wat niet overeenkomt met een werkelijke HTTP-header. Zie Antwoordcaching in ASP.NET Corevoor meer informatie.

Wanneer u het [ResponseCache] kenmerk niet gebruikt, kan de cache van reacties worden gewijzigd met VaryByQueryKeys. Gebruik de ResponseCachingFeature rechtstreeks vanuit de HttpContext.Features:

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

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

Het gebruik van één waarde die gelijk is aan * in VaryByQueryKeys varieert de cache met alle queryparameters van de aanvraag.

HTTP-headers die worden gebruikt door Response Caching Middleware

De volgende tabel bevat informatie over HTTP-headers die van invloed zijn op het opslaan van reacties in de cache.

Caching respecteert aanvragen Cache-Control instructies

De middleware respecteert de regels van RFC 9111: HTTP Caching (sectie 5.2. Cache-Control). De regels vereisen dat een cache een geldige Cache-Control header die door de client wordt verzonden, naleeft. Onder de specificatie kan een client aanvragen indienen met een no-cache headerwaarde en de server dwingen een nieuw antwoord te genereren voor elke aanvraag. Er is momenteel geen controle voor ontwikkelaars over dit cachinggedrag wanneer de middleware wordt gebruikt, omdat de middleware voldoet aan de officiële cachespecificatie.

Bekijk andere cachefuncties van ASP.NET Core voor meer controle over het cachegedrag. Zie de volgende onderwerpen:

• Cache in het geheugen in ASP.NET Core
• Gedistribueerde caching in ASP.NET Core
• Cache Tag Helper in ASP.NET Core MVC
• Helper voor gedistribueerde cachetags in ASP.NET Core

Troubleshooting

Als cachinggedrag niet zoals verwacht is, controleert u of antwoorden in de cache kunnen worden opgeslagen en kunnen worden geleverd vanuit de cache. Bekijk de binnenkomende headers van de aanvraag en de uitgaande headers van het antwoord. Schakel logboekregistratie in om hulp te bieden bij foutopsporing.

Bij het testen en oplossen van problemen met cachinggedrag kan een browser aanvraagheaders instellen die van invloed zijn op caching op ongewenste manieren. Een browser kan bijvoorbeeld de Cache-Control-koptekst instellen op no-cache of max-age=0 wanneer een pagina wordt vernieuwd. De volgende hulpprogramma's kunnen expliciet aanvraagheaders instellen en de voorkeur hebben voor het testen van caching:

• Fiddler

Voorwaarden voor opslaan in cache

• De aanvraag moet resulteren in een serverantwoord met een statuscode van 200 (OK).
• De aanvraagmethode moet GET of HEAD zijn.
• In Startup.Configure moet responscache-middleware worden geplaatst voor middleware die caching vereist. Zie ASP.NET Core Middlewarevoor meer informatie.
• De Authorization koptekst mag niet aanwezig zijn.
• Cache-Control de headerparameters moeten geldig zijn en het antwoord moet gemarkeerd zijn public en niet gemarkeerd private.
• De Pragma: no-cache koptekst mag niet aanwezig zijn als de Cache-Control koptekst niet aanwezig is, omdat de Cache-Control koptekst de koptekst overschrijft wanneer deze Pragma aanwezig is.
• De Set-Cookie koptekst mag niet aanwezig zijn.
• Vary headerparameters moeten geldig zijn en niet gelijk zijn aan *.
• De Content-Length headerwaarde (indien ingesteld) moet overeenkomen met de grootte van de hoofdtekst van het antwoord.
• De IHttpSendFileFeature wordt niet gebruikt.
• Het antwoord mag niet verouderd zijn zoals aangegeven door de Expires header en de cache-richtlijnen max-age en s-maxage.
• Reactiebuffering moet succesvol zijn. De grootte van het antwoord moet kleiner zijn dan de geconfigureerde of standaardwaarde SizeLimit. De hoofdtekstgrootte van het antwoord moet kleiner zijn dan de geconfigureerde of standaardwaarde MaximumBodySize.
• Het antwoord moet in de cache worden opgeslagen volgens RFC 9111: HTTP Caching. De no-store instructie mag bijvoorbeeld niet bestaan in aanvraag- of antwoordheadervelden. Zie RFC 9111: HTTP-caching (sectie 3: Antwoorden opslaan in caches voor meer informatie.

Additional resources

• app opstarten in ASP.NET Core
• ASP.NET Core Middleware
• Cache in het geheugen in ASP.NET Core
• Gedistribueerde caching in ASP.NET Core
• Wijzigingen detecteren met wijzigingstokens in ASP.NET Core
• Responsecaching in ASP.NET Core
• Cache Tag Helper in ASP.NET Core MVC
• Helper voor gedistribueerde cachetags in ASP.NET Core