HybridCache - additional guidance on cache key composition

[mgravell]

Additional clarifications on cache key usage, requested via internal API review

/cc @tdykstra in particular; is this reasonable and welcomed?

Fixes #34647

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/performance/caching/hybrid.md	HybridCache library in ASP.NET Core

[mgravell]

also, thoughts on whether any of this should be echoed to (for example) HybridCache.GetOrCreateAsync - and if so: how? This is generated from intellisense - maybe a remarks link along the lines of

/// <remarks>For guidance on <paramref name="key"/> usage, please see https://learn.microsoft.com/aspnet/core/performance/caching/hybrid#somesectionhere.</remarks>

or is that too clumsy? is there a better / more typical approach?

[tdykstra]

This is a great addition to the article! I framed my edits as suggestions that you can accept as-is or edit.

[tdykstra]

/cc @tdykstra in particular; is this reasonable and welcomed?

It is both reasonable and welcomed. The information is worth adding to the article.

[tdykstra]

also, thoughts on whether any of this should be echoed to (for example) HybridCache.GetOrCreateAsync - and if so: how? This is generated from intellisense - maybe a remarks link along the lines of

/// <remarks>For guidance on <paramref name="key"/> usage, please see https://learn.microsoft.com/aspnet/core/performance/caching/hybrid#somesectionhere.</remarks>

or is that too clumsy? is there a better / more typical approach?

I think that makes sense, but I'll ask the expert -- @gewarren How would you handle this:

• In the GetOrCreate method API ref, link to the key guidance section of the hybrid cache article (the key guidance isn't in live yet but will follow this section).
• In the HybridCache class API ref, link to the hybrid cache conceptual article, not to a subsection.
• Both. We should link from API to conceptual wherever it might make sense.
• Neither. Avoid linking from API, put explanatory text in the API ref itself.

[gewarren]

@tdykstra I would say option C...both! And there's a clean way to do it, like this: https://github.com/dotnet/dotnet-api-docs/blob/329ae1e7f5f755d8a54fb7da57ef3e0e2ad2844d/xml/System/Func%601.xml#L129