luis-sousa-pinto / ulid

Fast .NET C# Implementation of ULID for .NET Core and Unity.

Ulid

Fast C# Implementation of ULID for .NET Core and Unity. Ulid is sortable, random id generator. This project aims performance by fastest binary serializer(MessagePack-CSharp) technology. It achives faster generate than Guid.NewGuid.

NuGet: Ulid or download .unitypackage from Ulid/Releases page.

Install-Package Ulid

Table of Contents

• How to use
• Performance
• Cli
• Integrate
• License

How to use

Similar api to Guid.

• Ulid.NewUlid()
• Ulid.Parse()
• Ulid.TryParse()
• new Ulid()
• .ToString()
• .ToByteArray()
• .TryWriteBytes()
• .TryWriteStringify()
• .ToBase64()
• .Time
• .Random

Performance

Guid is standard corelib guid. Ulid is this library. NUlid is competitor RobThree/NUlid.

• New

Method	Mean	Error	Ratio	Gen 0/1k Op	Gen 1/1k Op	Gen 2/1k Op	Allocated Memory/Op
Guid_	73.13 ns	NA	1.00	-	-	-	-
Ulid_	65.41 ns	NA	0.89	-	-	-	-
NUlid_	209.89 ns	NA	2.87	0.0162	-	-	104 B

Ulid.NewUlid() is faster than Guid.NewGuid() and zero allocation.

• Parse

Method	Mean	Error	Ratio	Gen 0/1k Op	Gen 1/1k Op	Gen 2/1k Op	Allocated Memory/Op
Guid_	197.98 ns	NA	1.00	-	-	-	-
Ulid_	28.67 ns	NA	0.14	-	-	-	-
NUlid_	161.03 ns	NA	0.81	0.0441	-	-	280 B

from string(Base32) to ulid, Ulid.Parse(string) is fastest and zero allocation.

• ToString

Method	Mean	Error	Ratio	Gen 0/1k Op	Gen 1/1k Op	Gen 2/1k Op	Allocated Memory/Op
Guid_	57.73 ns	NA	1.00	0.0163	-	-	104 B
Ulid_	38.77 ns	NA	0.67	0.0126	-	-	80 B
NUlid_	96.76 ns	NA	1.68	0.0583	-	-	368 B

to string representation(Base32), Ulid.ToString() is fastest and less allocation.

• NewId().ToString()

Method	Mean	Error	Ratio	Gen 0/1k Op	Gen 1/1k Op	Gen 2/1k Op	Allocated Memory/Op
Guid_	205.7 ns	NA	1.00	0.0162	-	-	104 B
Ulid_	110.2 ns	NA	0.54	0.0125	-	-	80 B
NUlid_	301.7 ns	NA	1.47	0.0744	-	-	472 B

case of get the string representation immediately, Ulid is twice faster than Guid.

• GetHashCode

Method	Mean	Error	Ratio	Gen 0/1k Op	Gen 1/1k Op	Gen 2/1k Op	Allocated Memory/Op
Guid_	0.9706 ns	NA	1.00	-	-	-	-
Ulid_	1.0329 ns	NA	1.06	-	-	-	-
NUlid_	20.6175 ns	NA	21.24	0.0063	-	-	40 B

GetHashCode is called when use dictionary's key. Ulid is fast and zero allocation.

• Equals

Method	Mean	Error	Ratio	Gen 0/1k Op	Gen 1/1k Op	Gen 2/1k Op	Allocated Memory/Op
Guid_	1.819 ns	NA	1.00	-	-	-	-
Ulid_	2.023 ns	NA	1.11	-	-	-	-
NUlid_	29.875 ns	NA	16.43	0.0126	-	-	80 B

Equals is called when use dictionary's key. Ulid is fast and zero allocation.

• CompareTo

Method	Mean	Error	Ratio	Gen 0/1k Op	Gen 1/1k Op	Gen 2/1k Op	Allocated Memory/Op
Guid_	5.409 ns	NA	1.00	-	-	-	-
Ulid_	3.838 ns	NA	0.71	-	-	-	-
NUlid_	17.126 ns	NA	3.17	0.0063	-	-	40 B

CompareTo is called when use sort. Ulid is fastest and zero allocation.

Cli

You can install command-line to generate ulid string by .NET Core Global Tool.

dotnet tool install --global ulid-cli

after installed, you can call like here.

$ dotnet ulid
01D7CB31YQKCJPY9FDTN2WTAFF

$ dotnet ulid -t "2019/03/25" -min
01D6R3EBC00000000000000000

$ dotnet ulid -t "2019/03/25" -max
01D6R3EBC0ZZZZZZZZZZZZZZZZ

$ dotnet ulid -t "2019/03/25" -max -base64
AWmwNy2A/////////////w==

argument list:
-t, -timestamp: [default=null]timestamp(converted to UTC, ISO8601 format recommended)
-r, -randomness: [default=null]randomness bytes(formatted as Base32, must be 16 characters, case insensitive)
-b, -base64: [default=False]output as base64 format, or output base32 if false
-min, -minRandomness: [default=False]min-randomness(use 000...)
-max, -maxRandomness: [default=False]max-randomness(use ZZZ...)

This CLI tool is powered by ConsoleAppFramework.

Integrate

System.Text.Json

NuGet: Ulid.SystemTextJson

You can use custom Ulid converter - Cysharp.Serialization.Json.UlidJsonConverter.

var options = new JsonSerializerOptions()
{
    Converters =
    {
        new Cysharp.Serialization.Json.UlidJsonConverter()
    }
};

JsonSerializer.Serialize(Ulid.NewUlid(), options);

If application targetframework is netcoreapp3.0, converter is builtin, does not require to add Ulid.SystemTextJson package, and does not require use custom options.

MessagePack-CSharp

NuGet: Ulid.MessagePack

You can use custom Ulid formatter - Cysharp.Serialization.MessagePack.UlidMessagePackFormatter and resolver - Cysharp.Serialization.MessagePack.UlidMessagePackResolver.

var resolver = MessagePack.Resolvers.CompositeResolver.Create(
    Cysharp.Serialization.MessagePack.UlidMessagePackResolver.Instance,
    MessagePack.Resolvers.StandardResolver.Instance);
var options = MessagePackSerializerOptions.Standard.WithResolver(resolver);

MessagePackSerializer.Serialize(Ulid.NewUlid(), options);

If you want to use this custom formatter on Unity, download UlidMessagePackFormatter.cs.

Dapper

For Dapper or other ADO.NET database mapper, register custom converter from Ulid to binary or Ulid to string.

public class BinaryUlidHandler : TypeHandler<Ulid>
{
    public override Ulid Parse(object value)
    {
        return new Ulid((byte[])value);
    }

    public override void SetValue(IDbDataParameter parameter, Ulid value)
    {
        parameter.DbType = DbType.Binary;
        parameter.Size = 16;
        parameter.Value = value.ToByteArray();
    }
}

public class StringUlidHandler : TypeHandler<Ulid>
{
    public override Ulid Parse(object value)
    {
        return Ulid.Parse((string)value);
    }

    public override void SetValue(IDbDataParameter parameter, Ulid value)
    {
        parameter.DbType = DbType.StringFixedLength;
        parameter.Size = 26;
        parameter.Value = value.ToString();
    }
}

// setup handler
Dapper.SqlMapper.AddTypeHandler(new BinaryUlidHandler());

Entity Framework Core

to use in EF, create ValueConverter and bind it.

public class UlidToBytesConverter : ValueConverter<Ulid, byte[]>
{
    private static readonly ConverterMappingHints defaultHints = new ConverterMappingHints(size: 16);

    public UlidToBytesConverter(ConverterMappingHints mappingHints = null)
        : base(
                convertToProviderExpression: x => x.ToByteArray(),
                convertFromProviderExpression: x => new Ulid(x),
                mappingHints: defaultHints.With(mappingHints))
    {
    }
}

public class UlidToStringConverter : ValueConverter<Ulid, string>
{
    private static readonly ConverterMappingHints defaultHints = new ConverterMappingHints(size: 26);

    public UlidToStringConverter(ConverterMappingHints mappingHints = null)
        : base(
                convertToProviderExpression: x => x.ToString(),
                convertFromProviderExpression: x => Ulid.Parse(x),
                mappingHints: defaultHints.With(mappingHints))
    {
    }
}

License

This library is under the MIT License.