Dalion ValueObjects

A C# code generator to cure Primitive Obsession.

ValueObjects is a .NET Source Generator and analyzer. It turns your primitives (ints, decimals etc.) into value objects that represent domain concepts (CustomerId, AccountBalance, etc.).

All generated code is compatible with C# 11.0 or higher and .NET 8.0 or higher.

Installation and usage

Add the Dalion.ValueObjects NuGet package to your project.

<ItemGroup> <PackageReference Include="Dalion.ValueObjects" Version="[1.1.0,)" ReferenceOutputAssembly="false" OutputItemType="Analyzer" /> </ItemGroup>

Then, create a readonly partial record struct and annotate it with the [ValueObject<T>] attribute:

using System; [ValueObject<Guid>] public readonly partial record struct CustomerId;

This enables the following for the type:

• Guarding against creation of uninitialized or invalid instances in code (based on validation rules you define)
• Ability to normalize the underlying primitive value upon creation
• String representation based on the underlying primitive value
• System.Text.Json Serialization and deserialization support
• TypeConverter support (see Type Conversion in .NET)
• Ability to check if an instance is initialized and valid, and to retrieve validation error messages
• Ability to define pre-set values as public static readonly fields (even if they are considered to be invalid)
• Implementation of IComparable and IComparable<T>
• Implementation of IFormattable for formatting support
• Implementation of IParsable<T> for parsing support
• Implementation of ISpanParsable<T> for span parsing support, and IUtf8SpanParsable<T> for UTF8 span parsing support (if the underlying type supports it)
• Generation of a static property Empty (name is configurable) that represents the default value for the value object type

It makes it possible to enable the following for the type, using arguments in the attribute to configure behavior:

• Equality comparison based on the underlying primitive value (configurable to be case-sensitive or case-insensitive for string-based value objects)
• Equality operators (== and !=) based on the underlying primitive value
• Implicit conversion to and from the underlying primitive value
• Optional generation of helper extension methods for FluentValidation integration
• Optional generation of helper extension methods to facilitate creation (e.g. 32.Celsius())

This library also enables multiple roslyn analyzers that validate correct usage of the [ValueObject<T>] attribute and the annotated types.

You can examine the generated code in the generated sample code files. The behavior of the generated types is documented by unit tests.

Similarly, the behavior of the roslyn analyzers is documented by unit tests.

All generated code is compatible with C# 11.0 or higher and .NET 8.0 or higher.

See the Wiki for more detailed information, such as getting started, tutorials, and how-tos.

Motivation

Creating value objects is a repetitive task. This project aims to reduce the amount of boilerplate code that needs to be written, by generating it.

Inspired by the awesome Vogen project.