Vogen 5.0.0-beta.1
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
<PackageReference Include="Vogen" Version="5.0.0-beta.1" />
paket add Vogen --version 5.0.0-beta.1
#r "nuget: Vogen, 5.0.0-beta.1"
// 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 haveAge age
.Age
might have validation that it couldn't be negative - instead of
string postcode
- we'd havePostcode 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 aValidation
result - Any validation that is not
Validation.Ok
results in aValueObjectValidationException
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. SettingExcludeAssets="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 | Versions 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. |
-
.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.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 |