Buforowanie odpowiedzi w oprogramowaniu pośredniczącym 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 umożliwia buforowanie odpowiedzi serwera na podstawie nagłówków Cache-Control HTTP.

• Implementacja buforowania korzysta ze standardowej semantyki buforowania HTTP.

• Buforowanie jest oparte na nagłówkach pamięci podręcznej HTTP podobnych do metody używanej przez serwery proxy.

• Ta forma buforowania jest przydatna w przypadku publicznych żądań GET lub HEAD API od klientów, gdzie spełnione są warunki buforowania.

• W przypadku aplikacji interfejsu użytkownika, takich jak Razor Strony, buforowanie odpowiedzi nie jest zwykle korzystne. Przeglądarki często ustawiają nagłówki żądań, które uniemożliwiają buforowanie.

  Buforowanie danych wyjściowych (dostępne w .NET 7 i nowszych) jest lepszym podejściem dla aplikacji interfejsu użytkownika. W tym scenariuszu konfiguracja określa, co należy buforować niezależnie od nagłówków HTTP.

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 >.

Configuration

W pliku Program.cs dodaj do kolekcji usług usługi oprogramowania pośredniczącego do buforowania odpowiedzi AddResponseCaching i skonfiguruj aplikację tak, aby używała tego oprogramowania pośredniczącego za pomocą metody rozszerzającej UseResponseCaching. 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 przy użyciu middleware 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 działa kontroler, akcja lub Razor strona.

• Posiada 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 do buforowania odpowiedzi buforuje tylko odpowiedzi serwera, które zwracają 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 middleware określa, czy odpowiedź może być buforowana.

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 treści odpowiedzi, który można przechować w pamięci podręcznej, podany w bajtach. Wartość domyślna to 64 * 1024 * 1024 (64 MB).
SizeLimit	Limit rozmiaru pamięci podręcznej odpowiedzi przez oprogramowanie pośredniczące, wyrażony w bajtach. Wartość domyślna to 100 * 1024 * 1024 (100 MB).
UseCaseSensitivePaths	Określa, czy odpowiedzi są buforowane na ścieżkach rozróżniających wielkość 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 interfejsu API lub modeli stron Razor, atrybut [ResponseCache] określa parametry niezbędne do ustawienia odpowiednich nagłówków do 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żna zróżnicować przy użyciu VaryByQueryKeys. 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 powoduje zmiany pamięci podręcznej w zależności od wszystkich parametrów zapytania żądania.

Nagłówki HTTP używane przez oprogramowanie pośredniczące do 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‡ †Jeśli nie określono limitu dla max-stale, middleware 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średnie w potoku przetwarzania żądania, które ustawia co najmniej jeden plik cookie, uniemożliwia oprogramowaniu pośredniemu buforowania odpowiedzi zapisanie odpowiedzi w pamięci podręcznej (na przykład dostawca TempData oparty na plikach cookiecookie).
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 dostarczana z pamięci podręcznej, jeśli wartość nie jest *, a ETag odpowiedzi nie pasuje do żadnej z podanych wartości. W przeciwnym razie zostaje zwrócona odpowiedź 304 (Niezmodyfikowana).
If-Modified-Since	If-None-Match Jeśli nagłówek nie jest obecny, pełna odpowiedź jest podawana z pamięci podręcznej, jeśli data buforowanej odpowiedzi jest nowsza niż podana wartość. W przeciwnym razie zostaje wyświetlona odpowiedź 304 — Niezmodyfikowana.
Date	W przypadku serwowania z pamięci podręcznej nagłówek Date jest ustawiany przez oprogramowanie pośredniczące, jeśli nie został podany w oryginalnej odpowiedzi.
Content-Length	W przypadku serwowania z pamięci podręcznej nagłówek Content-Length jest ustawiany przez oprogramowanie pośredniczące, 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 żądania HTTP 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 pośredniczące buforowania odpowiedzi używa IMemoryCacheprogramu , 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 cache'owania

• Żądanie musi spowodować odpowiedź serwera z kodem stanu 200 (OK).
• Metoda żądania musi być GET lub HEAD.
• Oprogramowanie pośredniczące do buforowania odpowiedzi musi zostać umieszczone przed oprogramowaniem pośredniczącym wymagającym buforowania. Aby uzyskać więcej informacji, zobacz ASP.NET Core oprogramowanie pośredniczące.
• 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 nagłówek Cache-Control nie jest, ponieważ nagłówek Cache-Control zastępuje nagłówek 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łówkiem Expires oraz dyrektywami pamięci podręcznej max-age 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 dyrektywa no-store nie może istnieć w polach nagłówka odpowiedzi lub żądania. 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 nagłówki Cache-Control i Pragma na wartość no-cache, aby odpowiedzi nie były pamiętane w pamięci podręcznej. 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