• Dictionary entity
• HashSet entity
• List entity

These entities publish a readonly API (indices, ContainsKey, GetEnumerator, Count, ...). This way, less boilerplate has to be written manually.

Other types

• IDomainObject
• AggregateRoot
• IApplicationService
• IBoundedContext
• IDomainService

Validation

Validation should be performed in the constructor of an object. A Validator class can be passed to constructors or factory methods Factories which gives control (from the outside) over the behaviour during (in)validation.

Validator

Provides a way to easily (in)validate domain objects. It support several modes to handle ValidationExceptions:

• Default: throws an exception when the guard invalidates (immutable).
• DoNotThrow: does not throw when the guard invalidates. This is being used by the TryCreate factory, see Factories. It remembers every validation exception that occured during invalidation (mutable).
• Oblivious: does not throw. It does not collect validation exception (immutable).

Guards

• Are an extension method on the Validator and contains logic to validate a domain object. It therefore guards that an object will be in a valid state.
• Ensure that checks are centralized, can easily be re-used, and will throw consistent exception messages. Consistency of messages is especially relevant when using Validation exceptions, see Validation exceptions.
• Help avoid the usage of the throw keyword in hot paths as throw keywords prevent JIT-inlining.
• Accept an ErrorCode. This code is a unique code (in the scope of the domain) and can be used by other services to know which error has occured. When a code has been passed to the guard, a validation exception will be thrown. If null is provided, a system exception will be thrown.

Exceptions

ValidationExceptions

• Are represented in code as ValidationException<TGuard>.
• Should occur after invalidation of external input.
• Contain an error code, a message, and values of the validation parameters, which can be communicated externally.
• This helps localization of messages shown to the end-user for external services. To consume and localize these messages, see the DDD Contracts library.

System exceptions

• Are represented in code as SystemException<TGuard>.
• Contain system-information and therefore should not be visible to the user.

Factories

Factories can be created by implementing the static abstract method ICreatable<TObject,T1,T2,..) (the value object generator will automatically create them for you). When they are implemented, a TryCreate or Create factory method can be used. The TryCreate method offers a good way to try to construct domain objects without having to use an expensive try-catch to catch the validation exception. This factory uses the DoNotThrow Validator-method behind the scenes.

Examples

Create a value object that needs to be validated:

Behaviour:

• Name null will throw a ValidationException<NotNullGuard<Name>> with message "Required data 'value' for 'Name' is missing.".
• Name 'ThisNameIsTooLong' will throw a ValidationException<LengthInRangeGuard> with message "Length is out of range for 'Name' 'ThisNameIsTooLong' (Lower bound: '1') (Upper bound: '15').'.
• Name '1337' will throw a ValidationException<RegexGuard> with message "'Name' '1337' is incorrect.".

Now it's easy to perform TryCreate on the object:

Value object generator

A value object can easily be generated by placing an attribute on an readonly (ref) partial struct. If this is not possible, place the attribute on a partial record/class). The parameters on the attribute are settings which configure the creation of the value object.

The generator correctly implements a value object for you by:

• Forcing you to think about the ToString-implementation:
  You can implement ToString, or letting you choose the default ToDisplayString-method. This can be configured using attribute parameter generateToString. See also ToDisplayString.
• Implementing Equals, GetHashCode, IComparable, and comparison operators:
  Comparison will only be implemented when the underlying value implements IComparable and the setting generateComparison is enabled.
• Generating a default constructor which supports Validator and therefore Guards:
  It even creates some standard validation, see Underlying types. This can be turned of by setting attribute parameter generateDefaultConstructor to false.
• Forces you to think about forbidding the usage of a parameterless constructor by default:
  As structs automatically contain a parameterless constructor, something that can be forgotten easily. The generator will place an Obsolete attribute on a generated parameterless constructor if the required setting forbidParameterlessConstruction is set to true. When the constructor is still being called, it will throw an InvalidOperationException.
• Generating a static property containing a default instance of the value object:
  Value objects are immutable and therefore easily can provided a default value (if needed). This functionality can be turned on by setting generateStaticDefault to true.
• Generating default casts for you:
  • From the underlying value to the value object: explicit cast (because it could throw exceptions).
  • From the value object to the underlying value: implicit cast.
• Letting you choose the property name which holds the underlying value:
  This can be done by providing a value for parameter propertyName. If not provided, 'Value' will be used as property name.
• Setting the accessibility of the property by default to private:
  This can be changed by setting propertyIsPublic to true.
• Letting you think about if a ValidationException or a SystemException should be thrown when a Guard invalidates:
  Using the parameter useValidationExceptions.
• Exposing indices and IEnumerable IReadOnly-methods to value objects with an enumerable as underlying value:
  This can be turned off by setting parameter generateEnumerable to false.
• Adding the keyword readonly automatically for structs:
  This will ensure immutability and also optimize the struct.
• Letting you think about if a underlying value should be nullable:
  Nullability can be enabled by setting valueIsNullable to true.
• Adding the StructLayoutAttribute with LayoutKind.Auto:
  It gives the CLR permission to reorder the bytes corresponding to these fields. It decides exactly how to reorganize the fields for memory usage, packing, etc. By default structs in C# are implemented with LayoutKind.Sequential, because if types are commonly used for COM Interop, their fields must stay in the order they were defined. But because our ValueObjects are not expected to be used for COM Interop the LayoutKind.Auto attribute is used to optimize the struct.
• Adding basic validation for you:
  See Underlying types.
• Forcing you to think about string-equality:
  Comparison behaviour should be provided for value objects that have an underlying value of string.
• Generating Length or Count properties:
  For string or enumerable value objects.
• Automatically implementing IValueObject:
  Not implementing the interface can lead to unexpected and undesired behaviour in your code.

If the generated default constructor has to be extended or edited: copy the generated constructor, place it in your domain object, and edit it. Also set parameter generateDefaultConstructor to false.

⚠️ Manually added properties won't be included in the structural equality.

Manually added properties won't be used in the Equals, CompareTo and GetHashCode-calculation. To use value objects with multiple underlying values a ValueTuple can be provided as type parameter. The property should be set to private and non-private expression bodied properties should be created that expose each value of the tuple. See the tuple example below.

Underlying types

The value object generator supports the following underlying types: struct, string, list, and dictionary. It can even generate objects with multiple underlying values in the form of ValueTuples, see Tuple value object example.

Struct (default)

GenerateValueObjectAttribute<T>
A value object with a struct as underlying value, for example int, DateTime, decimal. It has 2 optional settings minimumValue and maximumValue. When the underlying value implements IComparable, the default constructor will guard that the value lies between these bounds.

Dictionary

GenerateDictionaryValueObjectAttribute<TKey, TValue>
A value object with an immutable dictionary as underlying type. It has 2 optional settings: minimumCount and maximumCount. If provided, the default constructor will guard that the KeyValuePair-count lies between these values.

List

GenerateListValueObjectAttribute<T>
A value object with an immutable list as underlying type. It has 2 optional settings: minimumCount, maximumCount. If provided, the default constructor will guard that the element-count lies between these values.

String

GenerateStringValueObjectAttribute
A value object that holds a string as underlying value. It has multiple settings:

• minimumLength and maximumLength (required). If provided, the default constructor will guard that the length of the string lies between these values.
• useRegex (required). If true, it will force you to implement a static method ValidationRegex which returns a Regex. This regex will be used to (in)validate the object. See the example below.
• stringFormat (required). The default constructor will guard that the string is of one of the following formats:
  • Default
  • Alpha
  • AlphaWithUnderscore
  • AlphaNumeric
  • AlphaNumericWithUnderscore
• stringComparison (required). Configures the way strings should be compared, see StringComparison.
• stringCaseConversion (optional). Configures if the string should be converted to LowerInvariant or UpperInvariant automatically. Default: NoConversion.

Simple value object example

To create a simple PlayerAge value object. Write the following code:

It will generate the following code:

String value object example

The Uuid provided in this package is created using dogfooding principles. It is implemented as follows:

This results in the following generated code:

Tuple value object example

The ValidationExceptionMessage used in this package is also created using dogfooding principles. It is implemented as follows:

This generates the following code:

Generic type example

Unfortunately, attribute type arguments cannot use type parameters. In case you want to create a open generic default value object, just add a type parameter to the definition of the type and the type provided in the attribute will be overwritten.

⚠️ As you can see in the example above, non-generic attributes can aso be used to generate value object. Use these non-generic attributes for Blazor WebAssembly, because at the moment generic attributes don't work there: https://github.com/dotnet/runtime/issues/77047.

Identities

Entities require a unique identity (ID) in order to be distinguished from other entities. Each entity should have it's strongly typed ID. It's important that the scope in which the ID should unique is taken into consideration before implementing them. The underlying value of an identity should implement IEquatable. It can be one of the following types:

• A primitive type (like string, ulong, int, byte, etc.).
• A (custom implemented) ValueObject.
• A Guid.
• A Uuid (which is included in this package, see Simple value object example): a 32-digit UUID without hyphens.
• Any other struct which implements IEquatable.

Identities can be implemented correctly by using one of the following methods (ordered by preference):

• Use the Identity generator. This way you can create a readonly struct (which probably lives on the stack).
• Implementing the abstract record IdBase. Not recommended as this creates a reference type.
• Implementing IId. Not recommended as Equals and GetHashCode should manually correctly be implemented.

A SingletonId<TObject> is also supported. This is convenient for implementing IDs of objects that only have one ID per type.

To enable correct JSON serialization of identities, add the following line to your Program.cs

builder.Services.AddIdentityJsonSerialization();

Identity generator

An identity belongs to an entity. To create an identity for an entity, simply make the class partial and add the attribute GenerateIdentity<T> (where T is the underlying value). The type parameter <T> can also be omitted. In this case the underlying value of the identity will be ulong. A readonly partial struct will be generated which is nested in the entity class. The entity will also get a property which contains an instance of the identity. Two parameters can be provided when adding the attribute:

• name. If provided, this will be the name of the identity. The default name is Identity.
• propertyName. The name of the identity-property of the entity class. The default name is Id.

If entity Player has a GenerateIdentity-attribute (with default arguments):

• Player.Identity references the identity type.
• Player.Id references the instance of the identity.

Entity with identity example

The following example will generate a strongly typed identity for entity Player:

The following code will be generated:

Miscellaneous

ToDisplayString

An extension method on IDomainObject which can be used when overriding ToString. It creates a display string of the domain object by serializing it and changing the ':' to '='. The value returned can be configured by providing an anonymous object to customize the string. If omitted, it will create a string of all fields and properties of the class/struct. For example, to only show the ID of an entity, use:

Tuple iterator

Iterates each value of a ValueTuple.

Range iterator

A custom easy-to-use number iterator which uses the Ranges-feature (introduced in C# 8).

Will write:

ValueTuple JSON converter

To enable correct JSON serialization of value tuples, add the following line to Program.cs

builder.Services.AddValueTupleJsonSerialization();

Global using generator

This packages automatically generates global usings for namespaces in this package. Namespaces in this file are often referenced when domain modeling and do not have to be manually referenced anymore.