From 046b3281e1641dd317653bd252b6a6f0e0fd814c Mon Sep 17 00:00:00 2001
From: Marcello Lamonaca <marcello@lamonaca.eu>
Date: Tue, 19 Jul 2022 15:17:19 +0200
Subject: [PATCH] minimal api: add output cache notes

---
 docs/dotnet/asp.net/minimal-api.md | 61 ++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/docs/dotnet/asp.net/minimal-api.md b/docs/dotnet/asp.net/minimal-api.md
index b582366..a71b790 100644
--- a/docs/dotnet/asp.net/minimal-api.md
+++ b/docs/dotnet/asp.net/minimal-api.md
@@ -161,3 +161,64 @@ app.UseAuthorization(); // must come before routes
 app.MapGet("/alcohol", () => Results.Ok()).RequireAuthorization("<policy>");  // on specific endpoints
 app.MapGet("/free-for-all", () => Results.Ok()).AllowAnonymous();
 ```
+
+## Output Caching
+
+```cs
+builder.Services.AddOutputCaching();  // no special options
+builder.Services.AddOutputCaching(options => 
+{
+    options => options.AddBasePolicy(x => x.NoCache())  // no cache policy
+
+    Func<OutputCacheContext, bool> predicate = /* discriminate requests */
+    options.AddBasePolicy(x => x.With(predicate).CachePolicy());
+    options.AddBasePolicy("<policy-name>", x => x.CachePolicy());  // named policy
+});
+
+// [...]
+
+app.UseOutputCaching();  // following middlewares can use output cache
+
+// [...]
+
+app.MapGet("/<route>", RouteHandler).CacheOutput();  // cache forever
+app.MapGet("/<route>", RouteHandler).CacheOutput().Expire(timespan);
+
+app.MapGet("/<route>", RouteHandler).CacheOutput(x => x.CachePolicy());
+app.MapGet("/<route>", RouteHandler).CacheOutput("<policy-name>");
+
+app.MapGet("/<route>", RouteHandler).CacheOutput(x => x.VaryByHeader(/* headers list */));
+app.MapGet("/<route>", RouteHandler).CacheOutput(x => x.VaryByQuery(/* query key */));
+app.MapGet("/<route>", RouteHandler).CacheOutput(x => x.VaryByValue());
+
+app.MapGet("/<route>", [OutputCache(/* options */)]RouteHandler);
+```
+
+### Cache Eviction
+
+```cs
+
+app.MapGet("/<route-one>", RouteHandler).CacheOutput(x => x.Tag("<tag>"));  // tag cache portion
+
+app.MapGet("/<route-two>", (IOutputCacheStore cache, CancellationToken token) => 
+{
+    await cache.EvictByTag("<tag>", token);  // invalidate a portion of the cache
+});
+```
+
+### Custom Cache Policy
+
+```cs
+app.MapGet("/<route-one>", RouteHandler).CacheOutput(x => x.AddCachePolicy<CustomCachePolicy>());
+```
+
+```cs
+class CustomCachePolicy : IOutputCachePolicy
+{
+    public ValueTask CacheRequestAsync(OutputCacheContext context, CancellationToken cancellationToken) { }
+
+    public ValueTask ServeFromCacheAsync(OutputCacheContext context, CancellationToken cancellationToken) { }
+
+    public ValueTask ServeResponseAsync(OutputCacheContext context, CancellationToken cancellationToken) { }
+}
+```