Vogen 3.0.25-beta.1

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

// Install Vogen as a Cake Tool
#tool nuget:?package=Vogen&version=3.0.25-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(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 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.
  • net8.0

    • No dependencies.

NuGet packages (9)

Showing the top 5 NuGet packages that depend on Vogen:

Package Downloads
NexusMods.Paths

Package Description

NexusMods.Hashing.xxHash64

Nexus Mods' Implementation of the xxHash64 algorithm.

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

GitHub repositories (2)

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

Repository Stars
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
3.0.25-beta.1 245 2/20/2024
3.0.24 54,511 1/9/2024
3.0.23 69,330 11/3/2023
3.0.23-beta.2 62 11/1/2023
3.0.23-beta.1 56 11/1/2023
3.0.22 7,473 10/23/2023
3.0.21 92,056 8/31/2023
3.0.20 141,180 7/17/2023
3.0.19 29,496 6/5/2023
3.0.18 10,572 5/30/2023
3.0.17 255 5/29/2023
3.0.16 10,670 5/9/2023
3.0.15 14,876 4/14/2023
3.0.14 1,779 4/13/2023
3.0.13 2,761 3/29/2023
3.0.12 48,150 1/30/2023
3.0.11 4,040 1/24/2023
3.0.10 476 1/14/2023
3.0.9 4,135 12/29/2022
3.0.8 326 12/27/2022
3.0.7 2,237 12/16/2022
3.0.6 425 12/10/2022
3.0.5 636 11/26/2022
3.0.4 12,115 11/7/2022
3.0.3 442 10/30/2022
3.0.2-alpha.2 108 10/12/2022
3.0.2-alpha 114 10/11/2022
3.0.1 578 10/8/2022
2.0.5 909 9/29/2022
2.0.4 410 9/28/2022
2.0.3 4,376 7/27/2022
2.0.2 433 7/27/2022
1.0.25 1,109 7/25/2022
1.0.24 469 7/24/2022
1.0.23 475 7/21/2022
1.0.22 1,461 6/18/2022
1.0.21 1,946 5/13/2022
1.0.20 525 5/3/2022
1.0.19 501 4/25/2022
1.0.18 12,620 2/21/2022
1.0.17 447 2/6/2022
1.0.16-alpha.1 136 1/29/2022
1.0.15 1,019 1/2/2022
1.0.12 304 12/28/2021
1.0.11 271 12/28/2021
1.0.9 1,663 12/11/2021
1.0.8 305 12/6/2021
1.0.7 298 12/5/2021
1.0.6 853 12/3/2021
1.0.5 297 12/2/2021
1.0.4 264 12/2/2021
1.0.3 294 12/1/2021
1.0.2 293 12/1/2021
1.0.1 459 12/1/2021
1.0.1-alpha.0.2 143 12/1/2021
0.0.0-alpha.0 143 1/2/2022