Enhance Performance Optimization Guidance

[yasaminashoori]

Search terms used: ASP.NET Core performance optimisation, caching best practices, IAsyncEnumerable streaming, async performance pitfalls.

Docs searched: the "Best Practices" section in ASP.NET Core Docs, Performance and Caching topics. These sources do not provide detailed guidance on advanced scenarios like large-data streaming or async-heavy workloads.

Why this topic: while the current "Best Practices" section covers general recommendations, developers working on high-load or complex applications need more advanced guidance on caching, streaming large datasets efficiently, and avoiding common async pitfalls.

Suggested location: expand the existing "Best Practices" section under Performance Optimization.

Abstract: this topic will cover advanced performance optimization in ASP.NET Core, including efficient caching strategies, streaming large datasets using IAsyncEnumerable, and avoiding common pitfalls in async-heavy workloads.

Outline:

Introduction to Advanced Performance Optimization
Efficient Caching Techniques
MemoryCache
DistributedCache
ResponseCache
Streaming Large Datasets with IAsyncEnumerable
Common Async Pitfalls and How to Avoid Them
Code Examples and Patterns
Summary and Recommendations

Update: Current coverage and gaps (per feedback from @wadepickett):

• Most of the caching mechanisms (MemoryCache, DistributedCache, ResponseCache via Tag Helpers) are partially covered in existing documentation.

• There is currently no coverage for:

  • Streaming large datasets efficiently using IAsyncEnumerable
  • Common async pitfalls and how to avoid them
  • A comprehensive guide tying together performance optimization techniques

References:

• Best Practices: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/best-practices.md
• HybridCache (.NET 9): https://learn.microsoft.com/en-us/dotnet/core/extensions/caching#hybridcache

[wadepickett]

Thanks #yasaminashoori!!! This is an area that could use some more information.

Triaging quick assessment:

Proposed additional guidance is for:
https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/best-practices.md

(cc: @tdykstra )

There is some coverage for some of these areas

Performance Optimization Topics Comparison

Proposed Outline Topic	Some Existing Documentation
Introduction to Advanced Performance Optimization	Partial coverage in Memory Management
Efficient Caching Techniques
- MemoryCache	Memory Cache in ASP.NET Core
- DistributedCache	Distributed Cache in ASP.NET Core
- ResponseCache	Cache Tag Helper and Distributed Cache Tag Helper
Streaming Large Datasets with IAsyncEnumerable	No comprehensive coverage.
Common Async Pitfalls and How to Avoid Them	No comprehensive coverage.
Code Examples and Patterns	Various examples spread across documentation, but no centralized resource for performance patterns

There is some coverage of caching mechanisms, which might need to expand (MemoryCache, DistributedCache, and ResponseCache via tag helpers), and there does seem to be a complete gap in documentation specifically addressing:

1. Advanced streaming techniques using IAsyncEnumerable for large datasets
2. Common async pitfalls and how to avoid them
3. A comprehensive guide that ties together these performance optimization techniques

Note: This topic on the HybridCache feature in .NET 9, addresses some advanced caching scenarios and a link to it from this performance doc might also help.

[yasaminashoori]

Thank you @wadepickett for the detailed feedback! I really appreciate your pointers.

I've refined the outline and content in an update section to ensure it complements existing documentation, fills the identified gaps, and provides actionable guidance for developers working on high-load or complex applications. I’m happy to take the next steps in drafting the detailed documentation once the outline and scope are agreed.

Please let me know if there are any additional points or suggestions. Looking forward to further feedback from @tdykstra and the team!

[wadepickett]

@tdykstra for input.

[yasaminashoori]

@wadepickett

Hi! I'm really interested in contributing to complete the documentation on the discussed topics. Should I get in touch with @dykstra?