HybridCache doc -- Add AOT, explain immutable, and edit pass using Acrolinx

[tdykstra]

Fixes #35505
Fixes #34974

---

Internal previews

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

[Copilot]

Pull Request Overview

This PR refines the HybridCache documentation style and adds guidance for using HybridCache in Native AOT scenarios.

• Edited wording, punctuation, and numeric formatting for clarity and consistency.
• Added a “Use Hybrid Cache with Native AOT” section covering serialization and trimming considerations.
• Streamlined the Additional Resources section to focus on the source code link.

Comments suppressed due to low confidence (1)

aspnetcore/performance/caching/hybrid.md:239

• Indent the description lines under the **Serialization** and **Trimming** bullets by at least four spaces so they render correctly as nested list items in Markdown.

  Native AOT doesn't support runtime reflection-based serialization. If you cache custom types, you must use source generators or explicitly configure serializers that are compatible with AOT, like `System.Text.Json` source generation. For example, with `System.Text.Json`, register a `JsonSerializerContext` for your types and configure it in `AddHybridCache`.

[Copilot]

[nitpick] Consider removing the informal lead-in "So" and rewriting for a more formal tone, e.g., "When targeting Native AOT, ensure your serialization setup is AOT-compatible; otherwise, HybridCache behaves the same..."

Suggested change

	So the main difference if you want to use AOT with `AddHybridCache` is the need to ensure that your serialization setup is AOT-compatible. Otherwise, `HybridCache` works the same way in Native AOT as in regular ASP.NET Core apps.
	When targeting Native AOT, ensure your serialization setup is AOT-compatible. Otherwise, `HybridCache` behaves the same way in Native AOT as in regular ASP.NET Core apps.

[Copilot]

[nitpick] The previous multi-resource list (including the GitHub issue #54647) was removed. If those references remain valuable for context, consider reintroducing them or explaining why only the source-code link is kept.

Suggested change

	For more information, see [the `HybridCache` source code](https://source.dot.net/#Microsoft.Extensions.Caching.Abstractions/Hybrid/HybridCache.cs)
	For more information, see:
	- [The `HybridCache` source code](https://source.dot.net/#Microsoft.Extensions.Caching.Abstractions/Hybrid/HybridCache.cs)
	- [GitHub issue #54647: Discussion on HybridCache improvements](https://github.com/dotnet/aspnetcore/issues/54647)
	If other references were removed, it was because they were outdated or no longer relevant to the current implementation of `HybridCache`.

[tdykstra]

The source code and GitHub issue links were added when the feature was still in Preview and by now are already getting out of date. The source code link that remains was changed from a permanent URL to a main branch URL. It won't get out of date.

[wadepickett]

Looks good. I agree with the minor nit from copilot on "So the main difference" change.
Consider updating the ms.date meta data if appropriate.

[Copilot]

Pull Request Overview

Adds Native AOT considerations to the HybridCache documentation and applies an editorial pass for clarity and consistency.

• Enhanced guidance on cache key usage, token significance, and tag invalidation.
• Introduced a “Use Hybrid Cache with Native AOT” section covering serialization and trimming.
• Applied formatting and wording edits (contractions, punctuation, numeric formatting).

[Copilot]

[nitpick] The numeric literal '1,024' includes a comma, which may be inconsistent with other code samples and documentation style; consider using '1024' for consistency.

Suggested change

	* Keys can be restricted to valid maximum lengths. For example, the default `HybridCache` implementation (via `AddHybridCache(...)`) restricts keys to 1,024 characters by default. That number is configurable via `HybridCacheOptions.MaximumKeyLength`, with longer keys bypassing the cache mechanisms to prevent saturation.
	* Keys can be restricted to valid maximum lengths. For example, the default `HybridCache` implementation (via `AddHybridCache(...)`) restricts keys to 1024 characters by default. That number is configurable via `HybridCacheOptions.MaximumKeyLength`, with longer keys bypassing the cache mechanisms to prevent saturation.

[mgravell]

There is an alternative way to configure System.Text.Json for AOT with HybridCache; right now it requires knowing a hidden magic trick via dependency injection (i.e. there is no explicit API), but we're looking at adding that very soon. Here's the associated PR: dotnet/extensions#6475

Right now, you'd need to use something like:

var jsonOptions = new JsonSerializerOptions() { TypeInfoResolver = Bar.MyJsonSerializationContext.Default };
services.AddHybridCache();
services.AddKeyedSingleton<JsonSerializerOptions>(typeof(IHybridCacheSerializer<>), jsonOptions);

for JSON with AOT - which is awkward an non-obvious (we added support very late, and didn't have time for formal API review), but in some future version this will be equivalent to (API to be confirmed):

var jsonOptions = new JsonSerializerOptions() { TypeInfoResolver = Bar.MyJsonSerializationContext.Default };
services.AddHybridCache().WithJsonSerializerOptions(jsonOptions);

[mgravell]

This refers to a future / proposed API addition; at the moment, this guidance would be very unclear. Question (genuinely): which is better:

1. issue guidance today that is obscure but tells them how to configure HybridCache for AOT via DI
2. defer until this is neatly wrapped in a managed easy to use API

?