ASP.NET Core'da yanıt önbelleğe alma ara yazılımı

Tarafından John Luo ve Rick Anderson

Bu makalede, bir ASP.NET Core uygulamasında yanıt önbelleğe alma ara yazılımının nasıl yapılandırılması açıklanır. Ara yazılım yanıtların ne zaman önbelleğe alındığını belirler, yanıtları depolar ve önbellekten yanıtlar sunar. HTTP önbelleğe alma ve [ResponseCache] özniteliğine giriş için bkz. Yanıt Önbelleğe Alma.

Yanıt önbelleğe alma ara yazılımı , HTTP Cache-Control üst bilgilerine göre sunucu yanıtlarının önbelleğe alınmasını sağlar.

• Önbelleğe alma davranışı standart HTTP önbelleğe alma semantiği uygular.

• Önbelleğe alma, ara sunucular tarafından kullanılan yönteme benzer HTTP önbellek üst bilgilerini temel alır.

• Bu önbelleğe alma biçimi, önbelleğe alma koşullarının karşılandığı istemcilerden gelen genel GET veya HEAD API istekleri için kullanışlıdır.

• Pages gibi Razor kullanıcı arabirimi uygulamaları için yanıt önbelleğe alma genellikle yararlı olmaz. Tarayıcılar genellikle önbelleğe almayı engelleyen istek üst bilgilerini ayarlar.

  Output önbelleğe alma (.NET 7 ve sonraki sürümlerde kullanılabilir) kullanıcı arabirimi uygulamaları için daha iyi bir yaklaşımdır. Bu senaryoda yapılandırma, HTTP üst bilgilerinden bağımsız olarak nelerin önbelleğe alındığını belirler.

Yanıt önbelleğe almayı test etmek için Fiddler'ı veya istek üst bilgilerini açıkça ayarlayabilen başka bir aracı kullanın. Üst bilgileri açıkça ayarlamak, önbelleğe alma testi için tercih edilir. Daha fazla bilgi için bkz Yanıt önbelleğe alma katmanı sorunlarını giderme>.

Configuration

Program.cs içinde, hizmet koleksiyonuna AddResponseCaching yanıt önbelleğe alma ara yazılımı hizmetlerini ekleyin ve uygulamayı UseResponseCaching uzantı yöntemiyle ara yazılımı kullanacak şekilde yapılandırın. UseResponseCaching ara yazılımı istek işleme işlem hattına ekler:

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 UseResponseCaching kullanılmadan önce çağrılmalıdır.

Örnek uygulama, sonraki isteklerde önbelleğe almayı denetlemek için üst bilgiler ekler:

• Önbellek Denetimi: Önbelleğe alınabilen yanıtları 10 saniyeye kadar önbelleğe alır.
• Değişiklik: Ara yazılımı yalnızca sonraki isteklerin Accept-Encoding üst bilgisi özgün istekle eşleşiyorsa önbelleğe alınmış bir yanıt sunmak üzere yapılandırır.

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

Yukarıdaki üst bilgiler yanıta yazılmaz ve bir denetleyici, eylem veya Razor Sayfa olduğunda geçersiz kılınabilir:

• [ResponseCache] özniteliği var. Bu, bir özellik ayarlı olmasa bile geçerlidir. Örneğin, VaryByHeader özelliğinin atlanması, karşılık gelen üst bilgi başlığının yanıttan çıkarılmasına neden olur.

Yanıt önbelleğe alma ara yazılımı yalnızca 200 (Tamam) durum koduna neden olan sunucu yanıtlarını önbelleğe alır. Hata sayfaları da dahil olmak üzere diğer tüm yanıtlar ara yazılım tarafından yoksayılır.

Warning

Kimliği doğrulanmış istemciler için içerik içeren yanıtlar, ara yazılımların bu yanıtları depolamasını ve sunmasını önlemek için önbelleğe alınamaz olarak işaretlenmelidir. Ara yazılımının yanıtın önbelleğe alınıp alınmadığını nasıl belirlediğinin ayrıntıları için bkz. Önbelleğe alma koşulları.

Yukarıdaki kod genellikle önbelleğe alınmış bir değeri tarayıcıya döndürmez. Fiddler'ı veya istek üst bilgilerini açıkça ayarlayabilen ve önbelleğe alma testi için tercih edilen başka bir aracı kullanın. Daha fazla bilgi için bu makalede sorun giderme bölümüne bakın.

Options

Yanıt önbelleğe alma seçenekleri aşağıdaki tabloda gösterilmiştir.

Option	Description
MaximumBodySize	Yanıt gövdesi için bayt cinsinden önbelleğe alınabilen en büyük boyut. Varsayılan değer (64 MB) değeridir 64 * 1024 * 1024 .
SizeLimit	Yanıt önbelleği ara yazılımının bayt cinsinden boyut sınırı. Varsayılan değer ( 100 * 1024 * 1024 100 MB).
UseCaseSensitivePaths	Yanıtların büyük/küçük harfe duyarlı yollarda önbelleğe alındığını belirler. Varsayılan değer şudur: false.

Aşağıdaki örnek ara yazılımı şu şekilde yapılandırılır:

• Gövde boyutu 1.024 bayttan küçük veya buna eşit olan yanıtları önbelleğe alın.
• Yanıtları büyük/küçük harfe duyarlı yollara göre depolayın. Örneğin, /page1 ve /Page1 ayrı olarak depolanır.

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

MVC, web API denetleyicileri veya Razor Sayfalar sayfa modelleri kullanılırken, [ResponseCache] özniteliği yanıt önbelleğe alma için uygun üst bilgileri ayarlamak için gereken parametreleri belirtir. Ara yazılımı kesinlikle gerektiren öznitelik [ResponseCache]'nin tek parametresi VaryByQueryKeys olup, bu gerçek bir HTTP üst bilgisine karşılık gelmez. Daha fazla bilgi için bkz . ASP.NET Core'da yanıt önbelleğe alma.

[ResponseCache] özniteliği kullanılmadığında, VaryByQueryKeys ile yanıt önbelleği değiştirilebilir. HttpContext.Features'tan ResponseCachingFeature öğesini doğrudan kullanın.

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

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

* içinde VaryByQueryKeys değerine eşit tek bir değer kullanılması, önbelleği tüm istek sorgu parametrelerine göre değiştirir.

Yanıt önbelleğe alma ara yazılımı tarafından kullanılan HTTP üst bilgileri

Aşağıdaki tabloda, yanıt önbelleğe almayı etkileyen HTTP üst bilgileri hakkında bilgi sağlanmaktadır.

Header	Details
Authorization	Başlık mevcutsa yanıt önbelleğe alınmaz.
Cache-Control	Ara yazılım, yalnızca public önbellek yönergesiyle işaretlenmiş yanıtları önbelleğe almayı dikkate alır. Önbelleğe almayı aşağıdaki parametrelerle denetleyin: max-age max-stale† min-fresh must-revalidate no-cache no-store only-if-cached private public s-maxage proxy-revalidate‡ Eğer max-stale için bir sınır belirtilmezse, ara yazılım hiçbir işlem yapmaz. proxy-revalidate‡ ile aynı etkiye must-revalidatesahiptir. Daha fazla bilgi için bkz . RFC 9111: İstek Yönergeleri.
Pragma	Pragma: no-cache istekteki bir üst bilgi, Cache-Control: no-cache ile aynı etkiyi üretir. Eğer varsa, bu üst bilgi Cache-Control başlığındaki ilgili direktiflerle geçersiz kılınır. HTTP/1.0 ile geriye dönük uyumluluk için dikkate alınır.
Set-Cookie	Başlık mevcutsa yanıt önbelleğe alınmaz. İstek işleme işlem hattında bir veya daha fazla tanımlama bilgisi ayarlayan herhangi bir ara yazılım, yanıt önbelleğe alma ara yazılımının yanıtı önbelleğe almasını engeller (örneğin, cookietabanlı TempData sağlayıcısı).
Vary	Önbelleğe alınmış yanıtın başka bir üst bilgiyle çeşitlendirilmesi için Vary üst bilgisi kullanılır. Örneğin, yanıtları kodlayarak Vary: Accept-Encoding üst bilgisini dahil edip, Accept-Encoding: gzip ve Accept-Encoding: text/plain üst bilgilerini içeren istekler için yanıtları ayrı ayrı önbelleğe alabilirsiniz. üst bilgi değerine * sahip bir yanıt hiçbir zaman depolanmaz.
Expires	Bu üst bilgi tarafından eski olarak kabul edilen bir yanıt, diğer Cache-Control üst bilgiler tarafından geçersiz kılınmadığı sürece depolanmaz veya alınmaz.
If-None-Match	Değer * değilse ve ETag yanıtın değeri sağlanan değerlerle eşleşmiyorsa, tam yanıt önbellekten sunulur. Aksi takdirde, 304 (Değiştirilmedi) yanıtı sunulur.
If-Modified-Since	If-None-Match başlık yoksa, önbelleğe alınan yanıt tarihi sağlanan tarihten daha yeni ise önbellekten tam yanıt sunulur. Aksi takdirde, 304 - Değiştirilmedi yanıtı sunulur.
Date	Önbellekten sunum yaparken, Date özgün yanıtta sağlanmadıysa header middleware tarafından belirlenir.
Content-Length	Önbellekten sunum yaparken, Content-Length özgün yanıtta sağlanmadıysa header middleware tarafından belirlenir.
Age	Age Özgün yanıtta gönderilen başlık yoksayılır. Ara yazılım, önbelleğe alınmış bir yanıt sunarken yeni bir değer hesaplar.

Önbelleğe alma işlemi, istek üzerindeki Cache-Control yönergelerini göz önünde bulundurur.

Orta katman yazılımı RFC 9111: HTTP Önbellekleme (Bölüm 5.2. Önbellek Denetimi) kurallarına uyar . Kurallar, istemci tarafından gönderilen geçerli bir Cache-Control üst bilgisini onurlandırmak için bir önbellek gerektirir. Belirtim altında, bir istemci üst bilgi değerine sahip no-cache istekler yapabilir ve sunucuyu her istek için yeni bir yanıt oluşturmaya zorlayabilir. Ara yazılım resmi önbelleğe alma belirtimine bağlı olduğundan, ara yazılımı kullanırken şu anda bu önbelleğe alma davranışı üzerinde geliştirici denetimi yoktur.

Önbelleğe alma davranışı üzerinde daha fazla denetim için ASP.NET Core'un diğer önbelleğe alma özelliklerini keşfedin. Aşağıdaki konulara bakın:

• ASP.NET Core'da bellek içi önbellek
• ASP.NET Core'da dağıtılmış önbelleğe alma
• ASP.NET Core MVC'de Önbellek Etiketi Yardımcısı
• ASP.NET Core'da Dağıtılmış Önbellek Etiketi Yardımcısı

Troubleshooting

Yanıt önbelleğe alma ara yazılımı, sınırlı kapasiteye sahip IMemoryCache kullanır. Kapasite aşıldığında , bellek önbelleği sıkıştırılır (TriggerOvercapacityCompaction).

Note

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dallar veya etiketler arasında geçiş yap açılır listesini kullanın.

Önbelleğe alma davranışı beklendiği gibi değilse yanıtların önbelleğe alınıp alınamadığını ve önbellekten sunulduğundan emin olun. İsteğin gelen üst bilgilerini ve yanıtın giden üst bilgilerini inceleyin. Hata ayıklamaya yardımcı olması için günlüğe kaydetmeyi etkinleştirin.

Önbelleğe alma davranışını test ederken ve sorun giderirken, tarayıcı genellikle önbelleğe almayı engelleyen istek üst bilgilerini ayarlar. Örneğin, bir tarayıcı bir sayfayı Cache-Control yenilerken başlık bilgisini no-cache veya max-age=0 olarak ayarlayabilir. Fiddler ve diğer araçlar istek üst bilgilerini açıkça ayarlayabilir ve önbelleğe alma testi için tercih edilir.

Önbelleğe alma koşulları

• İstek, 200 (Tamam) durum koduyla bir sunucu yanıtına neden olmalıdır.
• İstek yöntemi GET veya HEAD olmalıdır.
• Yanıt önbelleğe alma ara yazılımı, önbelleğe alma gerektiren ara yazılımdan önce yerleştirilmelidir. Daha fazla bilgi için bkz. ASP.NET Core ara yazılımı.
• Başlık Authorization mevcut olmamalıdır.
• Cache-Control üst bilgi parametreleri geçerli olmalı ve yanıt public olarak işaretlenmeli, private olarak işaretlenmemelidir.
• Pragma: no-cache üst bilgisi mevcut olmamalıdır, eğer Cache-Control üst bilgisi mevcut değilse, çünkü Cache-Control üst bilgisi mevcut olduğunda Pragma üst bilgisini geçersiz kılar.
• Başlık Set-Cookie mevcut olmamalıdır.
• Vary üst bilgi parametreleri geçerli olmalı ve değerine *eşit olmamalıdır.
• Üst Content-Length bilgi değeri (ayarlandıysa) yanıt gövdesinin boyutuyla eşleşmelidir.
• IHttpSendFileFeature kullanılmaz.
• Yanıt, üst bilgi ve Expires ve max-age önbellek yönergeleri tarafından belirtildiği gibi eski olmamalıdır.
• Yanıt arabelleğe alma başarılı olmalıdır. Yanıtın boyutu yapılandırılan veya varsayılan SizeLimitdeğerinden küçük olmalıdır. Yanıtın gövde boyutu, yapılandırılan veya varsayılan MaximumBodySizedeğerinden küçük olmalıdır.
• Yanıtın RFC 9111: HTTP Önbelleğe Alma'ya göre önbelleğe alınabilmesi gerekir. Örneğin, yönergesi no-store istek veya yanıt üst bilgisi alanlarında mevcut olmamalıdır. Ayrıntılar için bkz . RFC 9111: HTTP Önbelleğe Alma (Bölüm 3: Yanıtları Önbelleklerde Depolama.

Note

Siteler Arası İstek Sahteciliği (CSRF) saldırılarını önlemek için güvenli belirteçler oluşturmaya yönelik Antiforgery sistemi, yanıtların önbelleğe alınmaması için Cache-Control ve Pragma üst bilgilerini no-cache olarak ayarlar. HTML form öğeleri için sahtecilik karşıtı belirteçleri devre dışı bırakma hakkında bilgi için bkz ASP.NET Core'da Siteler Arası İstek Sahteciliği (XSRF/CSRF) saldırılarını önleme.

Ek kaynaklar

• Örnek kodu görüntüleme veya indirme (indirme)
• GitHub kaynağı: IResponseCachingPolicyProvider
• GitHub kaynağı: IResponseCachingPolicyProvider
• ASP.NET Core'da uygulama başlatma
• ASP.NET Core ara yazılımı
• ASP.NET Core'da bellek içi önbellek
• ASP.NET Core'da dağıtılmış önbelleğe alma
• ASP.NET Core'da değişiklik belirteçleriyle değişiklikleri algılama
• ASP.NET Core'da yanıtı önbelleğe alma
• ASP.NET Core MVC'de Önbellek Etiketi Yardımcısı
• ASP.NET Core'da Dağıtılmış Önbellek Etiketi Yardımcısı