Middleware pro ukládání výstupu do mezipaměti v ASP.NET Core

Od Tom Dykstra

Tento článek vysvětluje, jak nakonfigurovat middleware pro ukládání výstupu do mezipaměti v aplikaci ASP.NET Core. Úvod do ukládání výstupu do mezipaměti najdete v tématu Ukládání výstupu do mezipaměti.

Middleware pro ukládání výstupu do mezipaměti se dá použít ve všech typech aplikací ASP.NET Core: minimální rozhraní API, webové rozhraní API s kontrolery, MVC a Razor Pages. Příklady kódu jsou k dispozici pro minimální rozhraní API a rozhraní API založená na kontroleru. Příklady rozhraní API založené na kontroleru ukazují, jak pomocí atributů nakonfigurovat ukládání do mezipaměti. Tyto atributy lze použít také v aplikacích MVC a Razor Pages.

Příklady kódu odkazují na gravatar třídy , která generuje obrázek a poskytuje "vygenerované" datum a čas. Třída je definována a používána pouze v ukázkové aplikaci. Jejím účelem je snadno zjistit, kdy se používá výstup uložený v mezipaměti. Další informace naleznete v tématu Jak stáhnout ukázkové a preprocesor direktivy v ukázkovém kódu.

Přidání middlewaru do aplikace

Přidejte do kolekce služeb middleware ukládání výstupu do mezipaměti voláním AddOutputCache.

Přidejte middleware do kanálu zpracování požadavků voláním UseOutputCache.

Příklad:

builder.Services.AddOutputCache();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseHttpsRedirection();
app.UseOutputCache();
app.UseAuthorization();

Volání AddOutputCachea UseOutputCache nespustí chování při ukládání do mezipaměti, zpřístupňuje ukládání do mezipaměti. Aby se odpovědi na mezipaměť aplikací projevily, musí být ukládání do mezipaměti nakonfigurované, jak je znázorněno v následujících částech.

Poznámka:

• V aplikacích, které používají middleware CORS, UseOutputCache musí být volána po UseCors.
• V Razor aplikacích Pages a aplikacích s řadiči UseOutputCache musí být volána po UseRouting.

Konfigurace jednoho koncového bodu nebo stránky

V případě minimálních aplikací API nakonfigurujte koncový bod pro ukládání do mezipaměti voláním CacheOutputnebo použitím atributu [OutputCache] , jak je znázorněno v následujících příkladech:

app.MapGet("/cached", Gravatar.WriteGravatar).CacheOutput();
app.MapGet("/attribute", [OutputCache] (context) => 
    Gravatar.WriteGravatar(context));

U aplikací s kontrolery použijte [OutputCache] atribut na metodu akce, jak je znázorněno tady:

[ApiController]
[Route("/[controller]")]
[OutputCache]
public class CachedController : ControllerBase
{
    public async Task GetAsync()
    {
        await Gravatar.WriteGravatar(HttpContext);
    }
}

U Razor aplikací Pages použijte atribut na Razor třídu stránky.

Konfigurace několika koncových bodů nebo stránek

Vytvořte zásady při volání AddOutputCache pro určení konfigurace ukládání do mezipaměti, která se vztahuje na více koncových bodů. Pro konkrétní koncové body je možné vybrat zásadu, zatímco základní zásada poskytuje výchozí konfiguraci ukládání do mezipaměti pro kolekci koncových bodů.

Následující zvýrazněný kód konfiguruje ukládání do mezipaměti pro všechny koncové body aplikace s dobou vypršení platnosti 10 sekund. Pokud není zadaný čas vypršení platnosti, výchozí hodnota je jedna minuta.

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => 
        builder.Expire(TimeSpan.FromSeconds(10)));
    options.AddPolicy("Expire20", builder => 
        builder.Expire(TimeSpan.FromSeconds(20)));
    options.AddPolicy("Expire30", builder => 
        builder.Expire(TimeSpan.FromSeconds(30)));
});

Následující zvýrazněný kód vytvoří dvě zásady, z nichž každý určuje jinou dobu vypršení platnosti. Vybrané koncové body můžou používat 20sekundové vypršení platnosti a ostatní můžou používat 30sekundové vypršení platnosti.

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => 
        builder.Expire(TimeSpan.FromSeconds(10)));
    options.AddPolicy("Expire20", builder => 
        builder.Expire(TimeSpan.FromSeconds(20)));
    options.AddPolicy("Expire30", builder => 
        builder.Expire(TimeSpan.FromSeconds(30)));
});

Při volání CacheOutput metody nebo pomocí atributu [OutputCache] můžete vybrat zásadu pro koncový bod.

V minimální aplikaci API nakonfiguruje následující kód jeden koncový bod s 20sekundovým vypršením platnosti a jedním s 30sekundovým vypršením platnosti:

app.MapGet("/20", Gravatar.WriteGravatar).CacheOutput("Expire20");
app.MapGet("/30", [OutputCache(PolicyName = "Expire30")] (context) => 
    Gravatar.WriteGravatar(context));

U aplikací s kontrolery použijte [OutputCache] atribut na metodu akce a vyberte zásadu:

[ApiController]
[Route("/[controller]")]
[OutputCache(PolicyName = "Expire20")]
public class Expire20Controller : ControllerBase
{
    public async Task GetAsync()
    {
        await Gravatar.WriteGravatar(HttpContext);
    }
}

U Razor aplikací Pages použijte atribut na Razor třídu stránky.

Výchozí zásady ukládání výstupu do mezipaměti

Ve výchozím nastavení se ukládání výstupu do mezipaměti řídí těmito pravidly:

• Ukládají se do mezipaměti pouze odpovědi HTTP 200.
• Ukládají se do mezipaměti pouze požadavky HTTP GET nebo HEAD.
• Odpovědi, které nastavily soubory cookie, nejsou uložené v mezipaměti.
• Odpovědi na ověřené požadavky nejsou uložené v mezipaměti.

Následující kód použije všechna výchozí pravidla ukládání do mezipaměti na všechny koncové body aplikace:

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => builder.Cache());
});

Přepsání výchozích zásad

Následující kód ukazuje, jak přepsat výchozí pravidla. Zvýrazněné řádky v následujícím kódu vlastních zásad umožňují ukládání do mezipaměti pro metody HTTP POST a odpovědi HTTP 301:

using Microsoft.AspNetCore.OutputCaching;
using Microsoft.Extensions.Primitives;

namespace OCMinimal;

public sealed class MyCustomPolicy : IOutputCachePolicy
{
    public static readonly MyCustomPolicy Instance = new();

    private MyCustomPolicy()
    {
    }

    ValueTask IOutputCachePolicy.CacheRequestAsync(
        OutputCacheContext context, 
        CancellationToken cancellationToken)
    {
        var attemptOutputCaching = AttemptOutputCaching(context);
        context.EnableOutputCaching = true;
        context.AllowCacheLookup = attemptOutputCaching;
        context.AllowCacheStorage = attemptOutputCaching;
        context.AllowLocking = true;

        // Vary by any query by default
        context.CacheVaryByRules.QueryKeys = "*";

        return ValueTask.CompletedTask;
    }

    ValueTask IOutputCachePolicy.ServeFromCacheAsync
        (OutputCacheContext context, CancellationToken cancellationToken)
    {
        return ValueTask.CompletedTask;
    }

    ValueTask IOutputCachePolicy.ServeResponseAsync
        (OutputCacheContext context, CancellationToken cancellationToken)
    {
        var response = context.HttpContext.Response;

        // Verify existence of cookie headers
        if (!StringValues.IsNullOrEmpty(response.Headers.SetCookie))
        {
            context.AllowCacheStorage = false;
            return ValueTask.CompletedTask;
        }

        // Check response code
        if (response.StatusCode != StatusCodes.Status200OK && 
            response.StatusCode != StatusCodes.Status301MovedPermanently)
        {
            context.AllowCacheStorage = false;
            return ValueTask.CompletedTask;
        }

        return ValueTask.CompletedTask;
    }

    private static bool AttemptOutputCaching(OutputCacheContext context)
    {
        // Check if the current request fulfills the requirements
        // to be cached
        var request = context.HttpContext.Request;

        // Verify the method
        if (!HttpMethods.IsGet(request.Method) && 
            !HttpMethods.IsHead(request.Method) && 
            !HttpMethods.IsPost(request.Method))
        {
            return false;
        }

        // Verify existence of authorization headers
        if (!StringValues.IsNullOrEmpty(request.Headers.Authorization) || 
            request.HttpContext.User?.Identity?.IsAuthenticated == true)
        {
            return false;
        }

        return true;
    }
}

Pokud chcete použít tuto vlastní zásadu, vytvořte pojmenovanou zásadu:

builder.Services.AddOutputCache(options =>
{
    options.AddPolicy("CachePost", MyCustomPolicy.Instance);
});

A vyberte pojmenovanou zásadu pro koncový bod. Následující kód vybere vlastní zásadu pro koncový bod v minimální aplikaci API:

app.MapPost("/cachedpost", Gravatar.WriteGravatar)
    .CacheOutput("CachePost");

Následující kód provede totéž pro akci kontroleru:

[ApiController]
[Route("/[controller]")]
[OutputCache(PolicyName = "CachePost")]
public class PostController : ControllerBase
{
    public async Task GetAsync()
    {
        await Gravatar.WriteGravatar(HttpContext);
    }
}

Alternativní výchozí přepsání zásad

Alternativně můžete inicializovat instanci pomocí inicializace injektáže závislostí (DI) s následujícími změnami třídy vlastních zásad:

• Veřejný konstruktor místo soukromého konstruktoru.
• Eliminujte Instance vlastnost ve třídě vlastních zásad.

Příklad:

public sealed class MyCustomPolicy2 : IOutputCachePolicy
{

    public MyCustomPolicy2()
    {
    }

Zbývající část třídy je stejná jako v předchozím příkladu. Přidejte vlastní zásadu, jak je znázorněno v následujícím příkladu:

builder.Services.AddOutputCache(options =>
{
    options.AddPolicy("CachePost", builder => 
        builder.AddPolicy<MyCustomPolicy2>(), true);
});

Předchozí kód používá DI k vytvoření instance vlastní třídy zásad. Všechny veřejné argumenty v konstruktoru jsou vyřešeny.

Pokud jako základní zásadu používáte vlastní zásadu, nevyvolávejte OutputCache() (bez argumentů) ani nepoužívejte [OutputCache] atribut u žádného koncového bodu, na který by se měla použít základní zásada. Volání OutputCache() nebo použití atributu přidá do koncového bodu výchozí zásadu.

Zadání klíče mezipaměti

Ve výchozím nastavení je každá část adresy URL zahrnuta jako klíč položky mezipaměti, tj. schéma, hostitel, port, cesta a řetězec dotazu. Můžete ale chtít klíč mezipaměti explicitně řídit. Předpokládejme například, že máte koncový bod, který vrací jedinečnou odpověď pouze pro každou jedinečnou hodnotu culture řetězce dotazu. Varianta v jiných částech adresy URL, jako jsou jiné řetězce dotazů, by neměla vést k různým položkám mezipaměti. Taková pravidla můžete zadat v zásadách, jak je znázorněno v následujícím zvýrazněném kódu:

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => builder
        .With(c => c.HttpContext.Request.Path.StartsWithSegments("/blog"))
        .Tag("tag-blog"));
    options.AddBasePolicy(builder => builder.Tag("tag-all"));
    options.AddPolicy("Query", builder => builder.SetVaryByQuery("culture"));
    options.AddPolicy("NoCache", builder => builder.NoCache());
    options.AddPolicy("NoLock", builder => builder.SetLocking(false));
});

Pak můžete vybrat zásadu VaryByQuery pro koncový bod. V minimální aplikaci API vybere následující kód zásadu VaryByQuery pro koncový bod, který vrátí jedinečnou odpověď pouze pro každou jedinečnou hodnotu culture řetězce dotazu:

app.MapGet("/query", Gravatar.WriteGravatar).CacheOutput("Query");

Následující kód provede totéž pro akci kontroleru:

[ApiController]
[Route("/[controller]")]
[OutputCache(PolicyName = "Query")]
public class QueryController : ControllerBase
{
    public async Task GetAsync()
    {
        await Gravatar.WriteGravatar(HttpContext);
    }
}

Tady jsou některé možnosti řízení klíče mezipaměti:

• SetVaryByQuery – Zadejte jeden nebo více názvů řetězců dotazu, které chcete přidat do klíče mezipaměti.

• SetVaryByHeader – Zadejte jedno nebo více hlaviček HTTP, které se mají přidat do klíče mezipaměti.

• VaryByValue– Zadejte hodnotu, kterou chcete přidat do klíče mezipaměti. Následující příklad používá hodnotu, která označuje, jestli je aktuální čas serveru v sekundách lichý nebo sudý. Nová odpověď se vygeneruje jenom v případě, že počet sekund pochází z lichých na sudé nebo dokonce liché.

  builder.Services.AddOutputCache(options =>
  {
      options.AddBasePolicy(builder => builder
          .With(c => c.HttpContext.Request.Path.StartsWithSegments("/blog"))
          .Tag("tag-blog"));
      options.AddBasePolicy(builder => builder.Tag("tag-all"));
      options.AddPolicy("Query", builder => builder.SetVaryByQuery("culture"));
      options.AddPolicy("NoCache", builder => builder.NoCache());
      options.AddPolicy("NoLock", builder => builder.SetLocking(false));
      options.AddPolicy("VaryByValue", builder => 
          builder.VaryByValue((context) =>
              new KeyValuePair<string, string>(
              "time", (DateTime.Now.Second % 2)
                  .ToString(CultureInfo.InvariantCulture))));
  });
  

Slouží OutputCacheOptions.UseCaseSensitivePaths k určení, že v části klíče se rozlišují malá a velká písmena. Výchozí hodnota nerozlišuje malá a velká písmena.

Další možnosti najdete v předmětu OutputCachePolicyBuilder .

Obnovení platnosti mezipaměti

Obnovení mezipaměti znamená, že server může místo celého textu odpovědi vrátit stavový 304 Not Modified kód HTTP. Tento stavový kód informuje klienta, že odpověď na požadavek se nezmění od toho, co klient dříve přijal.

Následující kód znázorňuje použití hlavičky k povolení opětovného Etag ověření mezipaměti. Pokud klient odešle hlavičku If-None-Match s hodnotou etag dřívější odpovědi a položka mezipaměti je čerstvá, server místo úplné odpovědi vrátí hodnotu 304 Není změněno . Tady je postup, jak nastavit hodnotu značky etag v zásadě v aplikaci s minimálním rozhraním API:

app.MapGet("/etag", async (context) =>
{
    var etag = $"\"{Guid.NewGuid():n}\"";
    context.Response.Headers.ETag = etag;
    await Gravatar.WriteGravatar(context);

}).CacheOutput();

A tady je postup, jak nastavit hodnotu značky v rozhraní API založeném na kontroleru:

[ApiController]
[Route("/[controller]")]
[OutputCache]
public class EtagController : ControllerBase
{
    public async Task GetAsync()
    {
        var etag = $"\"{Guid.NewGuid():n}\"";
        HttpContext.Response.Headers.ETag = etag;
        await Gravatar.WriteGravatar(HttpContext);
    }
}

Dalším způsobem, jak provést opětovné ověření mezipaměti, je zkontrolovat datum vytvoření položky mezipaměti v porovnání s datem požadovaným klientem. Po zadání hlavičky If-Modified-Since požadavku vrátí ukládání výstupu do mezipaměti hodnotu 304, pokud je položka uložená v mezipaměti starší a nevyprší platnost.

Opětovná aktualizace mezipaměti je automatická v reakci na tyto hlavičky odeslané z klienta. Na serveru není nutná žádná zvláštní konfigurace, aby bylo možné toto chování povolit, a to kromě povolení ukládání výstupu do mezipaměti.

Vyřazení položek mezipaměti pomocí značek

Značky můžete použít k identifikaci skupiny koncových bodů a vyřazení všech položek mezipaměti pro skupinu. Například následující minimální kód rozhraní API vytvoří dvojici koncových bodů, jejichž adresy URL začínají na blogu, a označí je jako tag-blog:

app.MapGet("/blog", Gravatar.WriteGravatar)
    .CacheOutput(builder => builder.Tag("tag-blog"));
app.MapGet("/blog/post/{id}", Gravatar.WriteGravatar)
    .CacheOutput(builder => builder.Tag("tag-blog"));

Následující kód ukazuje, jak přiřadit značky ke koncovému bodu v rozhraní API založeném na kontroleru:

[ApiController]
[Route("/[controller]")]
[OutputCache(Tags = new[] { "tag-blog", "tag-all" })]
public class TagEndpointController : ControllerBase
{
    public async Task GetAsync()
    {
        await Gravatar.WriteGravatar(HttpContext);
    }
}

Alternativní způsob přiřazení značek pro koncové body s trasami, které začínají blog , je definovat základní zásadu, která se vztahuje na všechny koncové body s danou trasou. Následující kód ukazuje, jak to udělat:

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => builder
        .With(c => c.HttpContext.Request.Path.StartsWithSegments("/blog"))
        .Tag("tag-blog"));
    options.AddBasePolicy(builder => builder.Tag("tag-all"));
    options.AddPolicy("Query", builder => builder.SetVaryByQuery("culture"));
    options.AddPolicy("NoCache", builder => builder.NoCache());
    options.AddPolicy("NoLock", builder => builder.SetLocking(false));
});

Další alternativou pro minimální aplikace API je volání MapGroup:

var blog = app.MapGroup("blog")
    .CacheOutput(builder => builder.Tag("tag-blog"));
blog.MapGet("/", Gravatar.WriteGravatar);
blog.MapGet("/post/{id}", Gravatar.WriteGravatar);

V předchozích příkladech přiřazení značek jsou značkou identifikovány tag-blog oba koncové body. Položky mezipaměti pro tyto koncové body pak můžete vyřadit jediným příkazem, který odkazuje na tuto značku:

app.MapPost("/purge/{tag}", async (IOutputCacheStore cache, string tag) =>
{
    await cache.EvictByTagAsync(tag, default);
});

S tímto kódem se odešle požadavek HTTP POST, který vyřadí https://localhost:<port>/purge/tag-blog položky mezipaměti pro tyto koncové body.

Možná budete chtít vyřadit všechny položky mezipaměti pro všechny koncové body. Uděláte to tak, že vytvoříte základní zásadu pro všechny koncové body, jak to dělá následující kód:

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => builder
        .With(c => c.HttpContext.Request.Path.StartsWithSegments("/blog"))
        .Tag("tag-blog"));
    options.AddBasePolicy(builder => builder.Tag("tag-all"));
    options.AddPolicy("Query", builder => builder.SetVaryByQuery("culture"));
    options.AddPolicy("NoCache", builder => builder.NoCache());
    options.AddPolicy("NoLock", builder => builder.SetLocking(false));
});

Tato základní zásada umožňuje použít značku "tag-all" k vyřazení všeho v mezipaměti.

Zakázání uzamčení prostředků

Ve výchozím nastavení je uzamčení prostředků povolené, aby se zmírnit riziko kolku mezipaměti a hřmění herdy. Další informace naleznete v tématu Ukládání výstupu do mezipaměti.

Pokud chcete zakázat zamykání prostředků, zavolejte Při vytváření zásad metodu SetLocking(false), jak je znázorněno v následujícím příkladu:

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => builder
        .With(c => c.HttpContext.Request.Path.StartsWithSegments("/blog"))
        .Tag("tag-blog"));
    options.AddBasePolicy(builder => builder.Tag("tag-all"));
    options.AddPolicy("Query", builder => builder.SetVaryByQuery("culture"));
    options.AddPolicy("NoCache", builder => builder.NoCache());
    options.AddPolicy("NoLock", builder => builder.SetLocking(false));
});

Následující příklad vybere zásadu bez uzamčení pro koncový bod v minimální aplikaci API:

app.MapGet("/nolock", Gravatar.WriteGravatar)
    .CacheOutput("NoLock");

V rozhraní API založeném na kontroleru pomocí atributu vyberte zásadu:

[ApiController]
[Route("/[controller]")]
[OutputCache(PolicyName = "NoLock")]
public class NoLockController : ControllerBase
{
    public async Task GetAsync()
    {
        await Gravatar.WriteGravatar(HttpContext);
    }
}

Omezení

Následující vlastnosti OutputCacheOptions umožňují konfigurovat limity, které platí pro všechny koncové body:

• SizeLimit – Maximální velikost úložiště mezipaměti. Po dosažení tohoto limitu nebudou žádné nové odpovědi uloženy do mezipaměti, dokud nebudou vyřazeny starší položky. Výchozí hodnota je 100 MB.
• MaximumBodySize – Pokud tělo odpovědi tento limit překročí, nebude uložena do mezipaměti. Výchozí hodnota je 64 MB.
• DefaultExpirationTimeSpan – Doba trvání vypršení platnosti, která platí, pokud není určena zásadou. Výchozí hodnota je 60 sekund.

Ukládání do mezipaměti

IOutputCacheStore se používá pro úložiště. Ve výchozím nastavení se používá s MemoryCache. Odpovědi uložené v mezipaměti se ukládají v procesu, takže každý server má samostatnou mezipaměť, která se ztratí při každém restartování procesu serveru.

Redis Cache

Alternativou je použití mezipaměti Redis . Redis Cache poskytuje konzistenci mezi uzly serveru prostřednictvím sdílené mezipaměti, která prožívá jednotlivé procesy serveru. Použití Redis pro ukládání výstupu do mezipaměti:

• Nainstalujte balíček NuGet Microsoft.AspNetCore.OutputCaching.StackExchangeRedis.

• Zavolejte builder.Services.AddStackExchangeRedisOutputCache (neAddStackExchangeRedisCache) a zadejte připojovací řetězec, který odkazuje na server Redis.

  Příklad:

  builder.Services.AddStackExchangeRedisOutputCache(options =>
  {
      options.Configuration = 
          builder.Configuration.GetConnectionString("MyRedisConStr");
      options.InstanceName = "SampleInstance";
  });
  
  builder.Services.AddOutputCache(options =>
  {
      options.AddBasePolicy(builder => 
          builder.Expire(TimeSpan.FromSeconds(10)));
  });
  

  • options.Configuration– připojovací řetězec k místnímu serveru Redis nebo hostované nabídce, jako je Azure Cache for Redis. Například <instance_name>.redis.cache.windows.net:6380,password=<password>,ssl=True,abortConnect=False pro Azure Cache for Redis.
  • options.InstanceName – Volitelné, určuje logický oddíl mezipaměti.

  Možnosti konfigurace jsou identické s možnostmi distribuované mezipaměti založené na Redis.

IDistributedCache nedoporučuje se

IDistributedCache Nedoporučujeme používat s ukládáním výstupu do mezipaměti. IDistributedCache nemá atomické funkce, které jsou potřeba pro označování. Doporučujeme používat integrovanou podporu pro Redis nebo vytvářet vlastní IOutputCacheStore implementace pomocí přímých závislostí na základním mechanismu úložiště.

Viz také

• Přehled ukládání do mezipaměti v ASP.NET Core
• ASP.NET Core Middleware
• OutputCacheOptions
• OutputCachePolicyBuilder