Vogen 3.0.12

.NET 7.0 .NET Standard 2.0
dotnet add package Vogen --version 3.0.12
NuGet\Install-Package Vogen -Version 3.0.12
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Vogen" Version="3.0.12" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Vogen --version 3.0.12
#r "nuget: Vogen, 3.0.12"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Vogen as a Cake Addin
#addin nuget:?package=Vogen&version=3.0.12

// Install Vogen as a Cake Tool
#tool nuget:?package=Vogen&version=3.0.12

Vogen - Value Object Generator

What is the package?

This is a semi-opinionated library which is a Source Generator to generate Value Objects. The main goal is that the Value Objects generated have almost the same speed and memory performance as using primitives.

The Value Objects wrap simple primitives such as int, string, double etc.

To get started, add this package, and add a type such as:

[ValueObject(typeof(int))]
public partial struct CustomerId 
{
}

You can now treat CustomerId as you would an int and there is very little performance difference between the two:

var id = CustomerId.From(42);

And your method signatures change from:

public void HandleCustomer(int customerId)`

to

public void HandleCustomer(CustomerId customerId)`

The Source Generator generates code for things like creating the object and for performing equality.

Value Objects help combat Primitive Obsession. Primitive Obsession 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 have Age age. Age might have validation that it couldn't be negative
  • instead of string postcode - we'd have Postcode postcode. Postcode might have validation on the format of the text

The opinions are expressed as:

  • 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 private static method named Validate that returns a Validation result
  • Any validation that is not Validation.Ok results in a ValueObjectValidationException being thrown

Instead of

int customerId = 42;

... we'd have

var customerId = CustomerId.From(42);

CustomerId is declared as:

[ValueObject(typeof(int))]
public partial struct CustomerId 
{
}

That's all you need to do to switch from a primitive to a Value Object.

Here it is again with some validation

[ValueObject(typeof(int))]
public partial struct CustomerId 
{
    private static Validation Validate(int value) => 
        value > 0 ? Validation.Ok : Validation.Invalid(); 
}

This allows us to have more strongly typed domain objects instead of primitives, which makes the code easier to read and enforces better method signatures, so instead of:

public void DoSomething(int customerId, int supplierId, int amount)

we can have:

public void DoSomething(CustomerId customerId, SupplierId supplierId, Amount amount)

Now, callers can't mess up the ordering of parameters and accidentally pass us a Supplier ID in place of a Customer ID.

It also means that validation is in just one place. You can't introduce bad objects into your domain, therefore you can assume that in your domain every ValueObject is valid.

Adding the package

Add the package to your application using

dotnet add package Vogen

This adds a <PackageReference> to your project. You can additionally mark the package as PrivateAssets="all" and ExcludeAssets="runtime".

Setting PrivateAssets="all" means any projects referencing this one won't get a reference to the Vogen package. Setting ExcludeAssets="runtime" ensures the Vogen.SharedTypes.dll file is not copied to your build output (it is not required at runtime).

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  
  <PackageReference Include="Vogen" Version="1.0.9" 
    PrivateAssets="all" ExcludeAssets="runtime" />
  

</Project>

How does it compare to using native types?

Here's the benchmarks comparing a native int to a ValueObject:

|                  Method |     Mean |    Error |   StdDev | Ratio | Allocated |
|------------------------ |---------:|---------:|---------:|------:|----------:|
|        UsingIntNatively | 17.04 ns | 0.253 ns | 0.014 ns |  1.00 |         - |
|  UsingValueObjectStruct | 19.76 ns | 2.463 ns | 0.135 ns |  1.16 |         - |

There's hardly any speed overhead, and no memory overhead.

The next most common scenario is using a VO class to represent a natits are:

|                   Method |     Mean |    Error |  StdDev | Ratio | Allocated |
|------------------------- |---------:|---------:|--------:|------:|----------:|
|      UsingStringNatively | 204.4 ns |  8.09 ns | 0.44 ns |  1.00 |     256 B |
|  UsingValueObjectAsClass | 250.7 ns | 29.97 ns | 1.64 ns |  1.23 |     328 B |
| UsingValueObjectAsStruct | 248.9 ns | 18.82 ns | 1.03 ns |  1.22 |     304 B |
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48 net481
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.
  • net7.0

    • No dependencies.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on Vogen:

Package Downloads
HarvestForecast.Client

HarvestForecast.Client is an unofficial client library for the HarvestForecast API. Just add an access token and get started straight away!

Vogen.Serialization

Provides serialization support between Vogen and Newtonsoft.Json

GameFinder.Wine

Library for finding Wine prefixes.

Vogen.Serialization.TestTypes

Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Vogen:

Repository Stars
SteveDunn/PacManBlazor
PACMAN in Blazor WebAssembly
Version Downloads Last updated
3.0.12 11,389 1/30/2023
3.0.11 2,672 1/24/2023
3.0.10 288 1/14/2023
3.0.9 590 12/29/2022
3.0.8 171 12/27/2022
3.0.7 2,009 12/16/2022
3.0.6 270 12/10/2022
3.0.5 495 11/26/2022
3.0.4 11,860 11/7/2022
3.0.3 291 10/30/2022
3.0.2-alpha.2 64 10/12/2022
3.0.2-alpha 63 10/11/2022
3.0.1 388 10/8/2022
2.0.5 719 9/29/2022
2.0.4 256 9/28/2022
2.0.3 3,857 7/27/2022
2.0.2 284 7/27/2022
1.0.25 668 7/25/2022
1.0.24 315 7/24/2022
1.0.23 332 7/21/2022
1.0.22 1,187 6/18/2022
1.0.21 1,758 5/13/2022
1.0.20 364 5/3/2022
1.0.19 340 4/25/2022
1.0.18 7,663 2/21/2022
1.0.17 291 2/6/2022
1.0.16-alpha.1 95 1/29/2022
1.0.15 385 1/2/2022
1.0.12 191 12/28/2021
1.0.11 175 12/28/2021
1.0.9 716 12/11/2021
1.0.8 205 12/6/2021
1.0.7 189 12/5/2021
1.0.6 748 12/3/2021
1.0.5 181 12/2/2021
1.0.4 183 12/2/2021
1.0.3 185 12/1/2021
1.0.2 177 12/1/2021
1.0.1 200 12/1/2021
1.0.1-alpha.0.2 99 12/1/2021
0.0.0-alpha.0 94 1/2/2022