anthropic-sdk-csharp

# Working in this repository

Context for contributors (human or AI) on how this SDK is put together, plus the things reviews most often come back to. Setup instructions live in [CONTRIBUTING.md](CONTRIBUTING.md).

## Overview

- The official C#/.NET SDK for the Claude API. Much of it is generated from the OpenAPI spec, with hand-written helpers, adapters, credentials, and platform clients layered on top.
- Generated files are safe to edit. New generator output is git-merged with custom changes rather than overwriting them, so fix things where they live; a collision is just a merge conflict.
- Bugs that originate upstream are worth flagging as such even when a local patch lands first: a real API response the SDK's generated types can't deserialize or validate (a missing "required" field, an unknown enum member, a nullability mismatch) points at the OpenAPI spec, and broken generated infrastructure (retries, SSE parsing, serialization, disposal) points at the generator — fixing it there fixes every SDK.
- PRs target the default branch (`main` on the public repo). `next` belongs to release automation — don't open PRs against it or push to it; a commit that lands there outside the release flow breaks the sync. Rebase onto the current default branch before asking for review — a stale base shows up as dozens of unrelated "changed" files.
- Package versions (`VersionPrefix`, `.release-please-manifest.json`) and the per-package `src/*/CHANGELOG.md` files are written by release automation. What gets built, packed, and published is whatever is in the root `Anthropic.sln`; a new package additionally needs entries in `release-please-config.json` and the manifest, plus a line in the hand-maintained root `CHANGELOG.md` index.

## Build, test, lint

- The entry points are `./scripts/{bootstrap,build,test,format,lint}` (see CONTRIBUTING.md); `build` compiles `Anthropic.sln` and `examples/Anthropic.Examples.sln`. Run `format` and `lint` before pushing changes to C# or project files.
- Lint is `dotnet csharpier check .` (pinned version, via `dotnet tool restore`) plus `dotnet format style`/`analyzers` at info severity, so even IDE/CA suggestions fail it; CI, not a local run, is the source of truth. Prefer fixing a finding over suppressing it, and comment any suppression that's genuinely needed.
- `.cs` files use CRLF line endings (`.editorconfig`); csharpier flags LF files, which occasionally arrive via codegen, and `./scripts/format` fixes them.
- IDE churn (`.sln` header rewrites, added `this.` qualifiers, editor-specific `.gitignore` entries, whitespace-only diffs) is best reverted before committing.
- Warnings are errors and nullable reference types are on throughout `src/`. Other settings (target frameworks, `LangVersion`, `ImplicitUsings`) come from `src/Directory.Build.props` and several projects override them — `ImplicitUsings`, for instance, is off in `Anthropic` but on in most platform packages and the examples — so follow the project you're in rather than assuming.
- The libraries multi-target modern .NET plus `netstandard2.0`, so build with an SDK at least as new as the newest target framework. Tests run on .NET and on `net472`; the `net472` run is what exercises the `netstandard2.0` build (on Windows in CI), so both sides of a `#if` get tested somewhere.
- `./scripts/test` starts a Node-based mock API server first (`./scripts/mock`, port 4010, or point `TEST_API_BASE_URL` elsewhere). Only the generated `Services` tests and their `*MultiClientTest` wrappers talk to it; everything else, including the generated `Models` tests, runs without it. Live tests against real cloud providers only run with `ANTHROPIC_LIVE=1`.
- CI's `./scripts/detect-breaking-changes` compiles `main`'s generated `Services`/`Models` tests against your branch. It only sees the generated API surface, so a break in hand-written public API (helpers, adapters, credentials, platform clients) has to be called out by the author; and if the job fails the same way on the base branch without your changes, it's pre-existing drift awaiting release rather than something the PR did.
- Example projects target `net8.0`, should read credentials from the environment, and need adding to `examples/Anthropic.Examples.sln`: `./scripts/build` compiles the examples through that solution, and `./scripts/lint` fails if a project under `examples/` is missing from it. New user-facing helpers usually come with an example; user documentation lives outside this repo (see CONTRIBUTING.md), so note in the PR what needs documenting.

## Multi-targeting

- `#if NET` / `#if !NET` is the convention for TFM splits, wrapped around just the fragment that differs. The `*_OR_GREATER` symbols are easy to misjudge, so check which targets define a symbol before relying on one.
- Behaviour should be the same on every target. When an API is missing on netstandard2.0, use an equivalent that exists everywhere or add an internal shim (`src/Anthropic/Shims.cs`, `src/Anthropic/Core/HttpContentExtensions.cs`, `src/Anthropic.Bedrock/LocalShims.cs`) rather than compiling the behaviour out on one target — a guard around the missing `HttpStatusCode.TooManyRequests` once silently disabled 429 retries for every netstandard2.0 consumer, where `(HttpStatusCode)429` would have kept them.
- Polyfilled attribute/compiler types stay `internal` (public copies collide with consumers' own polyfills), and types that ship as netstandard2.0 packages (`System.Collections.Immutable`, `System.Threading.Tasks.Extensions`) are referenced rather than polyfilled. `required`, `init`, `[NotNullWhen]` and friends compile on netstandard2.0 through `Shims.cs`, which the other packages pick up by compile-linking the file — a project that doesn't link it doesn't have them.

## Code organization

- `Anthropic.Helpers` (with public sub-namespaces such as `Anthropic.Helpers.Beta` for the tool runner) is the curated helper surface users import, so new internal plumbing shouldn't be added directly to it. Cross-cutting internals go in `Anthropic.Core` (namespace and `src/Anthropic/Core/` directory; `JsonNodes`, `LazySseBody`, `StreamedToolInput` are precedents), and internals serving one feature go in an internal sub-folder/sub-namespace next to it (`Helpers/Fallbacks/*`).
- Public types placed in a namespace the SDK doesn't own (in practice `Microsoft.Extensions.AI`, MEAI) carry an `Anthropic` prefix so they can't collide with types the namespace owner adds later; `NamingConventionTest` enforces this, with `AIContentCacheExtensions` exempt because it predates the convention.
- The `Beta` prefix mirrors the API split: `client.Beta.*` services and the `Anthropic.Models.Beta.*` namespaces are the beta surface, and public helpers over beta-only types are named `Beta*`.
- A lot of hand-written logic exists twice, stable and beta (`AnthropicClientExtensions`/`AnthropicBetaClientExtensions`, `MessageContentAggregator`/`BetaMessageContentAggregator`, …), and the platform packages duplicate plumbing too (Bedrock and Vertex request validation and URL rewriting; SigV4 signing in both `Anthropic.Aws` and `Anthropic.Bedrock`). A fix usually needs applying to every copy. Sharing the *logic* through an internal helper, as `StreamedToolInput` does for the aggregators, beats maintaining parallel copies — but the stable and beta public API types themselves stay separate (no shared base types or unified models), so the two surfaces can evolve independently.
- For anything cross-SDK (environment variable and option names, header semantics, credential precedence, client-side policies like the non-streaming `max_tokens`/timeout guard, helper shapes such as aggregation returning the non-streaming `Message` type), matching the other SDKs is the default.

## Exceptions

- Everything the SDK throws on its own behalf derives from `AnthropicException` (`Anthropic.Exceptions`), so callers can catch the family in one clause:
  - `AnthropicServiceException` — the service reported an error; carries the parsed `ErrorType` (`InvalidRequestError`, `RateLimitError`, `OverloadedError`, …) when the body names one. `AnthropicApiException` is its non-2xx form, adding `StatusCode` and `ResponseBody`, and `AnthropicExceptionFactory` picks the concrete subclass by status (`AnthropicBadRequestException`, `AnthropicUnauthorizedException`, `AnthropicForbiddenException`, `AnthropicNotFoundException`, `AnthropicUnprocessableEntityException`, `AnthropicRateLimitException`, otherwise `Anthropic4xxException`/`Anthropic5xxException`, otherwise `AnthropicUnexpectedStatusCodeException`); `AnthropicSseException` is an `error` event arriving inside an otherwise successful stream.
  - `AnthropicIOException` — a transport failure wrapping the `HttpRequestException`; the client counts it as retryable.
  - `AnthropicInvalidDataException` — data that doesn't fit the models: JSON that won't deserialize, a failed `Validate()`, an absent required field, a wire shape a helper can't interpret. This is the type hand-written code throws most.
  - Plain `AnthropicException` with an actionable message for client-side configuration problems (a platform client that can't resolve a region, workspace, or credentials), and feature-specific subclasses such as `WorkloadIdentityException` where a family of failures deserves its own type.
- Deliberately outside that family: argument errors at public entry points are `ArgumentNullException`/`ArgumentException`; operations a platform client can't offer throw `NotSupportedException`; cancellation and client-side timeouts surface as `OperationCanceledException`/`TaskCanceledException`; and `BetaToolError` isn't a failure but the signal a tool implementation throws so the tool runner returns `is_error: true` content to the model.
- New code reuses these rather than adding types or throwing BCL exceptions for SDK conditions, keeps the original exception as `InnerException`, and leaves HTTP-status mapping to `AnthropicExceptionFactory`.

## Common mistakes

- **Rewriting the request to make it "work".** Don't hoist, merge, reorder, or drop parts of a request the caller built. Map inputs as-is and let the API reject what it doesn't support, so the caller gets an actionable 400 instead of silently different semantics. (Protocol translation in the platform adaptation handlers — `model` into the URL, `anthropic_version`/`anthropic_beta` into the body — is mapping, not rewriting.)
- **Inferring capabilities from model IDs.** Don't branch on model-name lists or prefixes: they go stale on the next launch and don't match Bedrock/Vertex/Foundry spellings or custom deployment names. Use an explicit option, or just send the request. (The exact-match tables mirrored verbatim from the other SDKs — the thinking-enabled deprecation warning and the non-streaming token limits — are the accepted precedents.)
- **Throwing on data the SDK doesn't recognize.** API responses can contain enum values, block types, and fields this SDK version doesn't model. Enumerate the cases you handle and pass everything else through untouched — especially in streaming and middleware code, where an exception tears down the caller's response. Compare enums as `x.Value() == Enum.Member` or `x.Raw() == "wire_value"`, never through `ToString()` (it returns JSON, quotes included), and remember `Value()` is an undefined member for values the SDK doesn't know, which can't be re-serialized.
- **Losing wire data on the way back to the API.** Models are raw-JSON-backed (`RawData`, `FromRawUnchecked`); when relaying API output into a new request, carry the raw data across rather than rebuilding from typed properties, which drops fields such as `caller`.
- **Sending `null` where the property should be omitted.** Request models are immutable — build once and use `with` for conditional additions. `Prop = cond ? value : null` is harmless on most optional properties (a `null` assignment is simply ignored there) but a trap on the ones the spec marks nullable (`ContextManagement`, `CacheControl`, `Container`, …): for those the assigned `null` is sent as `"prop": null`, which the API may treat differently from an omitted property.
- **Streaming assumptions that don't hold.**
  - Not every block has deltas: some arrive complete in `content_block_start` (`redacted_thinking`, server-tool and MCP tool *results*, and new block types keep appearing), so default to passing whole blocks through.
  - `tool_use`, `server_tool_use`, and `mcp_tool_use` start with `input: {}` and stream the real JSON as `input_json_delta` fragments, which need folding back into the block and may be truncated when the stream stops early.
  - Per-block state is keyed and flushed by the event's `Index`, not "everything accumulated so far".
  - Cumulative usage fields on `message_delta` are nullable and shouldn't overwrite `message_start` values with null.
  - Some fields only arrive as deltas, not on the start block (a thinking `signature`, for example).
- **Clobbering headers.** `anthropic-beta` and the helper-telemetry header are comma-joined sets: append and de-duplicate rather than overwrite or emit a second header line (there is an existing merge helper in `Anthropic.Core`), and keep a single `User-Agent`. When a helper or adapter emits a feature that needs a beta flag, add it automatically, merged with the caller's `Betas`.
- **Leaking first-party credentials or dropping client options in platform clients.** The Bedrock, Vertex, Foundry, AWS, and Google Cloud clients null out the base client's environment-resolved `ApiKey`/`AuthToken` so those never reach a third-party host, keep scheme, host and port (`Uri.Authority`) when rewriting URLs, honour `ClientOptions` (timeout, retries, headers) rather than `HttpClient` defaults, and use the header/scheme casing the provider expects; a new platform client needs all four.
- **Disposing things the caller still needs, and other I/O slips.** Don't dispose (or `using`) a `CancellationTokenSource`, stream, or `HttpResponseMessage` that the returned object still depends on. Reads may return fewer bytes than requested, stay async, and take the caller's `CancellationToken`; library `await`s use `.ConfigureAwait(false)`; and the only console output is the existing user-facing warnings on `Console.Error`.
- **Unverified claims about the API.** Check doc comments, exception messages, and PR text that say "the API rejects X" or "model Y requires Z" against the official Claude API docs, not a third-party page or a bug report.

## Style notes

- Type safety comes first. Bypassing the type system — null-forgiving `!`, casting around the compiler, `object`/reflection, or manipulating raw JSON where typed models exist — is occasionally necessary but usually a sign something should be restructured: pattern-match once and pass the validated value on, and capture nullable values with a pattern instead of `?.` followed by `.Value`.
- Immutable things should actually be immutable. A mutable collection exposed through a read-only interface can be cast back, so wrap it (`ReadOnlyDictionary`, as `SseAggregator` does) or use the frozen collections the models use; don't hand out references that let callers mutate state presented as fixed.
- Public entry points guard reference arguments with `ArgumentNullException` (tests pin those); past that boundary, values the signature declares non-nullable don't need re-checking. Data that turns out absent or malformed at runtime (API payloads, raw JSON, URI segments) gets a descriptive `AnthropicInvalidDataException` (see Exceptions) rather than an NRE.
- Avoid `@`-escaped identifiers (`@event` → `events`/`streamEvent`).
- A small constructor plus `required init` properties reads better than a long positional parameter list; when you hold the concrete variant type, the implicit conversions on unions and enums make `new(...)` wrappers unnecessary.
- Keyed lookups come as a pair: `TryGetX` returning `null`/`false`, and `GetX` throwing `KeyNotFoundException` via the `Try` variant.
- `sealed` unless designed for inheritance; `internal` unless deliberately public (`Anthropic`, `Anthropic.Bedrock`, and `Anthropic.Mcp` grant the test project `InternalsVisibleTo`; add it to another project if you need it); `/// <inheritdoc/>` on overrides; XML docs using `<c>`/`<see>` rather than Markdown. Changing an existing public signature is a breaking change even where `detect-breaking-changes` can't see it; an added overload usually isn't.
- Explicit `StringComparison` (ordinal for protocol tokens); LINQ set operations over hand-rolled `Contains` loops; `static readonly` for shared immutable data.
- New siblings follow the existing shape: aggregators get a `CollectAsync` extension like `SseAggregatorExtensions`, MEAI passthroughs use `AdditionalProperties[nameof(Tool.X)]`, per-content options use `anthropic:`-prefixed keys like `WithCacheControl`, and MEAI values go through `AIJsonUtilities.DefaultOptions.GetTypeInfo(...)` rather than reflection-based serialization. "How do we already do this elsewhere?" is usually the first review question.
- Comments and XML docs are welcome where they explain something non-obvious (an invariant, a wire-format reason, a race, why a `#if` split or a suppression exists) and unnecessary where they restate what the code plainly does. Capitalized sentence style.

## Tests

- A behaviour change comes with a test that fails before and passes after; new internal classes get unit tests of their own rather than only end-to-end coverage.
- Hand-written tests are plain xunit classes (arrange / act / assert) and don't inherit `TestBase`, which is the base for the generated tests. `Xunit` is a global using; async SDK calls take `TestContext.Current.CancellationToken`.
- Generated `*ServiceTest` methods that have a `[Theory] + [AnthropicTestClients]` wrapper in a `*MultiClientTest` run against every client flavour and have their own `[Fact]` removed; the rest keep `[Fact]` and run once against the default client, and `[Fact(Skip = …)]` methods stay as they are (the mock can't serve those endpoints). Codegen re-adds `[Fact]` to regenerated methods, and `GeneratedTestConformanceTest` only prints a warning about that rather than failing, so re-strip them from wrapped services after a codegen update.
- MEAI adapter tests go in `AnthropicClientExtensionsTestsBase` so they run against both adapters; only flavour-specific cases live in the derived classes.
- Tests that mutate environment variables join `[Collection("EnvVarMutating")]` (defined with parallelization disabled), tests that redirect `Console.Error` share `[Collection("console stderr")]` so they don't interleave with each other, and both restore what they change.
- For request-shaping code, asserting on the exact wire request (body and headers) is what makes the test meaningful; fixtures shouldn't enshrine shapes the real API would reject. Headers captured from a real socket arrive comma-folded into one line.

## Commits and pull requests

- Conventional Commits drive release-please and the changelog (`feat(scope):`, `fix(scope):`, `chore`, `docs`, `refactor`, …).
- A `!` or `BREAKING CHANGE:` footer makes release-please cut a major version of `Anthropic` (a minor for the pre-1.0 platform packages). Major bumps are rare and a maintainer call — a small, technically-breaking change doesn't warrant one; describe the compatibility impact in the PR instead.
- One logical change per PR, against the current default branch, with formatting-only churn (line-ending fixes included) in its own commit; big mixed PRs tend to get sent back to be split.
- A good PR description says what was wrong (a short before/after helps), what changed, and what gives confidence — the failing-then-passing test plus any manual verification — and calls out behaviour changes and anything left unverified.