Document cache tag helper in response caching doc

[danroth27]

No description provided.

[guardrex]

@tdykstra Want me to knock this out?

Come on, do you want me to beg? Do you want me on my knees, crying?

- Fifi Macaffee (Roger Ward), Mad Max, 1979

[tdykstra]

@guardrex Yes, please.

[guardrex]

@tdykstra A few problems here:

• We also have the <distributed-cache> TH. Given that we probably need to get into the cache repository options there, it will probably double the content that we need to provide.
• As it stands, the explanation of response caching in the Response Caching doc is tightly linked to headers that influence caching and the caching of entire responses. It's possible that the TH caching should be in its own doc. Note that ...
  • The Tag Helpers can vary-by-header, but the system isn't so tightly bound to headers. For example, caching can be set to absolute or sliding expiration, which is effective regardless of request headers.
  • The Tag Helpers can cache parts of responses (i.e., the content bound by the tag), and the content can be Razor content. They don't really do "response caching." It's more like "content caching" or something.
• These two Tag Helpers could also either have their own sample (if they're described in their own doc) or get rolled into the existing sample if the Response Caching doc is rewritten.
• Finally, there's the high level issue of what to do about all of the Tag Helpers and their docs. Does each of the ~17 MVC Tag Helpers deserve its own doc? If things went that way, then the Response Caching doc really would just link to it in its Resource section or with just a couple of lines in a section at the bottom of the doc.

Another alternative here is to punt 🏈 : Mention that these Tag Helpers exist in a section at the end of the doc and then link to the .NET Monsters video on the subject on Channel 9: https://channel9.msdn.com/Series/aspnetmonsters/Episode-35-Distributed-Cache-Tag-Helper

How do you want to proceed?

[tdykstra]

I'll defer to @danroth27

[Rick-Anderson]

@guardrex put it under https://docs.microsoft.com/en-us/aspnet/core/mvc/views/tag-helpers/intro
Can you post an outline and we'll get it approved?

[guardrex]

👍 Will do.

[Rick-Anderson]

@guardrex what took you so long to respond (sarcasm warning)?

[guardrex]

I'm at the 💪 gym 💪 and the weights are trying to kill me today. 💀 I just got pinned to the bench! 😄

[guardrex]

@Rick-Anderson I'll be knocking up the outline this evening, but just to clarify the doc location ...

mvc/views/tag-helpers/intro contains a sample and static content for the intro.md doc.

Do you want the doc, cache.md, and its associated static+sample folder cache, within the intro folder or within the tag-helpers folder?

[tdykstra]

tag-helpers folder

[guardrex]

thought so. thx.

[guardrex]

@Rick-Anderson @tdykstra

I almost have the outline ready. A few questions here ...

1. Do you want to call it Cache and distributed cache tag helpers, Caching tag helpers, or what do you want for the title? [@RickAndMSFT responds: I vote for Caching tag helpers ]
2. For the sample, I assume we'll go with one sample. <cache> and ... [@RickAndMSFT responds: OK]
   • Default Startup: <distributed-cache> using SQL cache
   • StartupWithRedis: <distributed-cache> using Redis cache
3. For <distributed-cache> using SQL, is it ok to go with Azure SQL Database? [@RickAndMSFT responds: OK]
4. For <distributed-cache> using Redis, is it ok to go with Azure Redis Cache? [@RickAndMSFT responds: OK]
5. We just want to define (not provide in the sample) the following extensibility points, correct?
   • IDistributedCacheTagHelperFormatter
   • IDistributedCacheTagHelperStorage
   • IDistributedCacheTagHelperService
6. I don't want to reinvent the wheel for IDistributedCache, so I plan to point the reader to performance/caching/distributed for more info. Ok? [@RickAndMSFT responds: OK]
7. Finally, do you want to get into the weeds on custom cache invalidation techniques? From what I've gathered thus far, it's not trivial. However, I'll Just Do It!™️ if we need to go there. [@RickAndMSFT responds: Skip this]

[Rick-Anderson]

@kichalla can you respond to outline questions. I responded inline with my guesses

[guardrex]

With @Rick-Anderson comments, this is what the draft outline looks like ...

Title: Caching tag helpers (mvc/views/tag-helpers/caching)

• Sample (MSBuild/csproj)
  • <cache> tag helper
  • Startup: <distributed-cache> tag helper using Azure SQL Database
  • StartupWithRedis: <distributed-cache> tag helper using Azure Redis Cache
• Introduction - Explain the purpose of these two TH's with examples of when a dev would want to use this type of caching. Provide some commentary on the persistence and distributed differences of the two TH's.
• <cache> tag helper - show example code from sample
• <distributed-cache> tag helper - show example code from sample
  • name attribute (prefix for the cache key to ensure unique cache entities)
  • IDistributedCache - Brief commentary and point to performance/caching/distributed
  • Configure with Azure SQL Database; refer to Azure doc for Azure setup
  • Configure with Azure Redis Cache; refer to Azure doc for Azure setup
• Use sample to demo <cache> and <distributed-cache> (SQL) behavior side-by-side
• Configuration
  • enabled attribute: true/false
  • priority attribute: CachePreservationPriority (Low, Normal, High, and NeverRemove)
  • Duration configuration
    • expires-after
    • expires-on
    • expires-sliding
    • Use sample to demo expires-after
  • vary-by-* version configuration
    • vary-by-cookie
    • vary-by-header
    • vary-by-query
    • vary-by-route
    • vary-by-user
    • vary-by
    • Use sample to demo vary-by-query
    • Use sample to demo composite key scenario: vary-by-header & vary-by-route
• <distributed-cache> custom implementations (define them; don't put into the sample)
  • IDistributedCacheTagHelperFormatter
  • IDistributedCacheTagHelperStorage
  • IDistributedCacheTagHelperService
• Resources
  • Introduction to Tag Helpers - mvc/views/tag-helpers/intro
  • Authoring Tag Helpers - mvc/views/tag-helpers/authoring
  • Azure SQL Database Documentation - https://docs.microsoft.com/azure/sql-database/
  • Azure Redis Cache Documentation - https://docs.microsoft.com/azure/redis-cache/
  • CacheTagHelper Class - https://docs.microsoft.com/aspnet/core/api/microsoft.aspnetcore.mvc.taghelpers.cachetaghelper
  • DistributedCacheTagHelper Class - https://docs.microsoft.com/aspnet/core/api/microsoft.aspnetcore.mvc.taghelpers.distributedcachetaghelper

[guardrex]

Isn't this covered now by https://github.com/aspnet/Docs/pull/2644/files#diff-1ce85b6d78dcd047d3358068e57048c9

[Rick-Anderson]

@guardrex I forgot @pkellner was working on that.
@kichalla can you respond to outline questions.
@pkellner can you review the info in this issue?

[Rick-Anderson]

@pkellner don't you cover this?

[guardrex]

@Rick-Anderson He did ... covered by #2644

[pkellner]

@Rick-Anderson @guardrex I'd say yes and no.

The "Built in Tag Helper" doc's I'm doing are targeting the user of tags. That is, primarily focussed around how to use the attributes associated with the tags and their implications (along with short examples).

The "Yes" part of the answer is that I say in the Distributed Cache Tag Helper doc

Distributed Cache Tag Helper inherits from the same class as Cache Tag Helper so all these attributes are common from Cache Tag Helper.

Because there are two built in implementations, I feel obligated to mention them as well as have a reference to an article that gives many more details about configurations.

There are two implementations of IDistributedCache built in to ASP.NET Core. One is based on Sql Server and the other is based on Redis. Details of these implementations can be found at the resource referenced below named "Working with a distributed cache". Both implementations involve setting an instance of IDistributedCache in ASP.NET Core's startup.cs.

Finally, I think details about how to build your own distributed cache implementation (including what methods need implementing) should be in a separate document along with a fully documented reference implementation.

LMK if you agree. Happy to update what I've done accordingly. Currently, I've got in my branch both the Distributed Cache and Cache Tag Helpers documented as I thought appropriate.

[pkellner]

@Rick-Anderson @guardrex Forgot to mention the "no" part of the answer is that I was not planning on doing the detailed doc on how to implement your own distributed cache tag helper. I'd be open to talking about it later, but for the moment, I'm focussed and committed to getting all the built in tag helpers documented as I described above.

[Rick-Anderson]

@pkellner I didn't intend for you to cover implement your own distributed cache tag helper, just doc'ing the built in TH.

[pkellner]

@Rick-Anderson I'm mostly looking for guidance on what to cover in Distributed Cache Tag Helper and what not do. In the branch below I've done the following. I'm open to changing what I've done based on guidance.

https://github.com/pkellner/Docs/blob/ra-pKellner-built-in-TH/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md

1. I did not detail any attributes that are in common with Cache Tag Helper
2. I did not document details of Redis or SqlServer implementations
3. I did not detail interface that must be implemented

My thinking is that these are all detailed (and will be maintained I assume) on other doc pages.

[Rick-Anderson]

@pkellner That sounds reasonable.