Copilot instructions

1---
2applyTo: "src/libraries/Microsoft.Extensions.Caching*/**"
3---
4 
5# Microsoft.Extensions.Caching — Folder-Specific Guidance
6 
7## Cache Key Correctness (D20)
8 
9- Cache keys must incorporate all inputs that affect the cached result — including format versions, serialization options, and any parameters that change the output
10- Key generation must be deterministic and stable across process restarts for distributed caches
11- Verify that key composition does not create collisions for distinct inputs
12- Cache miss must be distinguishable from a cached null value
13 
14## Eviction Policies (D20)
15 
16- Cache eviction must consider TTL, priority, estimated object size, and memory pressure — not just LRU
17- Expose eviction callbacks so consumers can observe and react to entry removal
18- Memory pressure-based eviction should clear stale references to avoid retaining unused objects
19 
20## Stampede Prevention (D20)
21 
22- When a cache entry expires, only one caller should recompute the value while others wait (thundering herd mitigation)
23- HybridCache (available in .NET 9+) and similar patterns should use a single-flight mechanism for concurrent requests to the same key
24 
25## Performance & Allocation (D5)
26 
27- Closures for cache factory methods must not allocate on every cache access — cache the delegate or use a static lambda with explicit state
28- Distributed cache serialization must handle large objects efficiently — consider compression and streaming for values over 100KB
29- In-memory cache operations must avoid holding locks during expensive value computation
30- Hot paths must avoid per-operation allocations — prefer pooled buffers and cached delegates
31 
32## Thread Safety (D6)
33 
34- `MemoryCache` and `HybridCache` (available in .NET 9+) are expected to be used concurrently — all access patterns must be thread-safe
35- Entry creation and eviction callbacks may execute on different threads — do not assume single-threaded access
36 
37## Distributed vs In-Memory
38 
39- `IDistributedCache` implementations must handle serialization/deserialization correctly and document size limits
40- Test with both in-memory and distributed backing stores — behavior differences must be accounted for
41- Distributed cache key expiration semantics may differ from in-memory — document and test accordingly
42 
43