agentleFS
SentryKnown publishergetsentry/sentry-dotnet/AGENTS.md

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.

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
  1. Very specific:

    If you only need to sync submodules (e.g.

    line 19
  2. Very specific:

    Use solution filters instead of the full Sentry.slnx:

    line 36
  3. Very specific:

    Never commit auth tokens, API keys or credentials.

    line 118
  4. Very specific:

    Use SentryNoMobile.slnf — no extra toolchain needed.

    line 159
  5. Very specific:

    Test project naming: <SourceProjectName>.Tests (e.g.

    line 187
  6. Very specific:

    Test naming convention: Method_Context_Expectation (e.g., CaptureEvent_ActiveScope_AppliesScopeData)

    line 188
  7. Distinctive:

    Run tests locally — they will fail with a diff

    line 204
  8. Very specific:

    Commit the updated *.verified.* snapshot files

    line 206
  9. Very specific:

    Never git add -A: After merging main, the recorded submodule pointers move but the working copies under modules/ do not until you run git …

    line 214
  10. Very specific:

    Do NOT add entries manually.

    line 249
  11. Very specific:

    Do not add comments that restate what the code already says.

    line 284
  12. Distinctive:

    When a sample changes, update its comments rather than dropping them.

    line 322
  13. Very specific:

    When adding a configurable property to any of the classes descending from SentryOptions:

    line 328
  14. Very specific:

    Add the property to SentryOptions as normal.

    line 330
  15. Very specific:

    Add a matching nullable property to BindableSentryOptions.

    line 331
  16. Very specific:

    Add a line in BindableSentryOptions.ApplyTo: options.MyProp = MyProp ??

    line 332
  17. Very specific:

    Run the relevant bindable options test (e.g., BindableSentryOptionsTests) — the BindableProperties_MatchOptionsProperties test will fail if …

    line 333
  18. Distinctive:

    Prefer LSP over Grep/Read for code navigation — it's faster, precise, and avoids reading entire files:

    line 339
  19. Distinctive:

    Use Grep only when LSP isn't available or for text/pattern searches (comments, strings, config).

    line 345
  20. Distinctive:

    After writing or editing code, check LSP diagnostics and fix errors before proceeding.

    line 347

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 cleanslate

If 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 directly
  • global.json — pins .NET SDK and Workload versions
  • Directory.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:

FilterUse when
SentryNoMobile.slnfGeneral development (no Android/iOS build toolchain needed for quicker builds)
Sentry-CI-Build-macOS.slnfAll macOS projects except the app samples
Sentry-CI-Build-Windows.slnfAll Windows projects except the app samples
Sentry-CI-Build-Linux.slnfAll Linux projects except the app samples
Sentry-CI-Build-Samples-macOS.slnfThe MAUI, Android, iOS, Mac Catalyst and macOS sample apps
Sentry-CI-Build-Samples-Linux.slnfThe MAUI and Android sample apps, built on Linux
Sentry-CI-IntegrationTest-macOS.slnfThe packages the integration tests use, on macOS
Sentry-CI-IntegrationTest.slnfThe packages the integration tests use, on Linux and Windows

Do not edit *.slnf files directly. They are generated by scripts/generate-solution-filters.ps1 from scripts/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.cs

Before 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 below

git 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

PathInstead
*.slnfEdit scripts/generate-solution-filters-config.yaml, then run scripts/generate-solution-filters.ps1
CHANGELOG.mdGenerated on squash-merge from the PR title. .github/workflows/changelog-guard.yml fails CI on manual entries
src/Sentry.Bindings.Cocoa/ApiDefinition.cs, StructsAndEnums.csEdit 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 scripts

Upgrading 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's CI_BUILD define they stop at the DSN #error in samples/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_HOME set and Java installed.
  • Built on all platforms (Linux, macOS, Windows).
  • Sentry.Bindings.Android wraps the native Android SDK.

iOS / Mac Catalyst

  • macOS only. Requires Xcode.
  • Sentry.Bindings.Cocoa wraps the native Cocoa SDK.
  • Device tests run in CI only.
  • src/Sentry.Bindings.Cocoa/ApiDefinition.cs and StructsAndEnums.cs are auto-generated — do not edit them directly. All changes must go in scripts/patch-cocoa-bindings.cs and be applied by running scripts/generate-cocoa-bindings.ps1.

MAUI

  • Requires MAUI workloads: sudo dotnet workload restore (macOS/Linux) or dotnet workload restore (Windows).
  • Combine mobile toolchain requirements above.

Blazor WASM

  • Sentry.AspNetCore.Blazor.WebAssembly.PlaywrightTests uses Playwright — see playwright-blazor-wasm.yml for 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 failures

API Changes

Public API diffs are stored as Verify snapshot files. After any public API change:

  1. Run tests locally — they will fail with a diff
  2. Accept the diff: pwsh ./scripts/accept-verifier-changes.ps1
  3. 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 merging main, the recorded submodule pointers move but the working copies under modules/ do not until you run git submodule update --init --recursive. git add -A then 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 touch

PR 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.3

The prefix selects the CHANGELOG section (defined in .github/release.yml):

PrefixSection
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 SentryOptions or 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:

  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<StringOrRegex>), use a simpler surrogate (e.g., List<string>?) 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/.

Code Intelligence

Prefer LSP over Grep/Read for code navigation — it's faster, precise, and avoids reading entire files:

  • workspaceSymbol to find where something is defined
  • findReferences to see all usages across the codebase
  • goToDefinition / goToImplementation to 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.