Dalion.ValueObjects 1.0.0-beta05

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.).

Installation and usage

Add the Dalion.ValueObjects NuGet package to your project.

<ItemGroup>
  <PackageReference
    Include="Dalion.ValueObjects"
    Version="[1.0.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 for conversion to and from the underlying primitive value
• 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 Default (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.

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

Give a Star! ⭐

If you like or are using this project please give it a star. Thanks!

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.

Limitations Overcome

This library addresses several limitations found in similar solutions, such as Vogen or StronglyTypedId:

• No Run-Time Dependency:
  Unlike e.g. Vogen, which requires an assembly at run-time (e.g. Vogen.SharedTypes.dll), all necessary types are generated alongside your value objects. There are no additional run-time dependencies. All required types are generated at compile-time and generated code is self-contained.

• Automatic Generation of Pre-Set Values:
  Every value object automatically gets an Empty or Default (configurable) pre-set value, reducing boilerplate and ensuring consistency.

Fundamental Differences in Approach

This library takes a distinct approach to value objects, with perspectives and assumptions that are incompatible with those of Vogen or StronglyTypedId.

These assumptions and approaches reflect our perspective on value objects, which may differ from others. For us, they make this library more practical and usable in real-world projects.