ddd-dotnet · git:20261108.c2f94bf · 2026-11-08 · sha256 14807fd772404480

ddd-dotnet git:20261108.c2f94bfA

Immutable. This exact content never changes and is served at /api/v1/blob/14807fd772404480.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_nund373ldtlnd65b/14807fd7724044800e9d448bc88d83db07f4dbdc273db9ea9fa71c1935118d6a.json

Then /plugin install ddd-dotnet@markdownregistry-nund373ldtlnd65b in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: ddd-dotnet
description: >-
  The .NET realization of tactical DDD (see the `ddd` skill for the
  principles). Use when writing or reviewing C# domain code: value objects
  and their factories, aggregates and their From/Create, the domain exception
  family, collecting events on the root, or giving an aggregate its DbContext. It
  encodes the JorgeCostaMacia.DDD.* base types, the four-factory surface
  (From, FromOrNull, Create, CreateOrNull) and why every one is declared,
  Convert as the one place a value is altered, no coercion and no defaults on
  a value object, the aggregate rule (From cascades, Create seals), and one
  DbContext per aggregate as its accessor.
---

# DDD in .NET

The .NET *how* of the model defined in `ddd` (load it for the *why*). How a validator is written — rules, messages, composition — is `validation-dotnet`'s; this skill says which validator each domain type has and how it runs it.

## The base types

The building blocks come from the `JorgeCostaMacia.DDD.*` packages (the ddd-dotnet repository); derive from them, don't redeclare them.

| Package | Gives |
| --- | --- |
| `JorgeCostaMacia.DDD.ValueObject` | `StringValueObject`, `IntValueObject`, `LongValueObject`, `DecimalValueObject`, `DateTimeValueObject`, `DateTimeUtcValueObject`, `BoolValueObject`, `UuidValueObject`… — each with its validator and validation exception |
| `JorgeCostaMacia.DDD.Aggregate` | `Aggregate`: the root's base, with `AddEvent` / `PullEvents` |
| `JorgeCostaMacia.DDD.Entity` / `.DDD.DomainEvent` | `IEntity`, `IDomainEvent` |
| `JorgeCostaMacia.DDD.Exception` | `NotFoundException`, `ExistException`, `ValidationException`, `ErrorException` — the bases of every family exception, each with a fixed code |

## Value objects

A value object is a `sealed record` deriving from its base, one folder per field — `Domain/<Field>/` holding `<Aggregate><Field>`, its `<Aggregate><Field>Validator` and its `<Aggregate><Field>ValidationException`. All of them flat at the root of `Domain/`: no `ValueObjects/` grouping.

```csharp
internal sealed record PedidosReferencia : LongValueObject
{
    // HYDRATE — raw assignment, no conversion, no validation: ORMs and deserializers only.
    public PedidosReferencia(long value) : base(value) { }

    // CONVERT — materializes through Convert, unvalidated: the path composites build their parts with.
    public static new PedidosReferencia From(long value) => new PedidosReferencia(Convert(value));
    public static new PedidosReferencia? FromOrNull(long? value) => value is null ? null : From(value.Value);

    // CREATE — nothing invalid escapes it.
    public static new PedidosReferencia Create(long value)
    {
        PedidosReferencia vo = From(value);
        vo.Validate();

        return vo;
    }

    public static new PedidosReferencia? CreateOrNull(long? value)
    {
        PedidosReferencia? vo = FromOrNull(value);
        vo?.Validate();

        return vo;
    }

    private void Validate() => PedidosReferenciaValidator.Create().ValidateAndThrow(this);
}
```

- **Declare all four factories, always** — whatever the field's nature. The bases declare all four as public statics, so an undeclared one is still reachable and answers wrongly: `XId.CreateOrNull(5L)` without its own declaration returns the *base* type, validated by the base validator — the field's own rule skipped in silence. `new` is mandatory on each, and the compiler proves the *modifier* both ways: `CS0108` without it, `CS0109` where nothing is hidden. It cannot prove a factory is *declared*: an undeclared one resolves to the base's at any call site that doesn't demand the derived type — `XEstado.Create(x).Value` in a predicate compiles and skips the rule. `From`/`FromOrNull` are pinned by the aggregate, whose typed properties refuse the base (`CS0266`); `Create`/`CreateOrNull` on a payload VO have no production caller, so a test pins them — see *Testing this model*.
- **Optionality lives in the `OrNull` sibling, never in the return type**: `From`/`Create` always return non-null. `FromOrNull` is the one place that looks at the input (`value is null ? null : From(value.Value)`; a string VO writes `From(value)`, since `string?` has no `.Value`). `CreateOrNull` branches on **what `FromOrNull` returned** (`vo?.Validate()`), never on the input again — so it stays correct if a `From` ever maps a sentinel to absence, and never hands the validator a null.
- **One input type per VO**, the base's natural primitive. A second suffixed overload (`FromOrNull(string?)` and `FromOrNull(int?)`) makes `FromOrNull(null)` ambiguous (`CS0121`); other primitives are converted at the call site.
- **The validator is reached through one `private void Validate()`**, the local is `vo`.

### Convert — the one place a value is altered

The base's `protected static Convert` is the only place a value changes on its way in, and what it does is convert the input to **the base's representation**: `StringValueObject` trims, `DateTimeUtcValueObject` yields an instant in UTC. A derived VO whose type represents something else **hides it** — `private static new` — and every factory picks it up:

```csharp
// fidelity: a landing layer keeps the source's text as it came
private static new string Convert(string value) => value;

// the store keeps microseconds: one value in memory, on the wire and in the table
private static new DateTime Convert(DateTime value)
    => new DateTime(value.Ticks - (value.Ticks % TimeSpan.TicksPerMicrosecond), value.Kind);
```

- Hiding `Convert` is how a layer states its policy; keep it uniform across the layer (every string VO of a landing layer passes through, not one of them).
- Calls *inside* the base still bind to the base's overloads — hiding only affects the derived type's factories.
- A conversion **never alters a value silently** beyond its rule: no comma dropped as a thousands separator, no fraction truncated into an integer. When the input is not the type, it throws.

### No coercion, no defaults

- **A VO never pulls a value into range.** Out of range is a caller's mistake and its `Create` throws the typed exception.
- **No `Default` and no public `Max`.** A default is call-site policy; a public bound is an invitation to clamp against it. The bound lives as a literal in the validator, pinned by two tests either side (`Create(1000)` accepted, `Create(1001)` rejected) so it cannot drift.
- **A base rejects only what is not the type** — and most bases check nothing (`validation-dotnet` lists what each one does). Policy (not empty, a range, a format, a closed list) lives in the derived VO's validator.
- A bound on "now" is captured when the validator is constructed — per `Create` today. Cache a validator in a static and the clock freezes at process start.

### A composite value object

A VO made of other VOs (a page range of two page numbers) is a plain `IValueObject` record holding its parts, not a derived base. Its validator runs each part's own validator plus the cross rule (`start <= end`), which inheriting could not do.

## Aggregates

```csharp
internal sealed class Pedidos : Aggregate
{
    public long Id { get; init; }                          // the identity (see ddd: it may stay a primitive)
    public PedidosReferencia? Referencia { get; set; }     // optional field, nullable VO
    public PedidosMetaActive MetaActive { get; set; } = null!;

    private Pedidos() { }                                   // ORM materialization

    public Pedidos(                                        // hydration
        long id,
        PedidosReferencia? referencia,
        PedidosMetaActive metaActive)
    {
        Id = id;
        Referencia = referencia;
        MetaActive = metaActive;
    }

    // FROM cascades: every part through ITS From — nothing validated, nothing thrown yet.
    public static Pedidos From(
        long id,
        long? referencia,
        bool metaActive)
        => new Pedidos(
            id,
            PedidosReferencia.FromOrNull(referencia),
            PedidosMetaActive.From(metaActive));

    // CREATE seals: one composed validation, one exception with every failure.
    public static Pedidos Create(
        long id,
        long? referencia,
        bool metaActive)
    {
        Pedidos aggregate = From(
            id,
            referencia,
            metaActive);
        aggregate.Validate();

        return aggregate;
    }

    private void Validate() => PedidosValidator.Create().ValidateAndThrow(this);
}
```

- The root is an `internal sealed class` deriving `Aggregate` (identity, not value semantics — so a class, not a record). Fields that change are `set`; the identity and what never changes after creation are `init`.
- **The aggregate never calls its parts' `Create`** — that would throw on the first invalid part alone. `From` cascades through the parts' `From`/`FromOrNull`; `Create` validates the whole once (see *Validating the model*).
- **The nullability of each factory call matches its property**: `XField.FromOrNull(...)` for an optional field, `XField.From(...)` for a required one. Add a field, keep both sides in step.

## Validating the model

Every value object and every aggregate has its own `<X>Validator` and `<X>ValidationException`, next to it in its folder.

- **The validator is built with `Create()`, never resolved from DI.** A type validates inside its own static `Create`, where there is no container, and its rules are pure — there is nothing to inject. `XValidator.Create()` assembles the whole chain, and the type reaches it through one `private void Validate() => XValidator.Create().ValidateAndThrow(this);`.
- **Only `Create` validates.** `From` and the hydration constructor never do: a composite is built from unvalidated parts, and rehydrating N rows must not re-validate them.
- **A value object's validator `Include`s its base's** (`Include(DateTimeUtcValueObjectValidator.Create())` through the constructor) and adds the field's own rule, so the base's type checks always run. Its exception derives the base's (`DateTimeValueObjectValidationException`…).
- **The aggregate's validator composes its parts**: one `SetValidator` per value-object property — an optional one guarded with `.When(v => v.Part is not null)` and selected as `v.Part!` — plus the aggregate's own cross-field rules. One `ValidateAndThrow` in `Create` reports every failure, with its property path, in one `<X>ValidationException`.

  ```csharp
  RuleFor(v => v.Referencia!)
      .SetValidator(referencia)
      .When(v => v.Referencia is not null);

  RuleFor(v => v.MetaDeletedAt)                // the aggregate's own rule
      .NotNull()
      .When(v => !v.MetaActive.Value);
  ```

- A composite value object (two page numbers making a range) validates each part with the part's own validator plus the cross rule (`start <= end`).
- **Which layer holds a content rule** follows `ddd`: a landing layer's payload VO has a validator that only `Include`s its base's, and the field's rule — a length, a format — lives in the standardizing layer's VO; the landing layer's own rules are on its identity and `Meta*` fields.

## The exception family

Each concept ships its typed exceptions, one file each, deriving the `JorgeCostaMacia.DDD.Exception` bases: `<X>ValidationException` (raised by its validator), `<X>NotFoundException`, `<X>ExistException`.

- Each carries a **fixed GUID code**, a literal in its convenience constructor, so occurrences trace across logs and responses whatever the wording. The code is a **UUIDv7** (`Guid.CreateVersion7()`), minted fresh for each exception type by whoever writes the file — never copied from a neighbour: a generator that stamps one GUID into every file it writes leaves seventy exceptions sharing a code that then identifies none of them. Nothing in the language checks it, so the host suite does: one convention test asserts every exception's code is distinct across the solution (see `testing-dotnet`).
- Two constructors: the full tuple (transport) and the convenience one producers use.

## Events

The root collects what happened as `IDomainEvent`s through `AddEvent(...)` — in this family the contract's own event, since the bus's `Event` is an `IDomainEvent` (see `ddd`: the published events *are* the domain events) — and whoever persists it takes them with `PullEvents()` **after** a successful save, so no event escapes a failed operation. How they reach the bus is `bus-dotnet`'s.

## The aggregate's accessor

**One `DbContext` per aggregate**, internal to its module, its `DbSet` named `<X>Repository`: the per-aggregate accessor `ddd` asks for. Application uses it as-is — an accepted core coupling, with no repository port around it. How the model maps to the tables (value objects, keys, converters) is persistence, not this skill's.

## Testing this model

- Composition tests use `From` (it skips the validators and keeps the test free of unrelated field rules); rule tests use `Create`.
- Every VO with a rule of its own: its red case on the typed exception, and the bound from both sides.
- `From`/`FromOrNull` both directions on the aggregate: every optional part materialized when supplied, every one null when not.
- A `Convert` of its own (a truncation, a kind) has its own test: without it, moving the VO to another base passes everything else.
- **A VO with no rule and no `Convert` of its own has no test file of its own.** What it has to pin is the same for every VO of its kind — the four factories declared on the type and returning it, and the layer's `Convert` policy (a landing layer's strings pass through, a standardizing layer's are trimmed) — so one **convention test per module** enumerates the module's value objects and pins it for all of them (`testing-dotnet` has the realization). The day it gains a rule or a `Convert`, it gains its file.