Ulid

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

Allow to convert Guid.

• .ToGuid()
• (Guid)ulid

Performance

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

• New

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

• Parse

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

• ToString

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

• NewId().ToString()

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

• GetHashCode

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

• Equals

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

• CompareTo

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.

…

Entity Framework Core

to use in EF, create ValueConverter and bind it.

…

To use those converters, you can either specify individual properties of entities in OnModelCreating method of your context:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<MyEntity>()
        .Property(e => e.MyProperty)
        .HasConversion<UlidToStringConverter>()
        .HasConversion<UlidToBytesConverter>();
}

or use model bulk configuration for all properties of type Ulid. To do this, overload ConfigureConventions method of your context:

protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder
        .Properties<Ulid>()
        .HaveConversion<UlidToStringConverter>()
        .HaveConversion<UlidToBytesConverter>();
}

License

This library is under the MIT License.