Copilot instructions

1---
2applyTo: "src/libraries/Microsoft.Extensions.Configuration*/**"
3---
4 
5# Microsoft.Extensions.Configuration — Folder-Specific Guidance
6 
7## Configuration Binding (D8)
8 
9- Configuration key lookups are case-insensitive — all switch statements and dictionary lookups over config keys must use `StringComparison.OrdinalIgnoreCase`
10- The default binder suppresses binding errors and silently skips unrecognized properties — document this when code depends on strict binding
11- Type conversion failures during binding must produce clear error messages identifying the configuration key and expected type
12- `IOptionsMonitor<T>` change notifications must propagate correctly to all subscribers during reload without race conditions
13- `ValidateOnStart()` calls must be idempotent — must not accumulate duplicate validation registrations
14 
15## Source Generator Parity (D13)
16 
17- Source-generated binding code must produce identical behavior to the runtime reflection-based binder for all supported types
18- Generated switch blocks over configuration keys must use case-insensitive comparison
19- Generated code must handle nullable types, default values, collections, and nested objects correctly
20- Incremental generators must handle cancellation and produce correct output on incremental changes
21- Test both source-generated and runtime code paths — parity failures are critical bugs
22 
23## Resource Ownership & Change Tokens (D4)
24 
25- File-based configuration providers must handle concurrent file replacement — use `FileShare.Delete` when reading
26- `IConfigurationRoot.Dispose` must dispose owned providers; document ownership for custom providers
27- Reload tokens must not leak event handler registrations — unsubscribe on disposal
28- Configuration providers own their data — `IConfigurationRoot` does not own `IFileProvider` instances
29 
30## Error Handling (D9)
31 
32- Exceptions must be the most specific applicable type with actionable context (key name, expected vs actual type)
33- Exceptions from inner operations must be wrapped or propagated — never swallowed silently
34- Configuration reload failures must be observable through logging or change notification callbacks
35 
36## Null Safety (D3)
37 
38- Input from configuration values and deserialized data must be validated for both null and semantic correctness
39 
40## Trim & AOT (D14)
41 
42- Annotate reflection-using binding APIs with `[DynamicallyAccessedMembers]` to preserve required metadata
43- Provide feature switches so the linker can trim optional binding functionality
44- No new IL2xxx trim warnings without explicit justification
45 
46