From b463f168069bf8a7e4c4d1260add36c177c1cd27 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Wed, 18 Mar 2026 13:30:24 +1300 Subject: [PATCH] chore: Added context re bindable options for agents #skip-changelog --- AGENTS.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ff986efde2..100a221a9c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,6 +139,19 @@ gh pr view --json number -q '.number' - Maintain **backwards compatibility** — avoid breaking public API without strong justification - Platform-specific code lives in `src/Sentry/Platforms/` and is conditionally compiled +## Adding New Options (AOT Compatibility) + +`SentryOptions` is **not** bound directly from configuration. Instead, a parallel `BindableSentryOptions` class (`src/Sentry/BindableSentryOptions.cs`) exists for AOT-safe configuration binding. + +When adding a configurable property to any of the classes descending from `SentryOptions`: + +1. Add the property to `SentryOptions` as normal. +2. Add a matching **nullable** property to `BindableSentryOptions`. Use only simple/primitive types the source generator can handle. For complex types (e.g., `IReadOnlyList`), use a simpler surrogate (e.g., `List?`) and convert in `ApplyTo`. +3. Add a line in `BindableSentryOptions.ApplyTo`: `options.MyProp = MyProp ?? options.MyProp;` +4. Run the relevant bindable options test (e.g., `BindableSentryOptionsTests`) — the `BindableProperties_MatchOptionsProperties` test will fail if any bindable property is missing from the bindable class. + +The same pattern applies to `BindableSentryAspNetCoreOptions`, `BindableSentryMauiOptions`, `BindableSentryLoggingOptions`, and the platform-specific partial classes under `src/Sentry/Platforms/`. + ## Commit Attribution AI commits MUST include: