Copilot instructions

1---
2applyTo: "src/libraries/Microsoft.Extensions.Options*/**"
3---
4 
5# Microsoft.Extensions.Options — Folder-Specific Guidance
6 
7## Options Pattern Usage (D8)
8 
9- `IOptions<T>` provides a singleton snapshot — use `IOptionsMonitor<T>` when configuration may change at runtime
10- `IOptionsSnapshot<T>` is scoped — do not inject it into singleton services (captive dependency)
11- Named options must be resolved correctly — validate that the name parameter flows through the entire options pipeline
12- Null option names must resolve to `Options.DefaultName`
13 
14## Validation (D8, D13)
15 
16- `ValidateOnStart()` calls must not accumulate duplicate validation registrations — each call should be idempotent
17- Use `IValidateOptions<T>` for complex cross-property validation that data annotations cannot express
18- Validation source generator output must match the behavior of runtime validation for all supported attributes
19- `[Range]`, `[Required]`, and custom validation attributes must be tested with boundary values
20- Generated validation code must handle concurrent usage without race conditions (avoid shared mutable state in generated validators)
21 
22## Options Monitor & Change Tracking
23 
24- `IOptionsMonitor<T>.OnChange` notifications must propagate correctly to all subscribers during configuration reload
25- Change tracking must not race with concurrent reads — use appropriate synchronization
26 
27## Source Generator Parity (D13)
28 
29- Options validation source generator must produce identical results to the runtime reflection-based validator
30- Generated code must handle all edge cases: nullable types, default values, constructor `params` parameters
31- Test both generated and runtime validation paths — parity failures are critical bugs
32 
33## Architecture & Layering (D17)
34 
35- Options abstractions (`IOptions<T>`, `IOptionsMonitor<T>`) belong in `Microsoft.Extensions.Options`
36- Do not introduce unnecessary new packages — prefer extending existing ones unless layering requires separation
37- Package references must target correct and aligned versions
38- Changes to options defaults or validation behavior are breaking changes requiring migration guidance
39 
40