Oprogramowanie pośredniczące buforowania odpowiedzi w programie ASP.NET Core

Przez John Luo i Rick Anderson

W tym artykule wyjaśniono, jak skonfigurować oprogramowanie pośredniczące buforowania odpowiedzi w aplikacji ASP.NET Core. Oprogramowanie pośredniczące określa, kiedy odpowiedzi są buforowane, przechowuje odpowiedzi i obsługuje odpowiedzi z pamięci podręcznej. Aby zapoznać się z wprowadzeniem do buforowania HTTP i atrybutu [ResponseCache] , zobacz Buforowanie odpowiedzi.

Oprogramowanie pośredniczące buforowania odpowiedzi:

• Włącza buforowanie odpowiedzi serwera na podstawie nagłówków pamięci podręcznej HTTP. Implementuje standardową semantykę buforowania HTTP. Pamięci podręczne oparte na nagłówkach pamięci podręcznej HTTP, takich jak serwery proxy.
• Zazwyczaj nie jest korzystne dla aplikacji interfejsu użytkownika, takich jak Razor Strony, ponieważ przeglądarki zwykle ustawiają nagłówki żądań, które uniemożliwiają buforowanie. Buforowanie danych wyjściowych, które jest dostępne na platformie .NET 7 lub nowszym, przynosi korzyści aplikacjom interfejsu użytkownika. W przypadku buforowania danych wyjściowych konfiguracja decyduje, co powinno być buforowane niezależnie od nagłówków HTTP.
• Może być korzystne w przypadku publicznych żądań GET lub HEAD API od klientów, na których spełnione są warunki buforowania .

Aby przetestować buforowanie odpowiedzi, użyj programu Fiddler lub innego narzędzia, które może jawnie ustawić nagłówki żądań. Jawne ustawianie nagłówków jest preferowane do testowania buforowania. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów.

Configuration

W Program.csprogramie dodaj usługi AddResponseCaching oprogramowania pośredniczącego buforowania odpowiedzi do kolekcji usług i skonfiguruj aplikację do używania oprogramowania pośredniczącego UseResponseCaching z metodą rozszerzenia. UseResponseCaching Dodaje oprogramowanie pośredniczące do potoku przetwarzania żądań:

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 należy wywołać przed UseResponseCaching użyciem oprogramowania pośredniczącego CORS.

Przykładowa aplikacja dodaje nagłówki w celu kontrolowania buforowania kolejnych żądań:

• Kontrola pamięci podręcznej: buforuje odpowiedzi z możliwością buforowania przez maksymalnie 10 sekund.
• Różne: konfiguruje oprogramowanie pośredniczące tak, aby obsługiwało buforowane odpowiedzi tylko wtedy, gdy nagłówek Accept-Encoding kolejnych żądań odpowiada oryginalnemu żądaniu.

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

Poprzednie nagłówki nie są zapisywane w odpowiedzi i są zastępowane, gdy kontroler, akcja lub Razor strona:

• Ma atrybut [ResponseCache]. Dotyczy to nawet wtedy, gdy właściwość nie jest ustawiona. Na przykład pominięcie właściwości VaryByHeader spowoduje usunięcie odpowiedniego nagłówka z odpowiedzi.

Oprogramowanie pośredniczące buforowania odpowiedzi buforuje tylko odpowiedzi serwera, które powodują kod stanu 200 (OK). Wszelkie inne odpowiedzi, w tym strony błędów, są ignorowane przez oprogramowanie pośredniczące.

Warning

Odpowiedzi zawierające zawartość dla uwierzytelnionych klientów muszą być oznaczone jako nie do buforowania, aby zapobiec przechowywaniu i obsługiwaniu tych odpowiedzi przez oprogramowanie pośredniczące. Zobacz Warunki buforowania , aby uzyskać szczegółowe informacje na temat sposobu, w jaki oprogramowanie pośredniczące określa, czy odpowiedź jest zapisywana w pamięci podręcznej.

Powyższy kod zwykle nie zwraca buforowanej wartości do przeglądarki. Użyj programu Fiddler lub innego narzędzia, które może jawnie ustawić nagłówki żądań i jest preferowane do testowania buforowania. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów w tym artykule.

Opcje

Opcje buforowania odpowiedzi są wyświetlane w poniższej tabeli.

Option	Description
MaximumBodySize	Największy rozmiar pamięci podręcznej treści odpowiedzi w bajtach. Wartość domyślna to 64 * 1024 * 1024 (64 MB).
SizeLimit	Limit rozmiaru oprogramowania pośredniczącego pamięci podręcznej odpowiedzi w bajtach. Wartość domyślna to 100 * 1024 * 1024 (100 MB).
UseCaseSensitivePaths	Określa, czy odpowiedzi są buforowane na ścieżkach z uwzględnieniem wielkości liter. Domyślna wartość to false.

Poniższy przykład umożliwia skonfigurowanie oprogramowania pośredniczącego na:

• Odpowiedzi pamięci podręcznej o rozmiarze treści mniejszym lub równym 1024 bajtom.
• Przechowuj odpowiedzi według ścieżek z uwzględnieniem wielkości liter. Na przykład /page1 i /Page1 są przechowywane oddzielnie.

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

W przypadku korzystania z wzorca MVC, kontrolerów internetowego interfejsu API lub Razor modeli [ResponseCache] stron atrybut określa parametry niezbędne do ustawienia odpowiednich nagłówków na potrzeby buforowania odpowiedzi. Jedynym parametrem atrybutu [ResponseCache] , który ściśle wymaga oprogramowania pośredniczącego, jest VaryByQueryKeys, który nie odpowiada rzeczywistemu nagłówkowi HTTP. Aby uzyskać więcej informacji, zobacz Buforowanie odpowiedzi w programie ASP.NET Core.

W przypadku braku użycia atrybutu [ResponseCache] buforowanie odpowiedzi może być zróżnicowane przy użyciu VaryByQueryKeyspolecenia . Użyj elementu ResponseCachingFeature bezpośrednio z pliku HttpContext.Features:

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

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

Użycie pojedynczej wartości równej * w VaryByQueryKeys zmiennej pamięci podręcznej zależy od wszystkich parametrów zapytania żądania.

Nagłówki HTTP używane przez oprogramowanie pośredniczące buforowania odpowiedzi

Poniższa tabela zawiera informacje na temat nagłówków HTTP, które wpływają na buforowanie odpowiedzi.

Header	Details
Authorization	Odpowiedź nie jest buforowana, jeśli nagłówek istnieje.
Cache-Control	Oprogramowanie pośredniczące uwzględnia tylko odpowiedzi buforowania oznaczone dyrektywą pamięci podręcznej public . Sterowanie buforowaniem przy użyciu następujących parametrów: max-age max-stale† min-fresh must-revalidate no-cache no-store only-if-cached prywatny public s-maxage proxy-revalidate‡ †Nie określono limitu do max-stale, oprogramowanie pośredniczące nie podejmuje żadnej akcji. ***proxy-revalidate ma taki sam efekt jak must-revalidate. Aby uzyskać więcej informacji, zobacz RFC 9111: Request Directives (RFC 9111: dyrektywy żądań).
Pragma	Nagłówek Pragma: no-cache w żądaniu generuje taki sam efekt jak Cache-Control: no-cache. Ten nagłówek jest zastępowany przez odpowiednie dyrektywy w nagłówku Cache-Control , jeśli istnieje. Rozważane pod kątem zgodności z poprzednimi wersjami protokołu HTTP/1.0.
Set-Cookie	Odpowiedź nie jest buforowana, jeśli nagłówek istnieje. Każde oprogramowanie pośredniczące w potoku przetwarzania żądań, które ustawia co najmniej jeden plik cookie, uniemożliwia buforowanie odpowiedzi oprogramowanie pośredniczące buforujące odpowiedź (na przykład opartego cookiena dostawcy TempData).
Vary	Nagłówek Vary jest używany do zmieniania buforowanej odpowiedzi przez inny nagłówek. Na przykład buforuj odpowiedzi przez kodowanie przez dołączenie nagłówka Vary: Accept-Encoding , który buforuje odpowiedzi dla żądań z nagłówkami Accept-Encoding: gzip i Accept-Encoding: text/plain oddzielnie. Odpowiedź z wartością nagłówka * nigdy nie jest przechowywana.
Expires	Odpowiedź uważana za nieaktualną przez ten nagłówek nie jest przechowywana ani pobierana, chyba że zostanie zastąpiona przez inne Cache-Control nagłówki.
If-None-Match	Pełna odpowiedź jest obsługiwana z pamięci podręcznej, jeśli wartość nie * jest, a ETag odpowiedź nie jest zgodna z żadną z podanych wartości. W przeciwnym razie jest obsługiwana odpowiedź 304 (niezmodyfikowana).
If-Modified-Since	If-None-Match Jeśli nagłówek nie jest obecny, pełna odpowiedź jest obsługiwana z pamięci podręcznej, jeśli data buforowanej odpowiedzi jest nowsza niż podana wartość. W przeciwnym razie jest obsługiwana odpowiedź 304 — niezmodyfikowana .
Date	W przypadku obsługi z pamięci podręcznej nagłówek jest ustawiany przez oprogramowanie pośredniczące, Date jeśli nie został podany w oryginalnej odpowiedzi.
Content-Length	W przypadku obsługi z pamięci podręcznej nagłówek jest ustawiany przez oprogramowanie pośredniczące, Content-Length jeśli nie został podany w oryginalnej odpowiedzi.
Age	Nagłówek Age wysłany w oryginalnej odpowiedzi jest ignorowany. Oprogramowanie pośredniczące oblicza nową wartość podczas obsługi buforowanej odpowiedzi.

Buforowanie uwzględnia dyrektywy Cache-Control

Oprogramowanie pośredniczące przestrzega zasad RFC 9111: buforowanie HTTP (sekcja 5.2). Cache-Control). Reguły wymagają pamięci podręcznej do honorowania prawidłowego Cache-Control nagłówka wysyłanego przez klienta. W ramach specyfikacji klient może wysyłać żądania z wartością nagłówka no-cache i wymusić na serwerze wygenerowanie nowej odpowiedzi dla każdego żądania. Obecnie nie ma kontroli dewelopera nad tym zachowaniem buforowania podczas korzystania z oprogramowania pośredniczącego, ponieważ oprogramowanie pośredniczące jest zgodne z oficjalną specyfikacją buforowania.

Aby uzyskać większą kontrolę nad zachowaniem buforowania, zapoznaj się z innymi funkcjami buforowania ASP.NET Core. Sprawdź następujące tematy:

• Buforowanie w pamięci w ASP.NET Core
• Buforowanie rozproszone w ASP.NET Core
• Pomocnik tagów pamięci podręcznej w ASP.NET Core MVC
• Pomocnik tagów rozproszonej pamięci podręcznej w ASP.NET Core

Troubleshooting

Oprogramowanie , który ma ograniczoną pojemność. Po przekroczeniu pojemności pamięć podręczna jest kompaktowana (TriggerOvercapacityCompaction).

Note

Linki dokumentacyjne do źródła referencyjnego .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla obecne prace rozwojowe nad nadchodzącą wersją .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Jeśli zachowanie buforowania nie jest zgodnie z oczekiwaniami, upewnij się, że odpowiedzi można buforować i mogą być obsługiwane z pamięci podręcznej. Sprawdź nagłówki przychodzące żądania i nagłówki wychodzące odpowiedzi. Włącz rejestrowanie , aby ułatwić debugowanie.

Podczas testowania i rozwiązywania problemów z zachowaniem buforowania przeglądarka zwykle ustawia nagłówki żądań, które uniemożliwiają buforowanie. Na przykład przeglądarka może ustawić Cache-Control nagłówek na no-cache lub max-age=0 podczas odświeżania strony. Program Fiddler i inne narzędzia mogą jawnie ustawiać nagłówki żądań i są preferowane do testowania buforowania.

Warunki buforowania

• Żądanie musi spowodować odpowiedź serwera z kodem stanu 200 (OK).
• Metoda żądania musi być GET lub HEAD.
• Oprogramowanie pośredniczące buforowania odpowiedzi musi zostać umieszczone przed oprogramowaniem pośredniczącym, które wymaga buforowania. Aby uzyskać więcej informacji, zobacz Oprogramowanie pośredniczące ASP.NET Core.
• Nagłówek Authorization nie może być obecny.
• Cache-Control parametry nagłówka muszą być prawidłowe, a odpowiedź musi być oznaczona public i nie oznaczona private.
• Nagłówek Pragma: no-cache nie może być obecny, jeśli Cache-Control nagłówek nie jest obecny, ponieważ Cache-Control nagłówek zastępuje nagłówek w chwili obecnej Pragma .
• Nagłówek Set-Cookie nie może być obecny.
• Vary parametry nagłówka muszą być prawidłowe i nie równe *.
• Wartość nagłówka Content-Length (jeśli jest ustawiona) musi być zgodna z rozmiarem treści odpowiedzi.
• Element IHttpSendFileFeature nie jest używany.
• Odpowiedź nie może być nieaktualna zgodnie z nagłówkami Expires i dyrektywami max-age pamięci podręcznej i .s-maxage
• Buforowanie odpowiedzi musi zakończyć się pomyślnie. Rozmiar odpowiedzi musi być mniejszy niż skonfigurowany lub domyślny SizeLimit. Rozmiar treści odpowiedzi musi być mniejszy niż skonfigurowany lub domyślny MaximumBodySize.
• Odpowiedź musi być buforowalna zgodnie z RFC 9111: buforowanie HTTP. Na przykład no-store dyrektywa nie może istnieć w polach nagłówka żądania lub odpowiedzi. Aby uzyskać szczegółowe informacje, zobacz RFC 9111: buforowanie HTTP (sekcja 3: Przechowywanie odpowiedzi w pamięciach podręcznych ).

Note

System antyforgeryjny do generowania bezpiecznych tokenów, aby zapobiec atakom fałszerzowania żądań między witrynami (CSRF), ustawia Cache-Control nagłówki i Pragma na no-cache wartość , aby odpowiedzi nie zostały buforowane. Aby uzyskać informacje na temat wyłączania tokenów antyforgeryjnych dla elementów formularza HTML, zobacz Zapobieganie atakom na fałszerzowanie żądań między witrynami (XSRF/CSRF) w ASP.NET Core.

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Źródło usługi GitHub dla IResponseCachingPolicyProvider
• Źródło usługi GitHub dla IResponseCachingPolicyProvider
• Uruchamianie aplikacji na platformie ASP.NET Core
• oprogramowanie pośredniczące ASP.NET Core
• Buforowanie w pamięci w ASP.NET Core
• Buforowanie rozproszone w ASP.NET Core
• Wykrywanie zmian za pomocą tokenów zmian w programie ASP.NET Core
• Buforowanie odpowiedzi na platformie ASP.NET Core
• Pomocnik tagów pamięci podręcznej w ASP.NET Core MVC
• Pomocnik tagów rozproszonej pamięci podręcznej w ASP.NET Core