sentry-dotnet
AGENTS.md776 starsChanged 3 days agoMITView on GitHub
The Sentry SDK for .NET: a multi-package repo (Sentry, Sentry.AspNetCore, Sentry.Maui, Sentry.Serilog, Sentry.OpenTelemetry, ~25 packages under src/) built with the .NET SDK pinned in global.json. It spans .NET Framework through the latest .NET, plus Android, iOS and Mac Catalyst via bindings over the native Sentry SDKs — see Platform Targets for the target frameworks and per-platform toolchain requirements. Check out the submodules first. The native SDKs and several build/tooling projects live in git submodules under modules/ (e.g. sentry-native, sentry-cocoa, perfview).…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- sdk-reviewSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
20 rules. About 0 are common, 5 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 19
If you only need to sync submodules (e.g.
- Very specific: line 36
Use solution filters instead of the full Sentry.slnx:
- Very specific: line 118
Never commit auth tokens, API keys or credentials.
- Very specific: line 159
Use SentryNoMobile.slnf — no extra toolchain needed.
- Very specific: line 187
Test project naming: <SourceProjectName>.Tests (e.g.
- Very specific: line 188
Test naming convention: Method_Context_Expectation (e.g., CaptureEvent_ActiveScope_AppliesScopeData)
- Distinctive: line 204
Run tests locally — they will fail with a diff
- Very specific: line 206
Commit the updated *.verified.* snapshot files
- Very specific: line 214
Never
git add -A: After merging main, the recorded submodule pointers move but the working copies under modules/ do not until you run git … - Very specific: line 249
Do NOT add entries manually.
- Very specific: line 284
Do not add comments that restate what the code already says.
- Distinctive: line 322
When a sample changes, update its comments rather than dropping them.
- Very specific: line 328
When adding a configurable property to any of the classes descending from SentryOptions:
- Very specific: line 330
Add the property to SentryOptions as normal.
- Very specific: line 331
Add a matching nullable property to BindableSentryOptions.
- Very specific: line 332
Add a line in BindableSentryOptions.ApplyTo: options.MyProp = MyProp ??
- Very specific: line 333
Run the relevant bindable options test (e.g., BindableSentryOptionsTests) — the BindableProperties_MatchOptionsProperties test will fail if …
- Distinctive: line 339
Prefer LSP over Grep/Read for code navigation — it's faster, precise, and avoids reading entire files:
- Distinctive: line 345
Use Grep only when LSP isn't available or for text/pattern searches (comments, strings, config).
- Distinctive: line 347
After writing or editing code, check LSP diagnostics and fix errors before proceeding.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Instructions
The Sentry SDK for .NET: a multi-package repo (Sentry, Sentry.AspNetCore, Sentry.Maui,
Sentry.Serilog, Sentry.OpenTelemetry, ~25 packages under src/) built with the .NET SDK
pinned in global.json. It spans .NET Framework through the latest .NET, plus Android, iOS
and Mac Catalyst via bindings over the native Sentry SDKs — see Platform Targets
for the target frameworks and per-platform toolchain requirements.
Getting Started
Check out the submodules first. The native SDKs and several build/tooling projects live in git submodules under modules/ (e.g. sentry-native, sentry-cocoa, perfview). Without them, builds, solution-filter generation, and other tooling break in confusing ways — e.g. scripts/generate-solution-filters.ps1 silently drops the missing projects from the *.slnf files.
The bootstrap step handles this for you (it runs git submodule update --init --recursive plus a full restore):
./dev.cs cleanslateIf you only need to sync submodules (e.g. in a fresh worktree), run ./dev.cs subup or git submodule update --init --recursive directly.
Build System
Uses the .NET SDK (dotnet CLI). Key files:
Sentry.slnx— full solution (all platforms/samples)... rarely used directlyglobal.json— pins .NET SDK and Workload versionsDirectory.Build.props/Directory.Build.targets— shared MSBuild properties across all projects
MSBuild hierarchical structure
MSBuild searches upward from each project file and uses the nearest Directory.Build.props/.targets it finds. Parent files are not automatically included. props/targets files in this repo explicitly <Import> parent/root files when appropriate.
integration-test/Directory.Build.props / integration-test/Directory.Build.targets are intentionally isolated (do not import root).
Solution Filters
Use solution filters instead of the full Sentry.slnx:
| Filter | Use when |
SentryNoMobile.slnf | General development (no Android/iOS build toolchain needed for quicker builds) |
Sentry-CI-Build-macOS.slnf | All macOS projects except the app samples |
Sentry-CI-Build-Windows.slnf | All Windows projects except the app samples |
Sentry-CI-Build-Linux.slnf | All Linux projects except the app samples |
Sentry-CI-Build-Samples-macOS.slnf | The MAUI, Android, iOS, Mac Catalyst and macOS sample apps |
Sentry-CI-Build-Samples-Linux.slnf | The MAUI and Android sample apps, built on Linux |
Sentry-CI-IntegrationTest-macOS.slnf | The packages the integration tests use, on macOS |
Sentry-CI-IntegrationTest.slnf | The packages the integration tests use, on Linux and Windows |
Do not edit
*.slnffiles directly. They are generated byscripts/generate-solution-filters.ps1fromscripts/generate-solution-filters-config.yaml.
Essential Commands
# Full build (operating system specific - run one only)
dotnet build Sentry-CI-Build-macOS.slnf
# Quick build (no mobile targets)
dotnet build SentryNoMobile.slnf
# Build a specific project
dotnet build src/Sentry/Sentry.csproj
# Run all tests
dotnet test Sentry-CI-Build-macOS.slnf
# Run all tests (non-mobile)
dotnet test SentryNoMobile.slnf
# Run tests for a specific project
dotnet test test/Sentry.Tests/Sentry.Tests.csproj
# Run a single test by name
dotnet test test/Sentry.Tests/ --filter "FullyQualifiedName~CaptureEvent_"
# Run android device tests (Android emulator must be running)
pwsh scripts/device-test.ps1 android
# Run ios device tests (iOS simulator must be running)
pwsh scripts/device-test.ps1 ios
# Format code
dotnet format Sentry.slnx --no-restore --exclude ./modules --exclude ./**/*OptionsSetup.cs --exclude ./test/Sentry.Tests/AttributeReaderTests.csBefore you're done
A change isn't finished until these are clean:
dotnet build Sentry-CI-Build-macOS.slnf # or the .slnf matching your OS
dotnet test Sentry-CI-Build-macOS.slnf
dotnet format Sentry.slnx --no-restore --exclude ./modules --exclude ./**/*OptionsSetup.cs --exclude ./test/Sentry.Tests/AttributeReaderTests.cs
git status # see the note belowgit status matters because the API-approval tests call Verify's AutoVerify
(test/Sentry.Testing/ApiExtensions.cs): a local test run silently rewrites the
*.verified.txt snapshots and still reports green. Check for snapshot churn after any run that
touches public API, and commit it deliberately.
For a full Release-mode build and test — what CI runs — use ./build.sh (./build.cmd on
Windows).
Boundaries
🚫 Never edit these — generated, vendored, or guarded by CI
| Path | Instead |
*.slnf | Edit scripts/generate-solution-filters-config.yaml, then run scripts/generate-solution-filters.ps1 |
CHANGELOG.md | Generated on squash-merge from the PR title. .github/workflows/changelog-guard.yml fails CI on manual entries |
src/Sentry.Bindings.Cocoa/ApiDefinition.cs, StructsAndEnums.cs | Edit scripts/patch-cocoa-bindings.cs, then run scripts/generate-cocoa-bindings.ps1 |
modules/** | Git submodules pointing at other repositories — change them upstream, never in place |
*.verified.* | Run the tests, then pwsh ./scripts/accept-verifier-changes.ps1 |
🚫 Never commit secrets
Never commit auth tokens, API keys or credentials. The DSNs checked into samples/ point at
Sentry's own demo projects — don't swap in one from a real project.
⚠️ Ask first
- Breaking or removing public API (see Key Conventions)
- Adding a package dependency — the SDK deliberately keeps its dependency surface minimal
- Changing anything under
.github/workflows/
Repository Layout
src/ # Source for all Sentry packages
test/ # Test projects (mirror src/ naming: Sentry.X.Tests)
samples/ # Sample applications
benchmarks/ # Performance benchmarks
integration-test/ # Pester-based integration tests (CLI, AOT, runtime, etc.)
modules/ # Native SDK submodules (sentry-native, Ben.Demystifier, etc.)
scripts/ # Build and maintenance scriptsUpgrading to a new .NET major version
Taking a dependency on a new .NET preview breaks the same handful of things every year -
package/version pinning, container base images, per-TFM ItemGroups, platform minimums, CI
runner setup, Xcode pinning and Verify snapshots. Read
CONTRIBUTING.md -> Upgrading to a new .NET major version
before starting one, and extend it with anything new you hit.
Two things worth knowing up front, because they cost the most time when missed:
dotnet pack and the integration tests catch most of it and a solution-filter build does not,
and the local checks must be run serially.
- Build samples locally with
GITHUB_ACTIONS=true. Without CI'sCI_BUILDdefine they stop at the DSN#errorinsamples/SamplesShared.cs, so later steps such as ILLink never run. - To tell a new-SDK regression from an existing failure, rebuild just the failing project and TFM
with the previous
global.json.
Platform Targets
Non-mobile (Linux / macOS / Windows)
- Use
SentryNoMobile.slnf— no extra toolchain needed. - Targets:
net10.0,net11.0,netstandard2.0,netstandard2.1,net462.
Android
- Requires
JAVA_HOMEset and Java installed. - Built on all platforms (Linux, macOS, Windows).
Sentry.Bindings.Androidwraps the native Android SDK.
iOS / Mac Catalyst
- macOS only. Requires Xcode.
Sentry.Bindings.Cocoawraps the native Cocoa SDK.- Device tests run in CI only.
src/Sentry.Bindings.Cocoa/ApiDefinition.csandStructsAndEnums.csare auto-generated — do not edit them directly. All changes must go inscripts/patch-cocoa-bindings.csand be applied by runningscripts/generate-cocoa-bindings.ps1.
MAUI
- Requires MAUI workloads:
sudo dotnet workload restore(macOS/Linux) ordotnet workload restore(Windows). - Combine mobile toolchain requirements above.
Blazor WASM
Sentry.AspNetCore.Blazor.WebAssembly.PlaywrightTestsuses Playwright — seeplaywright-blazor-wasm.ymlfor CI setup.
Alpine / musl
- Separate CI pipeline (
alpine.yml). Do not attempt Alpine-specific builds outside that environment.
Testing Conventions
- Framework: xUnit
- Mocking: nsubstitute
- Test project naming:
<SourceProjectName>.Tests(e.g.Sentry.AspNetCore.Tests) - Test naming convention:
Method_Context_Expectation(e.g.,CaptureEvent_ActiveScope_AppliesScopeData) - Snapshot tests use Verify — commit updated
*.verified.*files when API surface changes - Device tests (
Sentry.Maui.Device.TestApp,AndroidTestApp); requires a connected emulator to run locally - Integration tests in
integration-test/use Pester (PowerShell) — require a local nuget pack or CI-built packages
Accepting Verify snapshot changes
dotnet test
pwsh ./scripts/accept-verifier-changes.ps1
# Repeat if needed — dotnet test stops after N failuresAPI Changes
Public API diffs are stored as Verify snapshot files. After any public API change:
- Run tests locally — they will fail with a diff
- Accept the diff:
pwsh ./scripts/accept-verifier-changes.ps1 - Commit the updated
*.verified.*snapshot files
Git Workflow
- Branch off
main. Open the PR as a draft while you work on it, and mark it ready once CI is green and tests are in place. - Link the issue with a plain auto-close keyword on its own line in the PR body —
Closes #1234, not inline code and not a bare URL — so GitHub registers the link. - Never
git add -A. After mergingmain, the recorded submodule pointers move but the working copies undermodules/do not until you rungit submodule update --init --recursive.git add -Athen stages the stale copies and silently reverts a submodule pointer inside a commit that has nothing to do with submodules. Stage explicit paths instead, and check the full delta before pushing:
git diff origin/main...HEAD --stat # should list only files you meant to touchPR titles are changelog entries
The PR title becomes the squash-merge commit message and, from there, the changelog line. It must be a conventional commit that stands on its own as a release note:
feat: allow users to control Mechanism.Handled for captured exceptions
fix(serilog): logs from application namespaces beginning with "Sentry" are discarded
chore(deps): update Native SDK to v0.16.3The prefix selects the CHANGELOG section (defined in .github/release.yml):
| Prefix | Section |
feat: | Features ✨ |
fix: / bugfix: | Fixes 🐛 |
chore(deps): | Dependencies ⬆️ |
any type with !, e.g. feat!: | Breaking Changes 🛠 |
anything else (ci:, docs:, deps:, meta:, …) | Other |
Changelog
CHANGELOG.md is generated — see Boundaries.
Do NOT add entries manually. For a change that isn't user-facing, put #skip-changelog in
the PR description or add the skip-changelog label.
# Get PR number for current branch
gh pr view --json number -q '.number'Commit Attribution
AI commits MUST include:
Co-Authored-By: <Agent Name> <agent-email-or-noreply@example.com>Key Conventions
- New features must be opt-in — extend
SentryOptionsor relevant options class with getters/setters - Maintain backwards compatibility — avoid breaking public API without strong justification
- Platform-specific code lives in
src/Sentry/Platforms/and is conditionally compiled
Code Style
.editorconfig is authoritative for formatting and analyzer severity. dotnet format (see
Essential Commands) enforces it — run it before pushing rather than
hand-formatting.
Prefer no comments
This repository favours clean, readable code that needs no comments at all. Reach for a better name or a smaller method before reaching for a comment. Where something genuinely isn't obvious — a non-intuitive framework behaviour, a workaround for an upstream bug — a minimal comment is fine, but the code and the PR description are the documentation.
Do not add comments that restate what the code already says. In particular, don't annotate
members as being exposed for tests (// Exposed for tests) — that's already apparent from
the member being internal and from tests being its only callers.
❌ Comments that restate the code, or explain a member's visibility:
// Exposed for tests
internal bool HasFlushed { get; private set; }
// Loop through the envelope items and send each one
foreach (var item in envelope.Items)
{
await SendItemAsync(item, cancellationToken).ConfigureAwait(false);
}✅ Names carry the meaning; a comment earns its place only where the code can't speak:
internal bool HasFlushed { get; private set; }
foreach (var item in envelope.Items)
{
await SendItemAsync(item, cancellationToken).ConfigureAwait(false);
}
// Method info is currently only exposed by ToString(), see https://github.com/dotnet/runtime/issues/92869
internal static SentryStackFrame ParseNativeAOTToString(string info)(that last one is real, from src/Sentry/Internal/DebugStackTrace.cs — it records an upstream
runtime limitation the code itself can't convey.)
This applies to the library, not to samples/. Samples are documentation: people read them
to learn how to wire Sentry up, and copy them as a starting point. Comment them concisely but clearly,
including the configuration files — appsettings.json and the like carry // comments in this
repo even though JSON doesn't officially support them, and that has never caused a problem.
When a sample changes, update its comments rather than dropping them.
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:
- Add the property to
SentryOptionsas normal. - Add a matching nullable property to
BindableSentryOptions. Use only simple/primitive types the source generator can handle. For complex types (e.g.,IReadOnlyList<StringOrRegex>), use a simpler surrogate (e.g.,List<string>?) and convert inApplyTo. - Add a line in
BindableSentryOptions.ApplyTo:options.MyProp = MyProp ?? options.MyProp; - Run the relevant bindable options test (e.g.,
BindableSentryOptionsTests) — theBindableProperties_MatchOptionsPropertiestest 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/.
Code Intelligence
Prefer LSP over Grep/Read for code navigation — it's faster, precise, and avoids reading entire files:
workspaceSymbolto find where something is definedfindReferencesto see all usages across the codebasegoToDefinition/goToImplementationto jump to source
Use Grep only when LSP isn't available or for text/pattern searches (comments, strings, config).
After writing or editing code, check LSP diagnostics and fix errors before proceeding.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

