This is a .NET source generator and code analyser that generates strongly typed domain ideas. You provide this:
[ValueObject(typeof(int))]
public partial struct CustomerId {
// optional
private static Validation Validate(int value) => value > 0
? Validation.Ok
: Validation.Invalid("Customer IDs must be a positive number.");
}... and Vogen generates this:
public partial struct CustomerId : System.IEquatable<CustomerId> {
private readonly int _value;
public readonly int Value => _value;
public CustomerId() {
throw new Vogen.ValueObjectValidationException("Validation skipped by attempting to use the default constructor...");
}
private CustomerId(int value) => _value = value;
public static CustomerId From(int value) {
CustomerId instance = new CustomerId(value);
return instance;
}
public readonly bool Equals(CustomerId other) ...
public readonly bool Equals(int primitive) ...
public readonly override bool Equals(object obj) ...
public static bool operator ==(CustomerId left, CustomerId right) ...
public static bool operator !=(CustomerId left, CustomerId right) ...
public static bool operator ==(CustomerId left, int right) ...
public static bool operator !=(CustomerId left, int right) ...
public static bool operator ==(int left, CustomerId right) ...
public static bool operator !=(int left, CustomerId right) ...
public readonly override int GetHashCode() ...
public readonly override string ToString() ...
}You then use CustomerId instead of int in your domain in the full knowledge that it is valid and safe to use:
CustomerId customerId = CustomerId.From(123);
SendInvoice(customerId);
...
public void SendInvoice(CustomerId customerId) { ... }To ensure the validity of your value objects, the code analyser helps you avoid mistakes.
It does this by adding new constraints in the form of new compilation errors. For example, the analyser will spot issues when you declare a value object:
[ValueObject(typeof(int))]
public partial struct CustomerId {
// Vogen already generates this as a private constructor to that you can't use it:
// error CS0111: Type 'CustomerId' already defines a member called 'CustomerId' with the same parameter type
public CustomerId() { }
// error VOG008: Cannot have user defined constructors, please use the From method for creation.
public CustomerId(int value) { }
}... and it will spot issues when creating or consuming value objects:
// catches object creation expressions
var c = new CustomerId(); // error VOG010: Type 'CustomerId' cannot be constructed with 'new' as it is prohibited
CustomerId c = default; // error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
var c = default(CustomerId); // error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
var c = GetCustomerId(); // error VOG010: Type 'CustomerId' cannot be constructed with 'new' as it is prohibited
// catches lambda expressions
Func<CustomerId> f = () => default; // error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
// catches method / local function return expressions
CustomerId GetCustomerId() => default; // error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
CustomerId GetCustomerId() => new CustomerId(); // error VOG010: Type 'CustomerId' cannot be constructed with 'new' as it is prohibited
CustomerId GetCustomerId() => new(); // error VOG010: Type 'CustomerId' cannot be constructed with 'new' as it is prohibited
// catches argument / parameter expressions
Task<CustomerId> t = Task.FromResult<CustomerId>(new()); // error VOG010: Type 'CustomerId' cannot be constructed with 'new' as it is prohibited
void Process(CustomerId customerId = default) { } // error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.The main goal of this project is to achieve almost the same speed and memory performance as using primitives directly.
This is a Nuget package that contains a source generator and a code analyser. The analyser disallows code that could evade validation, meaning your types have more safety from invalid data.
The source generator generates Value Objects. Value Objects help combat Primitive Obsession by wrapping simple primitives such as int, string, double etc. in a strongly-typed type.
Primitive Obsession (AKA StringlyTyped) means being obsessed with primitives. It is a Code Smell that degrades the quality of software.
"Primitive Obsession is using primitive data types to represent domain ideas" #
Some examples:
- instead of
int age- we'd haveAge age.Agemight have validation that it couldn't be negative - instead of
string postcode- we'd havePostcode postcode.Postcodemight have validation on the format of the text
The source generator is opinionated. The opinions help ensure consistency. The opinions are:
- A Value Object (VO) is constructed via a factory method named
From, e.g.Age.From(12) - A VO is equatable (
Age.From(12) == Age.From(12)) - A VO, if validated, is validated with a static method named
Validatethat returns aValidationresult - Any validation that is not
Validation.Okresults in aValueObjectValidationExceptionbeing thrown
It is common to represent domain ideas as primitives, but primitives might not be able to fully describe the domain idea. To use Value Objects instead of primitives, we simply swap code like this:
public class CustomerInfo {
private int _id;
public CustomerInfo(int id) => _id = id;
}.. to this:
public class CustomerInfo {
private CustomerId _id;
public CustomerInfo(CustomerId id) => _id = id;
}There's a blog post here that describes it, but to summarise:
Primitive Obsession is being obsessed with the seemingly convenient way that primitives, such as
intsandstrings, allow us to represent domain objects and ideas.
It is this:
int customerId = 42What's wrong with that?
A customer ID likely cannot be fully represented by an int. An int can be negative or zero, but it's unlikely a customer ID can be. So, we have constraints on a customer ID. We can't represent or enforce those constraints on an int.
So, we need some validation to ensure the constraints of a customer ID are met. Because it's in int, we can't be sure if it's been checked beforehand, so we need to check it every time we use it. Because it's a primitive, someone might've changed the value, so even if we're 100% sure we've checked it before, it still might need checking again.
So far, we've used as an example, a customer ID of value 42. In C#, it may come as no surprise that "42 == 42" (I haven't checked that in JavaScript!). But, in our domain, should 42 always equal 42? Probably not if you're comparing a Supplier ID of 42 to a Customer ID of 42! But primitives won't help you here (remember, 42 == 42!).
(42 == 42) // true
(SuppliedId.From(42) == SupplierId.From(42)) // true
(SuppliedId.From(42) == VendorId.From(42)) // compilation errorBut sometimes, we need to denote that a Value Object isn't valid or hasn't been set. We don't want anyone outside of the object doing this as it could be used accidentally. It's common to have Unspecified instances, e.g.
public class Person {
public Age Age { get; } = Age.Unspecified;
}We can do that with an Instance attribute:
[ValueObject(typeof(int))]
[Instance("Unspecified", -1)]
public readonly partial struct Age {
public static Validation Validate(int value) =>
value > 0 ? Validation.Ok : Validation.Invalid("Must be greater than zero.");
}This generates public static Age Unspecified = new Age(-1);. The constructor is private, so only this type can (deliberately) create invalid instances.
Now, when we use Age, our validation becomes clearer:
public void Process(Person person) {
if(person.Age == Age.Unspecified) {
// age not specified.
}
}We can also specify other instance properties:
[ValueObject(typeof(int))]
[Instance("Freezing", 0)]
[Instance("Boiling", 100)]
public readonly partial struct Centigrade {
public static Validation Validate(float value) =>
value >= -273 ? Validation.Ok : Validation.Invalid("Cannot be colder than absolute zero");
}As mentioned previously, the goal of Vogen is to achieve very similar performance compare to using primitives themselves. Here's a benchmark comparing the use of a validated value object with underlying type of int vs using an int natively (primitively 🤓)
BenchmarkDotNet=v0.12.1, OS=Windows 10.0.22000
AMD Ryzen 9 5950X, 1 CPU, 32 logical and 16 physical cores
.NET Core SDK=6.0.100
[Host] : .NET Core 5.0.12 (CoreCLR 5.0.1221.52207, CoreFX 5.0.1221.52207), X64 RyuJIT
ShortRun : .NET Core 5.0.12 (CoreCLR 5.0.1221.52207, CoreFX 5.0.1221.52207), X64 RyuJIT
Job=ShortRun IterationCount=3 LaunchCount=1
WarmupCount=3
| Method | Mean | Error | StdDev | Ratio | Allocated |
|---|---|---|---|---|---|
| UsingIntNatively | 13.57 ns | 0.086 ns | 0.005 ns | 1.00 | - |
| UsingValueObjectStruct | 14.08 ns | 1.131 ns | 0.062 ns | 1.04 | - |
There is no discernable difference between using a native int and a VO struct; both are pretty much the same in terms of speed and memory.
The next most common scenario is using a VO class to represent a native String. These results are:
BenchmarkDotNet=v0.12.1, OS=Windows 10.0.22000
AMD Ryzen 9 5950X, 1 CPU, 32 logical and 16 physical cores
.NET Core SDK=6.0.100
[Host] : .NET Core 5.0.12 (CoreCLR 5.0.1221.52207, CoreFX 5.0.1221.52207), X64 RyuJIT
ShortRun : .NET Core 5.0.12 (CoreCLR 5.0.1221.52207, CoreFX 5.0.1221.52207), X64 RyuJIT
Job=ShortRun IterationCount=3 LaunchCount=1
WarmupCount=3
| Method | Mean | Error | StdDev | Ratio | RatioSD | Gen 0 | Allocated |
|---|---|---|---|---|---|---|---|
| UsingStringNatively | 135.4 ns | 16.89 ns | 0.93 ns | 1.00 | 0.00 | 0.0153 | 256 B |
| UsingValueObjectAsStruct | 171.8 ns | 14.40 ns | 0.79 ns | 1.27 | 0.01 | 0.0153 | 256 B |
There is a tiny amount of performance overhead, but these measurements are incredibly small. There is no memory overhead.
By default, each VO is decoarated with a TypeConverter and System.Text.Json (STJ) serializer. There are other converters/serialiazer for:
- Newtonsoft.Json (NSJ)
- Dapper
- EFCore
They are controlled by the Conversions enum. The following is has serializers for NSJ and STJ:
[ValueObject(conversions: Conversions.NewtonsoftJson | Conversions.SystemTextJson, underlyingType: typeof(float))]
public partial readonly struct Celsius { }If you don't want any conversions, then specify Conversions.None.
If you want your own conversion, then again specify none, and implement them yourself, just like any other type. But be aware that even serialisers will get the same compilation errors for new and default when trying to create VOs.
That doesn't give you validation. To validate Value, you can't use the shorthand syntax (Primary Constructor). So you'd need to do:
public record struct CustomerId
{
public CustomerId(int value) {
if(value <=0) throw new Exception(...)
}
}You might also provide other constructors which might not validate the data, thereby allowing invalid data into your domain. Those other constructors might not throw exception, or might throw different exceptions. One of the opinions in Vogen is that any invalid data given to a Value Object throws a ValueObjectValidationException.
You could also use default(CustomerId) to evade validation. In Vogen, there are analysers that catch this and fail the build, e.g:
// error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
CustomerId c = default;
// error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
var c2 = default(CustomerId);Yes, by referencing Vogen.Serialization.
You could, but to ensure consistency throughout your domain, you'd have to validate everywhere. And Shallow's Law says that that's not possible:
⚖️ Shalloway's Law "when N things need to change and N > 1, Shalloway will find at most N - 1 of these things."
Concretely: "When 5 things need to change, Shalloway will find at most, 4 of these things."
Yes. The analyser generates a compilation error.
Yes. The analyser generates a compilation error.
No. The parameter-less constructor is generated automatically, and the constructor that takes the underlying value is also generated automatically.
If you add further constructors, then you will get a compilation error from the code generator, e.g.
[ValueObject(typeof(int))]
public partial struct CustomerId {
// Vogen already generates this as a private constructor:
// error CS0111: Type 'CustomerId' already defines a member called 'CustomerId' with the same parameter type
public CustomerId() { }
// error VOG008: Cannot have user defined constructors, please use the From method for creation.
public CustomerId(int value) { }
}You could, but you'd get compiler warning CS0282-There is no defined ordering between fields in multiple declarations of partial class or struct 'type'
Implicit operators can be useful, but for Value Objects, they can confuse things. Take the following code without any implicit conversions:
Age age1 = Age.From(1);
OsVersion osVersion = OsVersion.From(1);
Console.WriteLine(age1 == osVersion); // won't compile! \o/That makes perfect sense. But adding in an implicit operator from Age to int, and it does compile!
Console.WriteLine(age1 == osVersion); // TRUE! (◎_◎;)
If we remove that implicit operator and replace it with an implicit operator from int to Age, it no longer compiles, which is great (we've got type safety back), but we end up violating the rules of implicit operators:
Predefined C# implicit conversions always succeed and never throw an exception. User-defined implicit conversions should behave in that way as well. If a custom conversion can throw an exception or lose information, define it as an explicit conversion
In my research, I read some other opinions, and noted that the guidelines listed in this answer say:
- If the conversion can throw an
InvalidCastexception, then it shouldn't be implicit. - If the conversion causes a heap allocation each time it is performed, then it shouldn't be implicit.
Which is interesting - Vogen wouldn't throw an InvalidCastException (only an ValueObjectValidationException). Also, for structs, we wouldn't create a heap allocation.
But since users of Vogen can declare a Value Object as a class or struct, then we wouldn't want implicit operators (from primitive => ValueObject) for just structs and not classes.
No, but you can provide them yourself. For certain types it would allow a much more natural way of expressing, er, expressions.
Although it can be confusing. Let's say there's a type like this (and imagine that there's implicit conversions to Age and to int'):
[ValueObject(typeof(int))]
public readonly partial struct Age
public static Validation Validate(int n) => n >= 0 ? Validation.Ok : Validation.Invalid("Must be zero or more");
}That says that Age instances can never be negative. So you would probably expect the following to throw, but it doesn't:
var age20 = Age.From(20);
var age10 = age20 / 2;
++age10;
age10 -= 12; // bang - goes negative??But no.. The implicit cast in var age10 = age20 / 2 results in an int and not an Age. Changing it to Age age10 = age20 / 2 fixes it. But this does go to show that it can be confusing.
If I'm using a library that uses Vogen, I'd like to easily tell if the type is just a primitive wrapper or not by the fact that it implements an interface, such as
IValidated<T>
Just like primitives have no interfaces, there's no need to have interfaces on Value Objects. The receiver that takes a CustomerId knows that it's a Value Object. If it were instead to take an IValidated<int>, then it wouldn't have any more information; you'd still have to know to call Value to get the value.
It might also relax type safety. Without the interface, we'd have signatures such as this:
public void SomSomething(CustomerId customerId, SupplierId supplierId, ProductId productId);... but with the interface, we could have signatures such as this:
public void SomSomething(IValidate<int> customerId, IValidated<int> supplierId, IValidated<int> productId);So, callers could mess things up by calling DoSomething(productId, supplierId, customerId))
There would also be no need to know if it's validated, as, if it's in your domain, it's valid (there's no way to manually create invalid instances). And with that said, there'd also be no point in exposing the 'Validate' method via the interface because validation is done at creation.
The term Value Object represents a small object whos equality is based on value and not identity. From Wikipedia
In computer science, a value object is a small object that represents a simple entity whose equality is not based on identity: i.e. two value objects are equal when they have the same value, not necessarily being the same object.
In DDD, a Value Object is (again, from Wikipedia)
... a value object is an immutable object that contains attributes but has no conceptual identity
Yes. You might want to represent special values for things like invalid or unspecified instances, e.g.
/*
* Instances are the only way to avoid validation, so we can create instances
* that nobody else can. This is useful for creating special instances
* that represent concepts such as 'invalid' and 'unspecified'.
*/
[ValueObject(typeof(int))]
[Instance("Unspecified", -1)]
[Instance("Invalid", -2)]
public readonly partial struct Age
{
private static Validation Validate(int value) =>
value > 0 ? Validation.Ok : Validation.Invalid("Must be greater than zero.");
}You can then use default values when using these types, e.g.
public class Person {
public Age Age { get; set; } = Age.Unspecified
}... and if you take an Age, you can compare it to an instance that is invalid/unspecified
public void CanEnter(Age age) {
if(age == Age.Unspecified || age == Age.Invalid) throw CannotEnterException("Name not specified or is invalid")
return age < 17;
}It would be great if it was, but it's not currently. I wrote an article about it, but in summary, there is a long-standing language proposal focusing on non-defaultable value types. Having non-defaultable value types is a great first step, but it would also be handy to have something in the language to enforce validate. So I added a language proposal for invariant records.
One of the responses in the proposal says that the language team decided that validation policies should not be part of C#, but provided by source generators.
dotnet run -c Release -- --job short --filter *
Any type can be wrapped. Serialisation and type conversions have implementations for:
-
string
-
int
-
long
-
short
-
byte
-
float (Single)
-
decimal
-
double
-
DateTime
-
DateTimeOffset
-
Guid
-
bool
For other types, a generic type conversion and serialiser is applied. If you are supplying your own converters for type conversion and serialization, then specify None for converters and decorate your type with attributes for your own types, e.g.
[ValueObject(typeof(SpecialPrimitive), conversions: Conversions.None)]
[System.Text.Json.Serialization.JsonConverter(typeof(SpecialPrimitiveJsonConverter))]
[System.ComponentModel.TypeConverter(typeof(SpecialPrimitiveTypeConverter))]
public partial struct SpecialMeasurement { }