Copilot instructions

1---
2applyTo: "src/libraries/Microsoft.Extensions.Http*/**,src/libraries/Microsoft.Extensions.FileProviders*/**,src/libraries/Microsoft.Extensions.Primitives*/**"
3---
4 
5# Microsoft.Extensions Common Libraries — Folder-Specific Guidance
6 
7Covers `Microsoft.Extensions.Http`, `Microsoft.Extensions.FileProviders`, and `Microsoft.Extensions.Primitives`.
8 
9## Extensions.Http (D17, D7)
10 
11- `HttpClientFactory` registration helpers must use `TryAdd` patterns to avoid overriding user-configured handlers
12- `DelegatingHandler` chains must correctly propagate disposal — document ownership of inner handlers
13- Connection pooling and lifetime settings (`PooledConnectionLifetime`) must be documented when composing `HttpClient` configurations
14- Ensure thread-safe access for `HttpClient` instances shared via factory — use `CompareExchange` for lazy initialization
15- Avoid per-operation allocations in handler pipelines — cache delegates and reuse handler instances where possible
16- All HttpClientFactory types must be trim-safe and NativeAOT-compatible
17 
18## Extensions.FileProviders (D10, D4)
19 
20- `PhysicalFileProvider` must handle concurrent file operations — use `FileShare.Delete` when reading files that may be rotated
21- File provider ownership is not transferred to `IConfigurationRoot` or `IConfigurationProvider` — document the ownership boundary
22- `IChangeToken` implementations must correctly handle callback registration and disposal
23- Polling-based file watchers must have configurable intervals and must clean up on disposal
24- Avoid unnecessary `ToArray()`/`ToList()` calls — prefer lazy enumeration with yield return when callers do not need materialized collections
25- Directory enumeration order changes are breaking changes — test ordering expectations
26 
27## Extensions.Primitives (D1, D5)
28 
29- `StringSegment` must provide string-equivalent operations — missing methods should maintain API parity with `string`
30- `ChangeToken.OnChange` registrations must be disposed when the owning component is disposed to prevent leaks
31- Implicit operators (e.g., string to `StringSegment`) must be documented and must not allocate on the conversion path
32- `GetHashCode` implementations must not allocate — use span overloads rather than allocating substrings
33- Avoid `Unsafe.As` casts when a standard cast is equally cheap (e.g., object to string)
34- Performance-sensitive code paths must avoid closures, string allocations, and boxing
35 
36## Cross-Cutting
37 
38- All types in these libraries must be trim-safe and NativeAOT-compatible
39- Public API changes must be evaluated for backward compatibility — these are foundational types with many downstream consumers
40- Abstractions (interfaces, base classes) belong in `*.Abstractions` packages; implementations in concrete packages
41 
42