Temp.DDDToolkit.HotChocolate 3.0.0

DDDToolkit

Source generators that remove the repetitive parts of domain driven design in .NET. You declare the intent with an attribute; the generator writes the base type, the equality members, the identifier plumbing, the persistence mapping and the API conversions.

Documentation: dylansnel.github.io/DDDToolkit, the docs/ folder as a site.

[AggregateRoot<Guid>("ORD")]
public partial class Order
{
    public Order(OrderId id, CustomerId customer) : base(id)
    {
        Customer = customer;
        RaiseDomainEvent(new OrderPlaced(id, customer));
    }

    public CustomerId Customer { get; private set; }

    public partial IReadOnlyList<OrderLine> Lines { get; }

    public void AddLine(OrderLine line) => _lines.Add(line);
}

That is the whole declaration. OrderId did not have to be written at all: naming the raw value generates it as an allocation-free identifier with parsing, comparison and JSON support. Order gets its base class, an optimistic concurrency version, a domain event list only it can write to, and a _lines backing field that Entity Framework maps directly while the outside world sees a read-only list.

Declare the identifier yourself when other aggregates, DTOs or API contracts refer to it, which gives it a file of its own to navigate to:

[EntityId<Guid>("ORD")]
public readonly partial record struct OrderId;

[AggregateRoot<OrderId>]
public partial class Order { }

Documentation

With an AI coding agent

An agent that has never seen the toolkit writes the base class the generator already writes, a settable collection, a sealed value object. Three things teach it otherwise.

A skill. skills/dddtoolkit holds the declarations, the rules the generators enforce, the wiring for Entity Framework and modules, and the fix for every DDD diagnostic. It is an Agent Skill, the format Claude Code, Codex, Cursor and GitHub Copilot read. This repository is also a Claude Code plugin marketplace, so in Claude Code:

/plugin marketplace add DylanSnel/DDDToolkit
/plugin install dddtoolkit@dddtoolkit

For another agent, npx skills add DylanSnel/DDDToolkit installs it, or copy the folder into the agent's skills directory.

The docs as text. The site serves llms.txt, an index of the pages with what each covers, and llms-full.txt, all of them in one file. Every page is also plain Markdown at its own address with .md added, such as docs/invariants.md.

The diagnostics. Every DDD diagnostic carries a link to its entry in Diagnostics, so an IDE opens it from the error list and an agent that reads the build output can follow it.

Packages

Reference DDDToolkit and add the integrations you actually use. Each integration package brings its own generator, so referencing it is all the configuration there is.

For now 3.x is published under Temp. ids: Temp.DDDToolkit, Temp.DDDToolkit.EntityFramework, and so on, each package in the table below with Temp. in front of its name. The nuget.org account that owns the DDDToolkit.* ids cannot publish at the moment, so DDDToolkit there is still 2.0.22. Only the package id is different. The assemblies and namespaces are the ones this page names, so using DDDToolkit; stays as it is.

dotnet add package Temp.DDDToolkit

There are five more packages you never reference directly: DDDToolkit.Analyzers and the .EntityFramework, .EntityFramework.Supabase, .FluentValidation and .HotChocolate analyzer packages beside it. Each one carries the generators for its integration and arrives as a dependency of the package above, so adding DDDToolkit.HotChocolate is all it takes to get the GraphQL generator.

Requires .NET 10. The generators themselves target netstandard2.0 and carry no runtime dependencies, so they load in any recent SDK.

The core has no mediator dependency and does not need one: in-process event delivery is a delegate you write, and DDDToolkit.Mediator only saves you writing it. The examples publish through Mediator rather than MediatR because MediatR is commercially licensed from version 13, and this repository prefers dependencies its users can take for free. MediatR still works perfectly well with the toolkit; Delivering domain events shows the delegate to write for it.

What the generators produce

Add DDDToolkit.EntityFramework and the same declarations also produce value converters, [Owned] and [ComplexType] annotations, and a single Add<Module>Converters call for your DbContext. Add DDDToolkit.HotChocolate and they produce GraphQL type bindings. You never write that code.

Beyond the declarations

Three things the toolkit does that are not a generated member.

Invariants. State a rule in the generated partial void CheckInvariants() seam, or as a nested IInvariant<T> when it deserves a name, a code and a test of its own. There are two moments to ask. GetInvariantViolations() answers with a list and never throws, for the application that wants to handle "not consistent yet"; EnsureInvariants() throws, and an interceptor runs the same check before every SaveChanges that writes the entity, child entities included, so a broken rule stops the save. Asking the aggregate root asks the whole aggregate, its children too, each violation naming the entity that reported it, so a handler can act on an aggregate and ask what that broke without a DbContext taking part. State nothing and the compiler erases the seam, so an aggregate with no invariants pays nothing.

Integration events. The outbox writes one row per event in the same transaction as the aggregate. A sink delivers it afterwards: to another module in this process, to a pgmq queue, to a GraphQL subscription, or to one you wrote. Versioning and upcasting keep last year's payload readable, and an inbox keyed by message id and consumer makes the receiving side idempotent.

Modules. Mark an assembly [assembly: Module("Ordering")] and name what it publishes with [ModuleContract]. An analyzer then reports where another module reaches past the contract. It says nothing at all until both sides opt in.

Status

Version 3.0 is a breaking release. Identifiers may be structs, domain events moved from Entity to AggregateRoot, IDomainEvent carries an id and a timestamp, aggregates gained an invariant seam and a concurrency version, and misapplied attributes now report a diagnostic instead of silently generating nothing.

Coming from 2.0.22, read Migrating to 3.0: it lists every break with the code you have and the code you need. The changelog has the rest.

License

MIT. See LICENSE.