Skip to main content

UnitGenerator by Cysharp, Inc

Nuget / site data​

Nuget GitHub last commit GitHub Repo stars

Details​

Info​

info

Name: UnitGenerator

C# Source Generator to create value-object, inspired by units of measure.

Author: Cysharp, Inc

NuGet: https://www.nuget.org/packages/UnitGenerator/

You can find more details at https://github.com/Cysharp/UnitGenerator

Source : https://github.com/Cysharp/UnitGenerator

Original Readme​

note

UnitGenerator

GitHub Actions Releases

C# Source Generator to create Value object pattern, also inspired by units of measure to support all arithmetic operators and serialization.

NuGet: UnitGenerator

Install-Package UnitGenerator

Introduction​

For example, Identifier, UserId is comparable only to UserId, and cannot be assigned to any other type. Also, arithmetic operations are not allowed.

using UnitGenerator;

[UnitOf(typeof(int))]
public readonly partial struct UserId { }

will generates

[System.ComponentModel.TypeConverter(typeof(UserIdTypeConverter))]
public readonly partial struct UserId : IEquatable<UserId> 
{
    readonly int value;
    
    public UserId(int value)
    {
        this.value = value;
    }

    public readonly int AsPrimitive() => value;
    public static explicit operator int(UserId value) => value.value;
    public static explicit operator UserId(int value) => new UserId(value);
    public bool Equals(UserId other) => value.Equals(other.value);
    public override bool Equals(object? obj) => // snip...
    public override int GetHashCode() => value.GetHashCode();
    public override string ToString() => value.ToString();
    public static bool operator ==(in UserId x, in UserId y) => x.value.Equals(y.value);
    public static bool operator !=(in UserId x, in UserId y) => !x.value.Equals(y.value);

    private class UserIdTypeConverter : System.ComponentModel.TypeConverter
    {
        // snip...
    }
}

However, Hp in games, should not be allowed to be assigned to other types, but should support arithmetic operations with int. For example double heal = target.Hp = Hp.Min(target.Hp * 2, target.MaxHp).

[UnitOf(typeof(int), UnitGenerateOptions.ArithmeticOperator | UnitGenerateOptions.ValueArithmeticOperator | UnitGenerateOptions.Comparable | UnitGenerateOptions.MinMaxMethod)]
public readonly partial struct Hp { }

// -- generates

[System.ComponentModel.TypeConverter(typeof(HpTypeConverter))]
public readonly partial struct Hp
    : IEquatable<Hp>
#if NET7_0_OR_GREATER
    , IEqualityOperators<Hp, Hp, bool>
#endif    
    , IComparable<Hp>
#if NET7_0_OR_GREATER
    , IComparisonOperators<Hp, Hp, bool>
#endif
#if NET7_0_OR_GREATER
    , IAdditionOperators<Hp, Hp, Hp>
    , ISubtractionOperators<Hp, Hp, Hp>
    , IMultiplyOperators<Hp, Hp, Hp>
    , IDivisionOperators<Hp, Hp, Hp>
    , IUnaryPlusOperators<Hp, Hp>
    , IUnaryNegationOperators<Hp, Hp>
    , IIncrementOperators<Hp>
    , IDecrementOperators<Hp>
#endif    
{
    readonly int value;

    public Hp(int value)
    {
        this.value = value;
    }

    public int AsPrimitive() => value;
    public static explicit operator int(Hp value) => value.value;
    public static explicit operator Hp(int value) => new Hp(value);
    public bool Equals(Hp other) => value.Equals(other.value);
    public override bool Equals(object? obj) => // snip...
    public override int GetHashCode() => value.GetHashCode();
    public override string ToString() => value.ToString();
    public static bool operator ==(in Hp x, in Hp y) => x.value.Equals(y.value);
    public static bool operator !=(in Hp x, in Hp y) => !x.value.Equals(y.value);
    private class HpTypeConverter : System.ComponentModel.TypeConverter { /* snip... */ }

    // UnitGenerateOptions.ArithmeticOperator
    public static Hp operator +(Hp x, Hp y) => new Hp(checked((int)(x.value + y.value)));
    public static Hp operator -(Hp x, Hp y) => new Hp(checked((int)(x.value - y.value)));
    public static Hp operator *(Hp x, Hp y) => new Hp(checked((int)(x.value * y.value)));
    public static Hp operator /(Hp x, Hp y) => new Hp(checked((int)(x.value / y.value)));
    public static Hp operator ++(Hp x) => new Hp(checked((int)(x.value + 1)));
    public static Hp operator --(Hp x) => new Hp(checked((int)(x.value - 1)));
    public static Hp operator +(A value) => new((int)(+value.value));
    public static Hp operator -(A value) => new((int)(-value.value));

    // UnitGenerateOptions.ValueArithmeticOperator
    public static Hp operator +(Hp x, in int y) => new Hp(checked((int)(x.value + y)));
    public static Hp operator -(Hp x, in int y) => new Hp(checked((int)(x.value - y)));
    public static Hp operator *(Hp x, in int y) => new Hp(checked((int)(x.value * y)));
    public static Hp operator /(Hp x, in int y) => new Hp(checked((int)(x.value / y)));

    // UnitGenerateOptions.Comparable
    public int CompareTo(Hp other) => value.CompareTo(other.value);
    public static bool operator >(Hp x, Hp y) => x.value > y.value;
    public static bool operator <(Hp x, Hp y) => x.value < y.value;
    public static bool operator >=(Hp x, Hp y) => x.value >= y.value;
    public static bool operator <=(Hp x, Hp y) => x.value <= y.value;

    // UnitGenerateOptions.MinMaxMethod
    public static Hp Min(Hp x, Hp y) => new Hp(Math.Min(x.value, y.value));
    public static Hp Max(Hp x, Hp y) => new Hp(Math.Max(x.value, y.value));
}

You can configure with UnitGenerateOptions, which method to implement.

[Flags]
enum UnitGenerateOptions
{
    None = 0,
    ImplicitOperator = 1,
    ParseMethod = 1 << 1,
    MinMaxMethod = 1 << 2,
    ArithmeticOperator = 1 << 3,
    ValueArithmeticOperator = 1 << 4,
    Comparable = 1 << 5,
    Validate = 1 << 6,
    JsonConverter = 1 << 7,
    MessagePackFormatter = 1 << 8,
    DapperTypeHandler = 1 << 9,
    EntityFrameworkValueConverter = 1 << 10,
    WithoutComparisonOperator = 1 << 11,
    JsonConverterDictionaryKeySupport = 1 << 12,
    Normalize = 1 << 13,
}

UnitGenerateOptions has some serializer support. For example, a result like Serialize(userId) => { Value = 1111 } is awful. The value-object should be serialized natively, i.e. Serialize(useId) => 1111, and should be able to be added directly to a database, etc.

Currently UnitGenerator supports MessagePack for C#, System.Text.Json(JsonSerializer), Dapper and EntityFrameworkCore.

[UnitOf(typeof(int), UnitGenerateOptions.MessagePackFormatter)]
public readonly partial struct UserId { }

// -- generates

[MessagePackFormatter(typeof(UserIdMessagePackFormatter))]
public readonly partial struct UserId 
{
    class UserIdMessagePackFormatter : IMessagePackFormatter<UserId>
    {
        public void Serialize(ref MessagePackWriter writer, UserId value, MessagePackSerializerOptions options)
        {
            options.Resolver.GetFormatterWithVerify<int>().Serialize(ref writer, value.value, options);
        }

        public UserId Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
        {
            return new UserId(options.Resolver.GetFormatterWithVerify<int>().Deserialize(ref reader, options));
        }
    }
}

Table of Contents​

UnitOfAttribute​

When referring to the UnitGenerator, it generates a internal UnitOfAttribute.

namespace UnitGenerator
{
    [AttributeUsage(AttributeTargets.Struct, AllowMultiple = false)]
    internal class UnitOfAttribute : Attribute
    {
        public Type Type { get; }
        public UnitGenerateOptions Options { get; }
        public UnitArithmeticOperators ArithmeticOperators { get; set; }
        public string ToStringFormat { get; set; }
        
        public UnitOfAttribute(Type type, UnitGenerateOptions options = UnitGenerateOptions.None) { ... }
    }
}

You can attach this attribute with any specified underlying type to readonly partial struct.

[UnitOf(typeof(Guid))]
public readonly partial struct GroupId { }

[UnitOf(typeof(string))]
public readonly partial struct Message { }

[UnitOf(typeof(long))]
public readonly partial struct Power { }

[UnitOf(typeof(byte[]))]
public readonly partial struct Image { }

[UnitOf(typeof(DateTime))]
public readonly partial struct StartDate { }

[UnitOf(typeof((string street, string city)))]
public readonly partial struct StreetAddress { }

Standard UnitOf(UnitGenerateOptions.None) generates value constructor, explicit operator, implement IEquatable , override GetHashCode, override ToString, == and != operator, TypeConverter for ASP.NET Core binding, AsPrimitive method.

If you want to retrieve primitive value, use AsPrimitive() instead of .Value. This is intended to avoid casual getting of primitive values (using the arithmetic operator option if available).

When type is bool, also implements true, false, ! operators.

public static bool operator true(Foo x) => x.value;
public static bool operator false(Foo x) => !x.value;
public static bool operator !(Foo x) => !x.value;

When type is Guid or Ulid, also implements New() and New***() static operator.

public static GroupId New();
public static GroupId NewGroupId();

Second parameter UnitGenerateOptions options can configure which method to implement, default is None.

Optional named parameter: ArithmeticOperators can configure which generates operators specifically. Default is Number. (This can be used if UnitGenerateOptions.ArithmeticOperator is specified.)

Optional named parameter: ToStringFormat can configure ToString format. Default is null and output as ${0}.

UnitGenerateOptions​

When referring to the UnitGenerator, it generates a internal UnitGenerateOptions that is bit flag of which method to implement.

[Flags]
internal enum UnitGenerateOptions
{
    None = 0,
    ImplicitOperator = 1,
    ParseMethod = 2,
    MinMaxMethod = 4,
    ArithmeticOperator = 8,
    ValueArithmeticOperator = 16,
    Comparable = 32,
    Validate = 64,
    JsonConverter = 128,
    MessagePackFormatter = 256,
    DapperTypeHandler = 512,
    EntityFrameworkValueConverter = 1024,
}

You can use this with [UnitOf].

[UnitOf(typeof(int), UnitGenerateOptions.ArithmeticOperator | UnitGenerateOptions.ValueArithmeticOperator | UnitGenerateOptions.Comparable | UnitGenerateOptions.MinMaxMethod)]
public readonly partial struct Strength { }

[UnitOf(typeof(DateTime), UnitGenerateOptions.Validate | UnitGenerateOptions.ParseMethod | UnitGenerateOptions.Comparable)]
public readonly partial struct EndDate { }

[UnitOf(typeof(double), UnitGenerateOptions.ParseMethod | UnitGenerateOptions.MinMaxMethod | UnitGenerateOptions.ArithmeticOperator | UnitGenerateOptions.ValueArithmeticOperator | UnitGenerateOptions.Comparable | UnitGenerateOptions.Validate | UnitGenerateOptions.JsonConverter | UnitGenerateOptions.MessagePackFormatter | UnitGenerateOptions.DapperTypeHandler | UnitGenerateOptions.EntityFrameworkValueConverter)]
public readonly partial struct AllOptionsStruct { }

You can setup project default options like this.

internal static class UnitOfOptions
{
    public const UnitGenerateOptions Default = UnitGenerateOptions.ArithmeticOperator | UnitGenerateOptions.ValueArithmeticOperator | UnitGenerateOptions.Comparable | UnitGenerateOptions.MinMaxMethod;
}

[UnitOf(typeof(int), UnitOfOptions.Default)]
public readonly partial struct Hp { }

ImplicitOperator​

// Default
public static explicit operator U(T value) => value.value;
public static explicit operator T(U value) => new T(value);

// UnitGenerateOptions.ImplicitOperator
public static implicit operator U(T value) => value.value;
public static implicit operator T(U value) => new T(value);

ParseMethod​

public static T Parse(string s)
public static bool TryParse(string s, out T result)

MinMaxMethod​

public static T Min(T x, T y)
public static T Max(T x, T y)

ArithmeticOperator​

public static T operator +(in T x, in T y) => new T(checked((U)(x.value + y.value)));
public static T operator -(in T x, in T y) => new T(checked((U)(x.value - y.value)));
public static T operator *(in T x, in T y) => new T(checked((U)(x.value * y.value)));
public static T operator /(in T x, in T y) => new T(checked((U)(x.value / y.value)));
public static T operator +(T value) => new((U)(+value.value));
public static T operator -(T value) => new((U)(-value.value));
public static T operator ++(T x) => new T(checked((U)(x.value + 1)));
public static T operator --(T x) => new T(checked((U)(x.value - 1)));

In addition, all members conforming to System.Numerics.INumber are generated.

If you want to suppress this and generate only certain operators, you can use the the ArithmeticOperatros option of [UnitOf] attribute as follows:

[UnitOf(
    typeof(int), 
    UnitGenerateOptions.ArithmeticOperator,
    ArithmeticOperators = UnitArithmeticOperators.Addition | UnitArithmeticOperators.Subtraction)]
public readonly partial struct Hp { }
ValueGenerates
UnitArithmeticOperators.AdditionT operator +(T, T)
UnitArithmeticOperators.SubtractionT operator -(T, T)
UnitArithmeticOperators.MultiplyT operator *(T, T), T operator +(T), T operator-(T)
UnitArithmeticOperators.DivisionT operator /(T, T), T operator +(T), T operator-(T)
UnitArithmeticOperators.IncrementT operator ++(T)
UnitArithmeticOperators.DecrementT operator --(T)

ValueArithmeticOperator​

public static T operator +(in T x, in U y) => new T(checked((U)(x.value + y)));
public static T operator -(in T x, in U y) => new T(checked((U)(x.value - y)));
public static T operator *(in T x, in U y) => new T(checked((U)(x.value * y)));
public static T operator /(in T x, in U y) => new T(checked((U)(x.value / y)));

Comparable​

Implements IComparable and >, <, >=, <= operators.

public U CompareTo(T other) => value.CompareTo(other.value);
public static bool operator >(in T x, in T y) => x.value > y.value;
public static bool operator <(in T x, in T y) => x.value < y.value;
public static bool operator >=(in T x, in T y) => x.value >= y.value;
public static bool operator <=(in T x, in T y) => x.value <= y.value;

WithoutComparisonOperator​

Without implements >, <, >=, <= operators. For example, useful for Guid.

[UnitOf(typeof(Guid), UnitGenerateOptions.Comparable | UnitGenerateOptions.WithoutComparisonOperator)]
public readonly partial struct FooId { }

Validate​

Implements partial void Validate() method that is called on constructor.

// You can implement this custom validate method.
[UnitOf(typeof(int), UnitGenerateOptions.Validate)]
public readonly partial struct SampleValidate
{
    // impl here.
    private partial void Validate()
    {
        if (value > 9999) throw new Exception("Invalid value range: " + value);
    }
}

// Source generator generate this codes.
public T(int value)
{
    this.value = value;
    this.Validate();
}
 
private partial void Validate();

Normalize​

Implements partial void Normalize(ref T value) method that is called on constructor.

// You can implement this custom normalize method to change value during initialization
[UnitOf(typeof(int), UnitGenerateOptions.Normalize)]
public readonly partial struct SampleValidate
{
    // impl here.
    private partial void Normalize(ref int value)
    {
        value = Math.Max(value, 9999);
    }
}

// Source generator generate this codes.
public T(int value)
{
    this.value = value;
    this.Normalize(ref this.value);
}
 
private partial void Normalize(ref int value);

JsonConverter​

Implements System.Text.Json's JsonConverter. It will be used JsonSerializer automatically.

[JsonConverter(typeof(UserIdJsonConverter))]
public readonly partial struct UserId
{
    class UserIdJsonConverter : JsonConverter<UserId>
}

JsonConverterDictionaryKeySupport​

Implements JsonConverter's WriteAsPropertyName/ReadAsPropertyName. It supports from .NET 6, supports Dictionary's Key.

var dict = Dictionary<UserId, int>
JsonSerializer.Serialize(dict);

MessagePackFormatter​

Implements MessagePack for C#'s MessagePackFormatter. It will be used MessagePackSerializer automatically.

[MessagePackFormatter(typeof(UserIdMessagePackFormatter))]
public readonly partial struct UserId
{
    class UserIdMessagePackFormatter : IMessagePackFormatter<UserId>
}

DapperTypeHandler​

Implements Dapper's TypeHandler by public accessibility. TypeHandler is automatically registered at the time of Module initialization.

public readonly partial struct UserId
{
    public class UserIdTypeHandler : Dapper.SqlMapper.TypeHandler<UserId>
}

[ModuleInitializer]
public static void AddTypeHandler()
{
    Dapper.SqlMapper.AddTypeHandler(new A.ATypeHandler());
}

EntityFrameworkValueConverter​

Implements EntityFrameworkCore's ValueConverter by public accessibility. It is not registered automatically so you need to register manually.

public readonly partial struct UserId
{
    public class UserIdValueConverter : ValueConverter<UserId, int>
}

// setup handler manually
builder.HasConversion(new UserId.UserIdValueConverter());

Use for Unity​

C# Source Generator feature is rely on C# 9.0. If you are using Unity 2021.2, that supports Source Generators. Add the UnitGenerator.dll from the releases page, disable Any Platform, disable Include all platforms and set label as RoslynAnalyzer.

It works in Unity Editor however does not work on IDE because Unity does not generate analyzer reference to .csproj. We provides CsprojModifer to analyzer support, uses Add analyzer references to generated .csproj supports both IDE and Unity Editor.

Unity(2020) does not support C# 9.0 so can not use directly. However, C# Source Genertor supports output source as file.

  1. Create UnitSourceGen.csproj.
<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net5.0</TargetFramework>

        <!-- add this two lines and configure output path -->
        <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
        <CompilerGeneratedFilesOutputPath>$(ProjectDir)..\Generated</CompilerGeneratedFilesOutputPath>
    </PropertyGroup>

    <ItemGroup>
        <!-- reference UnitGenerator -->
        <PackageReference Include="UnitGenerator" Version="1.0.0" />

        <!-- add target sources path from Unity -->
        <Compile Include="..\MyUnity\Assets\Scripts\Models\**\*.cs" />
    </ItemGroup>
</Project>
  1. install .NET SDK and run this command.
dotnet build UnitSourceGen.csproj

File will be generated under UnitGenerator\UnitGenerator.SourceGenerator\*.Generated.cs. UnitOfAttribute is also included in generated folder, so at first, run build command and get attribute to configure.

License​

This library is under the MIT License.

About​

note

Generating classes instead of value objects( e.g. int)

How to use​

Example ( source csproj, source files )​

This is the CSharp Project that references UnitGenerator

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net7.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <PropertyGroup>
        <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
        <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GX</CompilerGeneratedFilesOutputPath>
    </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="UnitGenerator" Version="1.5.1">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

Generated Files​

Those are taken from $(BaseIntermediateOutputPath)\GX

// <auto-generated>
// THIS (.cs) FILE IS GENERATED BY UnitGenerator. DO NOT CHANGE IT.
// </auto-generated>
#pragma warning disable CS8669
using System;
using System.Globalization;
#if NET7_0_OR_GREATER
using System.Numerics;
#endif
namespace StronglyDemo
{
    [System.ComponentModel.TypeConverter(typeof(DayIdTypeConverter))]
    readonly partial struct DayId 
        : IEquatable<DayId>
#if NET7_0_OR_GREATER
        , IEqualityOperators<DayId, DayId, bool>
#endif    
    {
        readonly int value;

        public int AsPrimitive() => value;

        public DayId(int value)
        {
            this.value = value;
        }
        
        public static explicit operator int(DayId value)
        {
            return value.value;
        }

        public static explicit operator DayId(int value)
        {
            return new DayId(value);
        }

        public bool Equals(DayId other)
        {
            return value.Equals(other.value);
        }

        public override bool Equals(object obj)
        {
            if (obj == null) return false;
            var t = obj.GetType();
            if (t == typeof(DayId))
            {
                return Equals((DayId)obj);
            }
            if (t == typeof(int))
            {
                return value.Equals((int)obj);
            }

            return value.Equals(obj);
        }
        
        public static bool operator ==(DayId x, DayId y)
        {
            return x.value.Equals(y.value);
        }

        public static bool operator !=(DayId x, DayId y)
        {
            return !x.value.Equals(y.value);
        }

        public override int GetHashCode()
        {
            return value.GetHashCode();
        }

        public override string ToString() => value.ToString();

        // Default
        
        private class DayIdTypeConverter : System.ComponentModel.TypeConverter
        {
            private static readonly Type WrapperType = typeof(DayId);
            private static readonly Type ValueType = typeof(int);

            public override bool CanConvertFrom(System.ComponentModel.ITypeDescriptorContext context, Type sourceType)
            {
                if (sourceType == WrapperType || sourceType == ValueType)
                {
                    return true;
                }

                return base.CanConvertFrom(context, sourceType);
            }

            public override bool CanConvertTo(System.ComponentModel.ITypeDescriptorContext context, Type destinationType)
            {
                if (destinationType == WrapperType || destinationType == ValueType)
                {
                    return true;
                }

                return base.CanConvertTo(context, destinationType);
            }

            public override object ConvertFrom(System.ComponentModel.ITypeDescriptorContext context, System.Globalization.CultureInfo culture, object value)
            {
                if (value != null)
                {
                    var t = value.GetType();
                    if (t == typeof(DayId))
                    {
                        return (DayId)value;
                    }
                    if (t == typeof(int))
                    {
                        return new DayId((int)value);
                    }
                }

                return base.ConvertFrom(context, culture, value);
            }

            public override object ConvertTo(System.ComponentModel.ITypeDescriptorContext context, System.Globalization.CultureInfo culture, object value, Type destinationType)
            {
                if (value is DayId wrappedValue)
                {
                    if (destinationType == WrapperType)
                    {
                        return wrappedValue;
                    }

                    if (destinationType == ValueType)
                    {
                        return wrappedValue.AsPrimitive();
                    }
                }

                return base.ConvertTo(context, culture, value, destinationType);
            }
        }
    }
}

Usefull​

Download Example (.NET C# )​

tip

Download Example project UnitGenerator

Share UnitGenerator​

https://ignatandrei.github.io/RSCG_Examples/v2/docs/UnitGenerator

In the same category (PrimitiveObsession) - 4 other generators​

DomainPrimitives​

Strongly​

StronglyTypedUid​

Vogen​