Packages
Canonical, grouped reference for every public Elarion .NET and npm package.
Elarion is split by capability and dependency boundary. Start with Elarion, then add only the providers
and adapters the host uses. Generator-only implementation projects are bundled by their public packages
and are intentionally absent from this list.
Core application model
These packages stay independent of ASP.NET Core, EF Core, and provider infrastructure.
| Package | Add it when |
|---|---|
Elarion.Abstractions | A contract-only assembly needs handlers (including request-driven IStreamHandler<,>), results, attributes, seams, canonical JSON, or generation triggers without runtime behavior. |
Elarion | An application assembly needs modules, handlers, decorators, scheduling, streams, buffering, current user, or source generation. This is the normal starting package and bundles Elarion.Generators. |
Elarion.Validation | DataAnnotations on requests must be enforced at runtime through Microsoft.Extensions.Validation. |
Elarion.Resilience | [Resilient] handlers or deferred scheduler retries need the Polly-backed default runner. |
Elarion.Caching | [Cacheable]/[CacheInvalidate] need the HybridCache-backed IHandlerCache. |
Elarion.Caching.PostgreSql | HybridCache needs the recommended PostgreSQL UNLOGGED L2 instead of a separate Redis service. |
Elarion.FeatureFlags.OpenFeature | [FeatureGate]/[FeatureVariant] should evaluate through a host-supplied OpenFeature provider. |
Elarion.FeatureFlags.FeatureManagement | Feature flags should come directly from configuration through Microsoft.FeatureManagement's OpenFeature provider. |
Hosting and handler transports
Protocols remain host-neutral where possible; ASP.NET packages own only their wire/host integration.
| Package | Add it when |
|---|---|
Elarion.JsonRpc | Handlers need the transport-neutral JSON-RPC dispatcher, MCP tool model, envelopes, telemetry, or schema export. |
Elarion.Grpc | A custom gRPC host needs typed unary or request-driven server-stream invocation, optional inline mapper delegates, one host-configured principal source, a correctly seeded dispatch scope, and stable startup AppError → RpcException translation without an ASP.NET dependency. |
Elarion.Grpc.AspNetCore | A grpc-dotnet ASP.NET Core host wants AddGrpc().AddElarion() plus ServerCallContext.InvokeElarionAsync/InvokeElarionStreamAsync, with HttpContext.User and RequestServices adopted automatically. This is the recommended gRPC host package. |
Elarion.AspNetCore | An ASP.NET host exposes JSON-RPC, [HttpEndpoint], files, ordered or request-driven SSE streams, current user middleware, or the role-holder proxy. |
Elarion.AspNetCore.OpenApi | [HttpEndpoint] routes should appear in OpenAPI with canonical schema and idempotency metadata. |
Elarion.AspNetCore.Mcp | Handlers should be exposed as an MCP server over Streamable HTTP. This is the only package referencing the MCP SDK. |
Elarion.AspNetCore.SchemaGeneration | An ASP.NET build should export rpc-schema.json for client generation. |
Elarion.AspNetCore.Identity | An ASP.NET host needs Identity registration, EF stores, ICurrentUser claims mapping, and the default authorizer. |
Elarion.AspNetCore.ProxyIdentity | The app sits behind an authenticating reverse proxy (Cloudflare Access, Google IAP, oauth2-proxy, an OIDC gateway) and must validate the token it forwards in a header or cookie, refuse to start unauthenticated, and run locally with a stand-in identity. See proxy identity. |
See transport capabilities and writing a custom transport.
Persistence, SQL, and transactions
Choose the EF Core tier or the NativeAOT SQL tier per host. EF applications keep authoring EF migrations but
run them through the one migration plan (Elarion.Migrations + a provider + Elarion.Migrations.EntityFrameworkCore);
an EF-free AOT host pairs Elarion.Sql with the database-neutral Elarion.Migrations engine and one provider package
that picks the database for both subsystems — Elarion.Sql.PostgreSql (AddElarionPostgreSql) or
Elarion.Sql.Sqlite (AddElarionSqlite). That single call registers one data source shared by the access
tier and migrations; the registrations that follow (AddElarionSqlUnitOfWork, AddElarionMigrations) name
no provider.
| Package | Add it when |
|---|---|
Elarion.EntityFrameworkCore | EF models need generated DbSets, entity configuration application, key conventions, keyset paging support, ambient tenant scoping ([GenerateElarionTenantScoping], ITenantScoped<T>), or the opt-in value-shape conventions (UseElarionEnumStringConversions, HasElarionJsonStringArray, ElarionValueComparers). Depends on Microsoft.EntityFrameworkCore (provider-neutral) for those conventions and on Elarion.Abstractions for the tenancy contracts. |
Elarion.EntityFrameworkCore.UnitOfWork | Handler transactions need the EF-backed IUnitOfWork, PostgreSQL lock timeout, and savepoints — and the transaction-scoped PostgreSQL row and advisory locks (LockRowAsync, AdvisoryLockAsync, TryAdvisoryLockAsync). |
Elarion.EntityFrameworkCore.LeasedWork | An application queue table (outbound deliveries, webhook dispatches, a durable retry table) needs workers on several instances to claim rows one at a time: the lease-guarded claim/finalize of ADR-0073, giving up exhausted rows at claim, eligibility-guarded finalizes, batch release on shutdown, projected claims, the partial claim index, and retry backoff helpers, without holding a row lock across the external call. Provider-neutral; brings Microsoft.EntityFrameworkCore.Relational. The outbox is built on it. |
Elarion.Paging | EF queries need keyset/offset execution, opaque cursors, or sort maps. ([ResourceFilter] and WhereAuthorized moved to Elarion.Abstractions, so data-level authorization no longer pulls this in.) |
Elarion.EntityFrameworkCore.BulkOperations | EF code needs provider-neutral streaming ExecuteInsertAsync and the bulk provider seam. |
Elarion.BulkOperations.PostgreSql | EF bulk inserts should use PostgreSQL binary COPY on the context connection. |
Elarion.Sql | An EF-free NativeAOT host needs generated row mappers and injection-safe SQL interpolation with no reflection fallback. Also supplies the EF-free IUnitOfWork — AddElarionSqlUnitOfWork() registers a scoped ISqlSession so handler transactions commit atomically without EF. Stays Npgsql-free; ISqlDatabase is the application's database handle (the DbContext/IDbContextFactory counterpart): the scoped session opens from it, and db.OpenSessionAsync() serves singleton-eligible handlers. |
Elarion.Sql.PostgreSql | The EF-free tier should run on PostgreSQL. The single AddElarionPostgreSql(connectionString) picks the provider for every subsystem: it registers one central NpgsqlDataSource (the shared core, EF Core's DbContext analogue), the provider the session opens from, and the PostgreSQL migration engine (session advisory lock, 1–10 nodes) behind the neutral AddElarionMigrations. Also ships UnpooledNpgsqlSession, a self-owned unpooled connection for session-scoped work and per-test databases that never touches Npgsql's static pool registry. |
Elarion.Sql.Sqlite | The EF-free tier should run on a single-node / edge SQLite file. The single AddElarionSqlite(connectionString) picks SQLite for every subsystem — a DbDataSource over Microsoft.Data.Sqlite (which ships none) and the provider the session opens from, plus the SQLite migration engine (per-file in-process lock) behind the neutral AddElarionMigrations. The full mirror of Elarion.Sql.PostgreSql. |
Elarion.Migrations | A host needs the one migration plan (ADR-0081): embedded versioned/repeatable SQL scripts and C# ICodeMigration steps merged into one version-ordered sequence with one history and one lock, planned and executed roll-forward without a database driver — the provider-neutral AddElarionMigrations over a provider registered elsewhere (Elarion.Sql.PostgreSql, Elarion.Sql.Sqlite). NativeAOT-compatible; EF-free. |
Elarion.Migrations.EntityFrameworkCore | An EF host should run its EF migrations through the plan instead of Database.MigrateAsync(): each EF migration becomes a version-ordered step beside SQL scripts and code steps (expand → C# backfill → contract in one release), via o.AddEntityFrameworkMigrations<TContext>(). Brings Microsoft.EntityFrameworkCore.Relational; not AOT. |
Elarion.EntityFrameworkCore.Identity | A persistence layer needs the web-free Identity model on a plain DbContext. |
Elarion.Authorization.EntityFrameworkCore | [RequireResource] needs the EF-backed resource-grant store and authorizer. |
Elarion.Idempotency.EntityFrameworkCore | [Idempotent] and event inbox claims need durable PostgreSQL-backed storage in the handler transaction. |
Elarion.Auditing.EntityFrameworkCore | [Auditable] handlers and [Audited] entities need a durable audit trail and field-level change capture. |
Elarion.Scheduling.EntityFrameworkCore | Recurring occurrences must be claimed once across multiple PostgreSQL-backed instances. |
Elarion.Coordination.PostgreSql | A coarse named role needs heartbeat leases, holder address advertisement, and fail-closed election. |
Events and browser updates
| Package | Add it when |
|---|---|
Elarion.Messaging.InMemory | Integration events may be best-effort and process-local while still dispatching after the EF transaction commits. |
Elarion.Messaging.Outbox | Integration events must survive crashes and deliver at least once after the business transaction commits. |
Elarion.ClientEvents | Browsers need authorized at-most-once re-query hints, topic registration, subscription lifecycle, and in-process delivery. |
Elarion.ClientEvents.PostgreSql | Client-event hints must fan out across roughly 1–10 nodes over PostgreSQL LISTEN/NOTIFY. |
Elarion.ClientEvents.AspNetCore | Client events should stream to browsers over authorized Server-Sent Events. |
Elarion.WebPush | Users should be notified while the app is closed: Web Push (VAPID) delivery to their browsers/PWAs with dead-subscription cleanup, a subscription-store seam, and an in-memory default. |
Elarion.WebPush.EntityFrameworkCore | Push subscriptions and the VAPID key pair need durable EF tables (PostgreSQL or SQLite). |
Elarion.WebPush.AspNetCore | The browser package's default transport should call MapElarionWebPush endpoints rather than application handlers. |
See events and messaging for domain events, integration events, outbox, client events, and ordered streams, and Web Push for notifying users whose app is closed.
Actors, connections, and devices
Default to request/reply plus client events. Add these packages only when a live state machine, bidirectional connection, or device identity chain is actually the consistency boundary.
| Package | Add it when |
|---|---|
Elarion.Actors | A live in-memory resource, hot ephemeral state, or decide-once coordinator needs a keyed mailbox and generated typed facade. Placement is explicit through ActorPlacementMode.Local, SingleHome, or fixed VirtualShards (ADR-0061). |
Elarion.Actors.PostgreSql | Actor snapshots need PostgreSQL durability/query access, single-homed actors need the "actors" role binding, or virtual-sharded actors need fixed actors:partition-N role leases via AddElarionPostgreSqlActorSharding<TDbContext>(). |
Elarion.Connections | A bidirectional client/device link needs the node-local registry, protocol codec seam, bounded server invocation, and client-event bridge. |
Elarion.Connections.AspNetCore | A device/client gateway needs the WebSocket lifecycle adapter with app-owned authentication and codec. |
Elarion.Connections.Tcp | A proprietary protocol needs hosted TCP listen/dial, TLS-before-framing, reconnect, framing, bounded outbound delivery, idle handling, or runtime-managed endpoints. |
Elarion.Connections.Simulation | Connection tests or developer simulators need in-memory sinks, observers, framed clients, or the socket-free full TCP lifecycle. |
Elarion.Connections.AspNetCore.Simulation | WebSocket adapter tests need a real Kestrel upgrade, handshake, codec, and close path via WebSocketTestHost. |
Elarion.Devices | Device provisioning needs pairing codes, key-store seams, HMAC challenge verification, and the canonical device principal. |
Elarion.Devices.EntityFrameworkCore | Device keys and single-use pairing codes need durable EF/PostgreSQL stores. |
Read the actor decision guide before adding the actor packages.
Blob storage and upload transports
| Package | Add it when |
|---|---|
Elarion.Blobs | Application code needs streaming provider-neutral blob contracts, pending/commit lifecycle, listing, or staged upload seams. |
Elarion.Blobs.PostgreSql | Blobs and/or resumable upload staging should live in the application's PostgreSQL database. |
Elarion.Blobs.Azure | Blobs and staged uploads should use Azure Blob Storage and append blobs. |
Elarion.Blobs.AspNetCore | An ASP.NET host needs direct upload/cancel and owner-scoped streaming download endpoints. |
Elarion.Blobs.Tus | Large uploads should use the recommended tus 1.0 resumable transport over any staged-upload store. |
Runtime settings
| Package | Add it when |
|---|---|
Elarion.Settings | Application code needs declared, typed runtime settings resolved through one layered resolver (default, store, configuration pin), plus the in-process default store/change source. |
Elarion.Settings.EntityFrameworkCore | Settings need durable relational storage with optimistic concurrency (provider-neutral; PostgreSQL and SQLite are exercised by the test suite). |
Elarion.Settings.Configuration | The effective global settings (secrets excluded) should project into IConfiguration/IOptionsMonitor with live reload. |
Elarion.Settings.DataProtection | Secret settings must be encrypted at rest with ASP.NET Core Data Protection (the opt-in ISettingValueProtector; secret definitions fail startup without a protector). |
Elarion.Settings.PostgreSql | Setting changes must notify every node over PostgreSQL LISTEN/NOTIFY. |
npm packages
| Package | Add it when |
|---|---|
@swimmesberger/elarion-jsonrpc-client-generator | A TypeScript client should be generated from rpc-schema.json with Zod validation and typed client-event subscriptions. |
@swimmesberger/elarion-contributions | A frontend needs typed extension points, declarative module contributions, capability gating, action gating from the RPC contract (canCall over the generated rpcMethodInfo), and optional React/Angular/TanStack Router bindings. |
@swimmesberger/elarion-webpush | A browser/PWA should subscribe to Web Push: availability detection (including the iOS Home Screen requirement), gesture-safe permission, subscribe/refresh helpers, and the service-worker handlers. |
@swimmesberger/elarion-pwa | The frontend should install as an app: install-prompt capture with iOS instructions, reloading into a new deploy only on a safe page change, renewing an expired authenticating-proxy session, a service-worker shell router (/sw) that never caches the API, personal pages, or redirects, and a Vite plugin (/vite) publishing the build version. See Installable apps (PWA). |
Dependency rules
Elarion.Abstractionscontains implementation-neutral contracts;Elarionsupplies dependency-light runtime behavior and bundles the core generator (Elarion.Generators); provider packages such asElarion.EntityFrameworkCoreandElarion.Sqlbundle their own generators.- Provider-neutral cores (
Blobs,Connections,ClientEvents, settings seams) never depend on a concrete provider or wire adapter. Elarion.JsonRpchas no ASP.NET dependency;Elarion.AspNetCoreowns HTTP hosting.- EF packages own EF mapping and providers; NativeAOT SQL packages stay EF-free.
- Generators emit deterministic code and diagnostics rather than scanning at runtime. Reference
Elariondirectly in every assembly that needs its bundled analyzer; analyzer assets are not transitive.
Typical references
| Project | Usual starting references |
|---|---|
| Application/module assembly | Elarion; optionally Elarion.Validation and provider-neutral capability packages |
| EF persistence assembly | Elarion.EntityFrameworkCore plus the exact EF-backed capability packages it maps |
| EF host running migrations | Elarion.Migrations + Elarion.Migrations.EntityFrameworkCore + Elarion.Sql.PostgreSql (or .Sqlite) for the plan's connection and lock |
| EF-free NativeAOT host (PostgreSQL) | Elarion.Sql + Elarion.Sql.PostgreSql + Elarion.Migrations |
| EF-free NativeAOT host (SQLite, single-node / edge) | Elarion.Sql + Elarion.Sql.Sqlite + Elarion.Migrations |
| ASP.NET Core host | Elarion, Elarion.JsonRpc, Elarion.AspNetCore; opt in to OpenAPI, MCP, schema generation, Identity, SSE, and blob transports as needed |
| Frontend | @swimmesberger/elarion-jsonrpc-client-generator; optionally @swimmesberger/elarion-contributions, @swimmesberger/elarion-pwa, and @swimmesberger/elarion-webpush |