Vogen 5.0.0-beta.1

This is a prerelease version of Vogen.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Vogen --version 5.0.0-beta.1                
NuGet\Install-Package Vogen -Version 5.0.0-beta.1                
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="5.0.0-beta.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Vogen --version 5.0.0-beta.1                
#r "nuget: Vogen, 5.0.0-beta.1"                
#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=5.0.0-beta.1&prerelease

// Install Vogen as a Cake Tool
#tool nuget:?package=Vogen&version=5.0.0-beta.1&prerelease                

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<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:

void HandleCustomer(int customerId)

to

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<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<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:

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

we can have:

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>net8.0</TargetFramework>
  </PropertyGroup>

  
  <PackageReference Include="Vogen" Version="4.0.0" 
    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 to represent a string:

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 Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages (9)

Showing the top 5 NuGet packages that depend on Vogen:

Package Downloads
Codehard.FileService.Contracts

An abstract contract for file service client and server.

PiBox.Hosting.Abstractions

PiBox is a `service hosting framework` that allows `.net devs` to `decorate their services with behaviours or functionality (think of plugins) while only using minimal configuration`.

Vogen.Serialization

Provides serialization support between Vogen and Newtonsoft.Json

HarvestForecast.Client

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

snkemp.Infrastructure

Package Description

GitHub repositories (3)

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

Repository Stars
JasperFx/marten
.NET Transactional Document DB and Event Store on PostgreSQL
SteveDunn/Vogen
A semi-opinionated library which is a source generator and a code analyser. It Source generates Value Objects
SteveDunn/PacManBlazor
PACMAN in Blazor WebAssembly
Version Downloads Last updated
5.0.3 5,754 9/26/2024
5.0.2 1,049 9/25/2024
5.0.1 1,138 9/23/2024
5.0.0-beta.1 186 9/9/2024
4.0.19 14,385 8/21/2024
4.0.18 975 8/17/2024
4.0.17 15,012 8/6/2024
4.0.16 1,497 7/30/2024
4.0.15 10,125 7/20/2024
4.0.14 5,295 7/16/2024
4.0.13 2,827 7/13/2024
4.0.12 15,269 6/21/2024
4.0.11 665 6/20/2024
4.0.10 710 6/19/2024
4.0.9 1,377 6/18/2024
4.0.8 18,241 5/30/2024
4.0.7 616 5/29/2024
4.0.6 7,047 5/27/2024
4.0.5 465 5/26/2024 4.0.5 is deprecated because it has critical bugs.
4.0.4 6,738 5/11/2024
4.0.3 2,997 5/8/2024
4.0.2 7,523 4/30/2024
4.0.1 439 4/29/2024
4.0.0 8,399 4/19/2024
3.0.25-beta.1 1,148 2/20/2024
3.0.24 183,825 1/9/2024
3.0.23 204,894 11/3/2023
3.0.23-beta.2 74 11/1/2023
3.0.23-beta.1 72 11/1/2023
3.0.22 9,196 10/23/2023
3.0.21 138,581 8/31/2023
3.0.20 203,095 7/17/2023
3.0.19 32,952 6/5/2023
3.0.18 10,618 5/30/2023
3.0.17 288 5/29/2023
3.0.16 11,665 5/9/2023
3.0.15 22,221 4/14/2023
3.0.14 1,961 4/13/2023
3.0.13 2,866 3/29/2023
3.0.12 58,874 1/30/2023
3.0.11 4,076 1/24/2023
3.0.10 514 1/14/2023
3.0.9 4,267 12/29/2022
3.0.8 358 12/27/2022
3.0.7 2,284 12/16/2022
3.0.6 458 12/10/2022
3.0.5 671 11/26/2022
3.0.4 12,171 11/7/2022
3.0.3 486 10/30/2022
3.0.2-alpha.2 120 10/12/2022
3.0.2-alpha 125 10/11/2022
3.0.1 607 10/8/2022
2.0.5 945 9/29/2022
2.0.4 435 9/28/2022
2.0.3 4,428 7/27/2022
2.0.2 465 7/27/2022
1.0.25 1,141 7/25/2022
1.0.24 497 7/24/2022
1.0.23 506 7/21/2022
1.0.22 1,531 6/18/2022
1.0.21 1,982 5/13/2022
1.0.20 553 5/3/2022
1.0.19 534 4/25/2022
1.0.18 13,399 2/21/2022
1.0.17 479 2/6/2022
1.0.16-alpha.1 146 1/29/2022
1.0.15 1,079 1/2/2022
1.0.12 335 12/28/2021
1.0.11 303 12/28/2021
1.0.9 1,712 12/11/2021
1.0.8 333 12/6/2021
1.0.7 323 12/5/2021
1.0.6 876 12/3/2021
1.0.5 322 12/2/2021
1.0.4 295 12/2/2021
1.0.3 321 12/1/2021
1.0.2 319 12/1/2021
1.0.1 801 12/1/2021
1.0.1-alpha.0.2 149 12/1/2021
0.0.0-alpha.0 150 1/2/2022