orleans

## Build, test, and style commands

* The repo builds with the .NET SDK from `global.json` (`10.0.400`, roll-forward `major`). Do not edit `global.json` unless explicitly asked.
* Build the solution with `dotnet build Orleans.slnx -bl`. CI uses this form and uploads the binlog.
* On Windows, `.\Build.cmd` runs `build.ps1`, which restores, builds, and packs `Orleans.slnx`, writes restore/build/pack binlogs, and outputs packages under `Artifacts\<Configuration>`. Set `BuildConfiguration=Release` to build release artifacts.
* Run tests with `dotnet test --solution Orleans.slnx --framework net10.0 --minimum-expected-tests 1 --max-parallel-test-modules 1`. CI also runs `net8.0`; source projects default to `net8.0;net10.0`.
* Run a category with `dotnet test --solution Orleans.slnx --framework net10.0 --filter-trait "Category=BVT" --minimum-expected-tests 1 --max-parallel-test-modules 1`. Common categories are `BVT`, `SlowBVT`, `Functional`, and provider-specific categories such as `Redis`, `Cassandra`, `SqlServer`, `Azure`, `AWS`, and `Streaming`.
* Run one test with `dotnet test --project test\Orleans.Core.Tests\Orleans.Core.Tests.csproj --framework net10.0 --filter-class "*MyTestClass*" --filter-method "*MyTestMethod*" --minimum-expected-tests 1`.
* `.\Test.cmd` runs the scripted Windows test subset using the default xUnit query filter `/[(Category=BVT)|(Category=SlowBVT)]`. `.\TestAll.cmd` adds the `Functional` category.
* Provider tests often need external services, connection-string environment variables, or secrets. Match `.github\workflows\ci.yml` and `test\TestInfrastructure\TestExtensions\TestDefaultConfiguration.cs` for the required setup.
* Style is enforced by `dotnet build` because `Directory.Build.props` sets `EnforceCodeStyleInBuild=true` and `TreatWarningsAsErrors=true`.

## High-level architecture

* Orleans is a virtual actor framework. User code defines grain interfaces (`IGrainWithStringKey`, `IGrainWithGuidKey`, etc.) and grain classes; the runtime activates, places, deactivates, persists, and routes calls to grains across silos.
* `src\Orleans.Core.Abstractions` contains the public programming model: grain interfaces, grain references, attributes, and shared abstractions used by both clients and silos.
* `src\Orleans.Serialization.Abstractions` and `src\Orleans.Serialization` provide the version-tolerant serializer, serialization attributes, runtime serialization services, and source-generator integration. Additional serializer packages live under `src\Orleans.Serialization.*` and `src\Serializers`.
* `src\Orleans.Core` contains shared client/server runtime infrastructure such as messaging, hosting integration, configuration, and serialization integration.
* `src\Orleans.Runtime` is the silo implementation: activation lifecycle, placement, cluster membership, reminders, runtime services, and grain execution.
* `src\Orleans.Sdk`, `src\Orleans.Client`, and `src\Orleans.Server` are packaging/metapackage projects. The SDK brings in core packages plus analyzers/code generation; the client/server packages compose the SDK with client or silo dependencies.
* Provider packages are intentionally split by backend and capability under `src\Azure`, `src\AWS`, `src\AdoNet`, `src\Cassandra`, `src\Redis`, and related top-level provider directories. They usually expose builder extensions in `Orleans.Hosting` and options in `Orleans.Configuration`.
* Tests mirror runtime areas under `test\`. Shared test infrastructure is in `test\TestInfrastructure\TestExtensions`, test grains and grain interfaces are under `test\Grains`, and `Orleans.TestingHost`/`TestClusterBuilder` are the primary integration-test harnesses.
* `src\api` contains generated public API surface files for packable projects. Do not edit these files manually. Regenerate an affected project by restoring with `dotnet restore <project> --configfile .github/NuGet.GenAPI.Config -p:GenerateOrleansApiSource=true`, then running `dotnet build <project> --framework net8.0 --configuration Release --no-incremental --no-restore -p:GenerateOrleansApiSource=true /t:"Build;GenAPIGenerateReferenceAssemblySource"`, matching `.github\workflows\generate-api-diffs.yml`.

## Key conventions

* Central package management is enabled in `Directory.Packages.props`; add or update package versions there instead of putting versions in individual projects.
* Use project references for repo-internal dependencies. `CONTRIBUTING.md` explicitly discourages DLL references and unnecessary `Private=True` metadata.
* `src\Directory.Build.props` makes source projects packable by default; `test\Directory.Build.props` makes test projects non-packable and configures MTP test applications. The root `Directory.Build.targets` copies `test\testconfig.json` under each test assembly name.
* Build-time code generation is controlled by `OrleansBuildTimeCodeGen=true`, which imports the Orleans code generator and analyzers as build analyzers for framework projects.
* Serializable Orleans types that cross grain calls, storage, or streams generally need `[GenerateSerializer]` plus stable `[Id(n)]` members. Do not renumber existing serialization IDs.
* Public API changes in packable `src\` projects usually require corresponding generated API-surface changes under `src\api`; always regenerate them with the GenAPI target instead of editing them by hand.
* Tests use xUnit with the custom `[TestCategory("...")]` attribute from `test\TestInfrastructure\TestExtensions\TestCategory.cs`; this maps categories to xUnit traits for `dotnet test --filter-trait "Category=..."`.
* Cluster tests usually derive from or compose fixtures in `test\TestInfrastructure\TestExtensions` and configure silos through `TestClusterBuilder`, `ISiloConfigurator`, or `ISiloBuilder`. The default cluster fixture uses in-memory reminders, durable jobs, and grain storage.
* Follow `.editorconfig`: C# uses file-scoped namespaces, system directives first, `var` preferences, braces on new lines, `_camelCase` private fields, and preview language features. Nullable is enabled for source projects and disabled for test projects.
* Add XML docs for new or changed public APIs even though CS1591 is currently suppressed; package projects generate documentation files.
* PR workflow from `AGENTS.md`: open PRs against `dotnet/orleans`, push feature branches to the `origin` fork, and create PRs with `gh pr create --repo dotnet/orleans --base main --head ReubenBond:<branch>`.

More agent context in dotnet/orleans

4 other files this repository gives its agents.