# AdCodicem.ValueObjects

> An answer to primitive obsession in .NET: single-value DDD value objects, with no reflection and no allocation on the paths that matter.

Annotate a `readonly partial struct` with `[ValueObject<T>]` and a Roslyn source generator writes the rest: construction that normalizes then validates, parsing, formatting, equality, ordering, and the JSON, EF Core, model binding and OpenAPI integrations. Install with `dotnet add package AdCodicem.ValueObjects`. These pages describe 0.2.1, the latest stable release.

## Docs

- [Introduction](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/introduction): An answer to primitive obsession in .NET 10 — single-value DDD value objects generated at compile time, whose rules reach JSON, EF Core, model binding and OpenAPI.
- [Frequently Asked Questions](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/faq): Short answers to the questions people ask about AdCodicem.ValueObjects, with links to the pages that explain them.

## Tutorials

- [Getting Started](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/getting-started): Install AdCodicem.ValueObjects, declare a first value object, and see what the source generator writes for it.
- [Validation and Normalization](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/tutorials/validation-and-normalization): Declare rules on the attribute, add normalization and validation hooks, and follow the order in which a value object runs them.
- [Known Values](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/tutorials/known-values): Model reference-data codes as value objects with named known values, a closed set, and an OpenAPI enum.
- [From Request to Database](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/tutorials/request-to-database): Take value objects through an ASP.NET Core API, its OpenAPI document and EF Core, declaring each rule once.
- [Public Identifiers](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/tutorials/public-identifiers): Declare Stripe-style public identifiers such as acc_1kcv3ahrz6dmv29gqy5cv, mint them, and store them in a narrow EF Core column.

## How-to guides

- [Serialize to JSON](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/json): Serialize value objects as their bare underlying value with System.Text.Json, including source-generated contexts, and with Newtonsoft.Json.
- [Use with ASP.NET Core](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/aspnet-core): Bind value objects from routes, query strings, headers and bodies in MVC and minimal APIs, and return RFC 9457 problem details carrying the violated rule.
- [Document in OpenAPI](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/openapi): Document value objects in the built-in .NET OpenAPI document as their underlying type, with the length, pattern, bounds and known values declared on them.
- [Use with Entity Framework Core](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/ef-core): Map every value object of an assembly to its underlying column type in one call, size columns from declared rules, and choose when reads are validated.
- [Use with Dapper](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/dapper): Register Dapper type handlers for every value object of an assembly, so raw SQL reads and writes the underlying value.
- [Use with FluentValidation](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/fluentvalidation): Validate commands and payloads against the rules value objects already own, and report their stable error codes.
- [Compare Strings Without Case](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/string-comparison): Choose between normalizing a string value object and declaring a case-insensitive comparison, and keep the database collation in agreement.
- [Format a Value](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/formatting): Give a value object named formats, such as a printed or masked IBAN, with an allocation-free formatter hook.
- [Conversions and Arithmetic](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/conversions-and-arithmetic): Opt into implicit and explicit conversions, and into operators and generic math for numeric value objects, without letting a result escape validation.
- [Add Domain Behaviour](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/domain-members): Add your own factories, properties and methods next to the generated members of a value object.
- [Test Your Value Objects](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/test-value-objects): Derive a dozen behavioural checks for your own value objects from a list of accepted and rejected values, with the xUnit contract kit.
- [Work With a Type Known Only at Run Time](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/runtime-lookup): Parse, create and describe a value object when only its Type is known, through the registry every value object joins automatically.
- [Use With an AI Coding Agent](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/ai-agents): Teach a coding agent the AdCodicem.ValueObjects authoring surface with the agent skill, installed as a Claude Code plugin or read as plain Markdown.
- [Migrate From Another Library](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/how-to/migrating): Move to AdCodicem.ValueObjects from bare primitives, hand-written value objects, Vogen, StronglyTypedId or Thinktecture.Runtime.Extensions, one type at a time.

## Reference

- [Packages](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/packages): The twelve AdCodicem.ValueObjects packages, and which boundary each one covers.
- [Authoring Reference](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/authoring-guide): The supported underlying types, every option of [ValueObject<T>] with its default, and the hook interfaces a value object implements.
- [Generated Members](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/reference/generated-members): Every member and interface the source generator adds to a value object, and the options that add more.
- [Error Codes and Exceptions](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/reference/errors): The stable error codes a rejected value carries, the ValidationResult that holds them, and the exception Create throws.
- [Diagnostics](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/reference/diagnostics): Every VO diagnostic the generator and the analyzers report, what it means, and how to fix it.

## Explanation

- [Primitive Obsession](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/explanation/primitive-obsession): What primitive obsession costs a .NET codebase, why the usual remedy is rarely applied, and what AdCodicem.ValueObjects changes about that.
- [Design Decisions](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/design-decisions): Why a value object is a readonly partial struct, why default is a build error, why rejection is not an exception, and why rules are declared once.
- [Entity Identifiers](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/entity-identifiers): The design of Stripe-style public identifiers — format, widths, check character, time bucket — and the alternatives that were turned down.
- [Benchmarks](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/benchmarks): The measurements behind the design — struct against class wrappers, collections, and the cost of validating at the boundary — with allocations to the byte.
- [Compared With Other Libraries](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/explanation/comparison): How AdCodicem.ValueObjects compares with Vogen, StronglyTypedId and Thinktecture.Runtime.Extensions, including where each of them is the better choice.
- [How the Library Is Tested](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/testing): The three test suites behind AdCodicem.ValueObjects — generated behaviour, the generator itself, real databases — and the two paths bugs hide in.

## Optional

- [Full documentation](https://adcodicem.github.io/AdCodicem.ValueObjects/llms-full.txt): every page above, as one Markdown file
- [API reference](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/api): generated from the XML doc comments
- [Preview documentation](https://adcodicem.github.io/AdCodicem.ValueObjects/docs/preview/introduction): describes main, ahead of the latest release
- [Agent skill](https://github.com/AdCodicem/AdCodicem.ValueObjects/tree/main/skills/value-objects): the authoring surface, the wiring of each integration and every diagnostic, written for coding agents