Intergiciel de mise en cache de sorite dans ASP.NET Core

Par Tom Dykstra

Cet article explique comment configurer l’intergiciel de mise en cache de sortie dans une application ASP.NET Core. Pour une présentation de la mise en cache de sortie, consultez Mise en cache de sortie.

L’intergiciel de mise en cache de sortie peut être utilisé dans tous les types d’applications ASP.NET Core : API minimale, API web avec contrôleurs, MVC et Razor Pages. Des exemples de code sont fournis pour les API minimales et les API basées sur le contrôleur. Les exemples d’API basées sur le contrôleur montrent comment utiliser des attributs pour configurer la mise en cache. Ces attributs peuvent également être utilisés dans les applications MVC et Razor Pages.

Les exemples de code font référence à une classe Gravatar qui génère une image et fournit une date et une heure de génération. La classe est définie et utilisée uniquement dans l’exemple d’application. Son but est de permettre de voir facilement quand la sortie mise en cache est utilisée. Pour plus d’informations, consultez Comment télécharger un exemple et Directives de préprocesseur dans un exemple de code.

Ajouter l’intergiciel à l’application

Ajoutez l’intergiciel de mise en cache de sortie à la collection de services en appelant AddOutputCache.

Ajoutez l’intergiciel au pipeline de traitement des demandes en appelant UseOutputCache.

Par exemple :

builder.Services.AddOutputCache();

var app = builder.Build();

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

Appeler AddOutputCache et UseOutputCache ne commence pas à mettre le comportement en cache, cela rend la mise en cache disponible. Pour que l’application mette en cache les réponses, la mise en cache doit être configurée comme indiqué dans les sections suivantes.

Remarque

• Dans les applications qui utilisent l’intergiciel CORS, UseOutputCache doit être appelé après UseCors.
• Dans les applications Razor Pages et les applications avec contrôleurs, UseOutputCache doit être appelé après UseRouting.

Configurer un point de terminaison ou une page

Pour les applications API minimales, configurez un point de terminaison pour qu’il effectue la mise en cache en appelant CacheOutput ou en appliquant l’attribut [OutputCache] , comme illustré dans les exemples suivants :

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

Pour les applications avec des contrôleurs, appliquez l’attribut [OutputCache] à la méthode d’action comme indiqué ici :

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

Pour les applications Razor Pages, appliquez l’attribut à la classe de page Razor.

Configurer plusieurs points de terminaison ou pages

Créez des stratégies lors de l’appel de AddOutputCache pour spécifier la configuration de mise en cache qui s’applique à plusieurs points de terminaison. Une stratégie peut être sélectionnée pour des points de terminaison spécifiques, tandis qu’une stratégie de base fournit une configuration de mise en cache par défaut pour une collection de points de terminaison.

Le code suivant mis en évidence configure la mise en cache pour tous les points de terminaison de l’application, avec une durée d’expiration de 10 secondes. Si aucune heure d’expiration n’est spécifiée, elle est définie par défaut sur une minute.

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

Le code suivant en surbrillance crée deux stratégies, chacune spécifiant une heure d’expiration différente. Les points de terminaison sélectionnés peuvent utiliser le délai d’expiration de 20 secondes, tandis que les autres peuvent utiliser le délai d’expiration de 30 secondes.

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

Vous pouvez sélectionner une stratégie pour un point de terminaison lors de l’appel de la méthode CacheOutput ou de l’attribut [OutputCache].

Dans une application API minimale, le code suivant configure un point de terminaison avec une expiration de 20 secondes et un point de terminaison avec une expiration de 30 secondes :

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

Pour les applications avec des contrôleurs, appliquez l’attribut [OutputCache] à la méthode d’action pour sélectionner une stratégie :

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

Pour les applications Razor Pages, appliquez l’attribut à la classe de page Razor.

Stratégie de mise en cache de sortie par défaut

Par défaut, la mise en cache de sortie suit les règles suivantes :

• Seules les réponses HTTP 200 sont mises en cache.
• Seules les requêtes HTTP GET ou HEAD sont mises en cache.
• Les réponses qui utilisent des cookies ne sont pas mises en cache.
• Les réponses aux demandes authentifiées ne sont pas mises en cache.

Le code suivant applique toutes les règles de mise en cache par défaut à tous les points de terminaison d’une application :

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

Substituer la stratégie par défaut

Le code suivant montre comment substituer les règles par défaut. Les lignes mises en surbrillance dans le code de stratégie personnalisé suivant permettent la mise en cache pour les méthodes HTTP POST et les réponses 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;
    }
}

Pour utiliser cette stratégie personnalisée, créez une stratégie nommée :

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

Sélectionnez la stratégie nommée pour un point de terminaison. Le code suivant sélectionne la stratégie personnalisée pour un point de terminaison dans une application API minimale :

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

Le code suivant fait de même pour une action de contrôleur :

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

Remplacement de stratégie par défaut alternative

Vous pouvez également utiliser l’injection de dépendances (DI) pour initialiser une instance, avec les modifications suivantes apportées à la classe de stratégie personnalisée :

• Un constructeur public au lieu d’un constructeur privé.
• Supprimez la propriété Instance dans la classe de stratégie personnalisée.

Par exemple :

public sealed class MyCustomPolicy2 : IOutputCachePolicy
{

    public MyCustomPolicy2()
    {
    }

Le reste de la classe est le même qu’indiqué précédemment. Ajoutez la stratégie personnalisée comme indiqué dans l’exemple suivant :

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

Le code précédent utilise l’ID pour créer l’instance de la classe de stratégie personnalisée. Tous les arguments publics dans le constructeur sont résolus.

Lorsque vous utilisez une stratégie personnalisée comme stratégie de base, n’appelez pas OutputCache() (sans argument) ou utilisez l’attribut [OutputCache] sur un point de terminaison auquel la stratégie de base doit s’appliquer. Appeler OutputCache() ou utiliser l’attribut ajoute la stratégie par défaut au point de terminaison.

Indiquer la clé cache

Par défaut, chaque partie de l’URL est incluse comme clé d’entrée de cache, c’est-à-dire le schéma, l’hôte, le port, le chemin d’accès et la chaîne de requête. Toutefois, vous pouvez contrôler explicitement la clé de cache. Par exemple, supposons que vous ayez un point de terminaison qui retourne une réponse unique seulement pour chaque valeur unique de la chaîne de requête culture. La variation d’autres parties de l’URL, telles que d’autres chaînes de requête, ne doit pas entraîner d’entrées de cache différentes. Vous pouvez spécifier ces règles dans une stratégie, comme indiqué dans le code en surbrillance suivant :

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

Vous pouvez ensuite sélectionner la stratégie VaryByQuery pour un point de terminaison. Dans une application API minimale, le code suivant sélectionne la stratégie VaryByQuery pour un point de terminaison qui retourne une réponse unique uniquement pour chaque valeur unique de la chaîne de requête culture :

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

Le code suivant fait de même pour une action de contrôleur :

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

Voici quelques-unes des options permettant de contrôler la clé de cache :

• SetVaryByQuery – Spécifiez un ou plusieurs noms de chaîne de requête à ajouter à la clé de cache.

• SetVaryByHeader – Spécifiez un ou plusieurs en-têtes HTTP à ajouter à la clé de cache.

• VaryByValue – Spécifiez une valeur à ajouter à la clé de cache. L’exemple suivant utilise une valeur qui indique si l’heure actuelle du serveur en secondes est impaire ou égale. Une nouvelle réponse n’est générée que lorsque le nombre de secondes passe de impair à pair ou de pair à impair.

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

Utilisez OutputCacheOptions.UseCaseSensitivePaths pour spécifier que la partie chemin d’accès de la clé respecte la casse. La valeur web par défaut doit respecter la casse.

Pour plus d’options, consultez la classe OutputCachePolicyBuilder.

Revalidation du cache

La revalidation du cache signifie que le serveur peut retourner un code d’état HTTP 304 Not Modified au lieu d’un corps de réponse entier. Ce code statut informe le client que la réponse à la requête est inchangée par rapport à ce que le client a reçu précédemment.

Le code suivant illustre l’utilisation d’un en-tête Etag pour activer la revalidation du cache. Si le client envoie un en-tête If-None-Match avec la valeur etag d’une réponse antérieure et que l’entrée du cache est nouvelle, le serveur retourne 304 Non modifié au lieu de la réponse complète. Voici comment définir la valeur etag dans une stratégie, dans une application API minimale :

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

}).CacheOutput();

Et voici comment définir la valeur etag dans une API basée sur un contrôleur :

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

Une autre façon d’effectuer la revalidation du cache consiste à vérifier la date de création de l’entrée de cache par rapport à la date demandée par le client. Lorsque l’en-tête de demande If-Modified-Since est fourni, la mise en cache de sortie retourne 304 si l’entrée mise en cache est antérieure et n’a pas expiré.

La revalidation du cache est automatique en réponse à ces en-têtes envoyés à partir du client. Aucune configuration spéciale n’est requise sur le serveur pour activer ce comportement, à part l’activation de la mise en cache de sortie.

Utiliser des balises pour supprimer les entrées de cache

Vous pouvez utiliser des balises pour identifier un groupe de points de terminaison et supprimer toutes les entrées de cache pour le groupe. Par exemple, le code d’API minimale suivant crée une paire de points de terminaison dont les URL commencent par « blog » et les étiquette « 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"));

Le code suivant montre comment attribuer des balises à un point de terminaison dans une API basée sur un contrôleur :

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

Une autre façon d’attribuer des balises pour les points de terminaison dont les itinéraires commencent par blog consiste à définir une stratégie de base qui s’applique à tous les points de terminaison avec cet itinéraire. Le code suivant montre comment procéder :

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

Une autre alternative pour les applications API minimales consiste à appeler MapGroup :

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

Dans les exemples d’attribution de balise précédents, les deux points de terminaison sont identifiés par la balise tag-blog. Vous pouvez ensuite supprimer les entrées de cache pour ces points de terminaison avec une seule instruction qui fait référence à cette balise :

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

Avec ce code, une requête HTTP POST envoyée à https://localhost:<port>/purge/tag-blog supprime les entrées de cache pour ces points de terminaison.

Vous souhaiterez peut-être pouvoir effacer toutes les entrées de cache pour tous les points de terminaison. Pour ce faire, créez une stratégie de base pour tous les points de terminaison comme le fait le code suivant :

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

Cette stratégie de base vous permet d’utiliser la balise « tag-all » pour tout supprimer dans le cache.

Désactiver le verrouillage des ressources

Par défaut, le verrouillage des ressources est activé pour atténuer le risque de tamponnement du cache et de tonitruation du troupeau. Pour plus d’informations, consultez Cache de sortie.

Pour désactiver le verrouillage des ressources, appelez SetLocking(false) lors de la création d’une stratégie, comme illustré dans l’exemple suivant :

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

L’exemple suivant sélectionne la stratégie de non-verrouillage pour un point de terminaison avec une application API minimale :

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

Dans une API basée sur un contrôleur, utilisez l’attribut pour sélectionner la stratégie :

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

Limites

Les propriétés suivantes de OutputCacheOptions vous permettent de configurer des limites qui s’appliquent à tous les points de terminaison :

• SizeLimit – Taille maximale du stockage de cache. Quand cette limite est atteinte, aucune nouvelle réponse n’est mise en cache jusqu’à ce que les entrées plus anciennes soient supprimées. La valeur par défaut est 100 Mo.
• MaximumBodySize – Si le corps de la réponse dépasse cette limite, elle n’est pas mise en cache. La valeur par défaut est 64 Mo.
• DefaultExpirationTimeSpan – Durée d’expiration qui s’applique quand elle n’est pas spécifiée par une stratégie. La valeur par défaut est 60 secondes.

Stockage du cache

IOutputCacheStore est utilisé pour le stockage. Par défaut, il est utilisé avec MemoryCache. Les réponses mises en cache sont stockées In-process, de sorte que chaque serveur a un cache distinct qui est perdu chaque fois que le processus serveur est redémarré.

Cache Redis

Une alternative consiste à utiliser le cache Redis. Le cache Redis assure la cohérence entre les nœuds du serveur grâce à un cache partagé qui survit aux processus individuels du serveur. Pour utiliser Redis pour la mise en cache des sorties :

• Installez le package NuGet Microsoft.AspNetCore.OutputCaching.StackExchangeRedis.

• Appelez builder.Services.AddStackExchangeRedisOutputCache (pas AddStackExchangeRedisCache) et spécifiez une chaîne de connexion qui pointe vers un serveur Redis.

  Par exemple :

  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 – Une chaîne de connexion à un serveur Redis local ou à une offre hébergée comme Azure Cache pour Redis. Par exemple, <instance_name>.redis.cache.windows.net:6380,password=<password>,ssl=True,abortConnect=False pour Azure Cache pour Redis.
  • options.InstanceName – Facultatif, spécifie une partition logique pour le cache.

  Les options de configuration sont identiques aux options de mise en cache distribuée basée sur Redis.

IDistributedCache n’est pas recommandé

Nous vous déconseillons d’utiliser IDistributedCache avec la mise en cache de sortie. IDistributedCache n’a pas de caractéristiques atomiques, qui sont requises pour le balisage. Nous vous recommandons d’utiliser la prise en charge intégrée pour Redis ou de créer des implémentations de IOutputCacheStore personnalisées en utilisant des dépendances directes sur le mécanisme de stockage sous-jacent.

Voir aussi

• Vue d’ensemble de la mise en cache dans ASP.NET Core
• Intergiciel (middleware) ASP.NET Core
• OutputCacheOptions
• OutputCachePolicyBuilder