OrionKey 0.5.0

OrionKey

Source-generated strongly-typed IDs for .NET.

OrionKey turns a readonly partial struct into a fully-featured strongly-typed ID with a single attribute. A bundled Roslyn source generator emits the equality, comparison, factory, serialization, and persistence members, so a domain ID stops being a bare Guid or long and becomes a distinct type the compiler can check. No base class, no runtime reflection, nothing to wire up.

Quick start

dotnet add package OrionKey

Mark a partial struct with [OrionId] and a storage type. The optional second type argument selects a generation strategy:

[OrionId<Guid>]              public readonly partial struct OrderId;
[OrionId<long, Snowflake>]   public readonly partial struct UserId;
[OrionId<string, Ulid>]      public readonly partial struct TenantId;
[OrionId<string, NanoId>]    public readonly partial struct SessionId;

Strategies

The int and long integer forms have no New() factory; they model ids assigned externally, typically by a database identity column.

What gets generated

For every annotated struct the generator emits, as partial companions:

• The struct body itself: a Value member, a New() factory (strategy-backed types), and value-based IEquatable equality with == / !=.
• An IComparable / IComparable<T> implementation, emitted only for sortable strategies (GuidV7, SequentialGuid, Snowflake, Ulid, Ksuid, ObjectId).
• A System.Text.Json JsonConverter so the id serializes as its underlying value.
• A TypeConverter for framework conversions and ASP.NET Core model binding.
• IParsable<T> and ISpanParsable<T> implementations for allocation-aware parsing.
• An EF Core ValueConverter, emitted only when the project references EF Core, so the id can be used directly as an entity key or property.

The generated converters are discovered automatically by System.Text.Json, EF Core, and ASP.NET Core model binding. No manual registration is required.

Library integration

When the consumer project references Dapper, Newtonsoft.Json, MongoDB.Driver, or Swashbuckle.AspNetCore, OrionKey emits matching companions for every [OrionId] struct:

OrionKey is released under the MIT License.

AOT & trimming

OrionKey 0.4+ is compatible with Native AOT and trimming. The runtime assembly carries <IsAotCompatible>true</IsAotCompatible> and a CI matrix publishes a self-contained AOT binary on linux-x64 and win-x64 every push.

Newtonsoft.Json, MongoDB.Driver, Swashbuckle.AspNetCore, and Dapper are not fully AOT-clean as of mid-2026 — prefer System.Text.Json, EF Core, and the BCL TypeConverter/IParsable pipelines in AOT projects. When using System.Text.Json source generation, register the generated <Id>JsonConverter instances into JsonSerializerOptions.Converters and pass the options into new JsonContext(options). For IParsable<T>, invoke T.Parse(text, null) via a where T : IParsable<T> constraint (the emitted Parse is an explicit interface implementation).