ZeroAlloc.ValueObjects.EfCore 2.2.1

ZeroAlloc.ValueObjects

Zero-allocation source-generated ValueObject equality for your existing domain types.

Same performance as record — without forcing the record keyword on your domain model. Add [ValueObject] to any partial class or partial struct and the generator emits Equals, GetHashCode, == and != with no heap allocations, plus a ToString override. ToString returns a new string, so it allocates like any other ToString.

Install

dotnet add package ZeroAlloc.ValueObjects

Quick start

using ZeroAlloc.ValueObjects;

// Annotate any existing partial class — no keyword changes, no base class
[ValueObject]
public partial class Money
{
    public decimal Amount { get; }
    public string Currency { get; }
    public Money(decimal amount, string currency) => (Amount, Currency) = (amount, currency);
}

// Use standard equality — zero allocations
var a = new Money(10m, "USD");
var b = new Money(10m, "USD");

bool equal = a == b;            // true
bool same  = a.Equals(b);       // true  — IEquatable<Money> fast path
int  hash  = a.GetHashCode();   // same as b.GetHashCode() — safe as dict key
string s   = a.ToString();      // "Money { Amount = 10, Currency = USD }"

Performance

Multi-field value objects (Money(decimal Amount, string Currency)): ZA matches record / record struct exactly. CFE allocates ~90 B per call.

The 0 B for Equals, GetHashCode, == and != is asserted on a class and a struct by EqualityAllocationTests.

Single-int wrapped IDs vs Vogen (the source-gen alternative):

ZA wins or ties every row, with 0 B allocated on all of them. The ToString row is 0 B only because the benchmark formats 42, and .NET caches the strings of small integers; formatting a larger value returns a new string. The previous regressions on GetHashCode (~30× slower) and ToString (~72 B allocation) were closed in v1.7 by aligning the single-property emit to Value.ToString(InvariantCulture) / Value.GetHashCode() directly. ZA also supports multi-field types — [ValueObject] on a partial class or partial struct with any number of fields — which Vogen does not.

Full methodology and analysis: docs/performance.md

Features

• Zero-allocation Equals, GetHashCode, == and != — no iterator state machine, no boxing
• Works on existing partial class and partial struct — no refactoring required
• Can inherit from non-record base classes
• Fine-grained member control with [EqualityMember] (opt-in) and [IgnoreEqualityMember] (opt-out)
• No extra generated members — no with, no Deconstruct, no EqualityContract
• Null-safe comparison for nullable reference type properties
• HashCode.Combine for ≤8 properties, incremental HashCode.Add for 9+

Why not just use record?

Typed identifiers

[TypedId] is the companion attribute for strongly-typed IDs — OrderId, UserId, MessageId. It solves the same problem as the ValueObject attribute, but tailored for single-value identifiers with built-in generation strategies.

Basic usage

using ZeroAlloc.ValueObjects;

[TypedId(Strategy = IdStrategy.Ulid)]
public readonly partial record struct OrderId;

// Usage
OrderId id = OrderId.New();          // monotonic ULID
string s = id.ToString();            // "01ARZ3NDEKTSV4RRFFQ69G5FAV" — 26-char base32
OrderId parsed = OrderId.Parse(s);   // round-trip

Strategies

Assembly-level default

[assembly: TypedIdDefault(Strategy = IdStrategy.Ulid)]

[TypedId]                                       // resolves to Ulid from the assembly default
public readonly partial record struct ProductId;

[TypedId(Strategy = IdStrategy.Snowflake)]      // per-struct override
public readonly partial record struct MessageId;

Snowflake worker ID configuration

Snowflake IDs encode a 10-bit worker ID so multiple processes can mint IDs concurrently without collision. Configure at startup:

builder.Services.AddSnowflakeWorkerId(workerId: 5);
builder.Services.AddSnowflakeWorkerId(envVar: "POD_ORDINAL", fallback: 0);
builder.Services.AddSnowflakeWorkerId(() => ComputeWorkerIdFromHostname());

These publish the worker ID immediately — no host required.

To derive the ID from a registered service, install ZeroAlloc.ValueObjects.Hosting, which adds an overload backed by a hosted service:

builder.Services.AddSnowflakeWorkerId(sp => sp.GetRequiredService<IMachineIdProvider>().Id);

It lives in a separate package so the core one carries no Microsoft.Extensions.Hosting.Abstractions dependency. The namespace is the same, so only the package reference changes.

If no provider is registered, the generated New() of a Snowflake-strategy ID, such as MessageId.New(), falls back to ZA_SNOWFLAKE_WORKER_ID env var, then throws TypedIdException.

EF Core

Install ZeroAlloc.ValueObjects.EfCore and call the registration the generator emits for your assembly, here MyApp:

protected override void ConfigureConventions(ModelConfigurationBuilder builder)
{
    builder.AddMyAppTypedIdConventions();
}

All [TypedId] structs in the assembly are mapped: Guid-backed → uniqueidentifier/uuid, long-backed → bigint. The generated Add{Assembly}TypedIdConventions() calls Properties<TId>().HaveConversion<TypedIdValueConverter<TId, TBacking>>() for each struct by name, so it needs no reflection or assembly scan and is trim-safe and NativeAOT-safe. Each struct also gets OrderId.AddTypedIdConvention(builder) to register one ID. The reflection-based builder.AddTypedIdConventions() remains for apps that do not trim. Per-property HasConversion still overrides. See EF Core integration.

Minimal API binding

No setup needed — the generator emits IParsable<T> + ISpanParsable<T>, so app.MapGet("/orders/{id}", (OrderId id) => …) just works.

JSON

Each TypedId carries [JsonConverter] pointing at a nested converter that reads/writes a string. Fully AOT-safe. No JsonSerializerContext wiring required for basic use; if you're source-generating JsonSerializerContext, include the TypedId types there too.

Compile-time diagnostics

[ValueObject] reports ZAVO001–ZAVO003 for value objects it cannot generate; see docs/diagnostics.md.

Production checklist

• Sequential is not for production. The counter resets on process restart. Use it only in tests where deterministic IDs matter.
• Snowflake worker IDs must be unique across all producing processes. AddSnowflakeWorkerId cannot detect duplicates. Coordinate via orchestrator ordinals (Kubernetes pod index, Nomad alloc index) or a central registry. Duplicate worker IDs silently produce colliding IDs.
• Clock skew matters. Snowflake generation handles small rollbacks by pinning to the last observed millisecond, but severe skew (>5s) throws TypedIdException. Run NTP-synced or accept the brief unavailability.
• Process restart loses Sequential state but not Snowflake or ULID/UUID7 ordering. ULID/UUID7 are globally safe to restart; Snowflake is safe if worker ID is stable across restarts.

Documentation

License

MIT