Yort.Xid.Net 2.0.0-beta

Prefix Reserved
.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher. .NET Standard 1.3 This package targets .NET Standard 1.3. The package is compatible with this framework or higher. .NET Framework 4.0 This package targets .NET Framework 4.0. The package is compatible with this framework or higher.
This is a prerelease version of Yort.Xid.Net.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Yort.Xid.Net --version 2.0.0-beta                

                    
                

            
NuGet\Install-Package Yort.Xid.Net -Version 2.0.0-beta
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="Yort.Xid.Net" Version="2.0.0-beta" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Yort.Xid.Net --version 2.0.0-beta                

                    
                

            
#r "nuget: Yort.Xid.Net, 2.0.0-beta"
#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 Yort.Xid.Net as a Cake Addin
#addin nuget:?package=Yort.Xid.Net&version=2.0.0-beta&prerelease

// Install Yort.Xid.Net as a Cake Tool
#tool nuget:?package=Yort.Xid.Net&version=2.0.0-beta&prerelease

Xid.Net - Globally Unique ID Generator

This project is a .Net port (with modifications) of https://github.com/rs/xid by Olivier Poitrey. Significant parts of the code and this readme are based on that project.

Xid.Net is a globally unique id generator library, ready to be used safely and directly in your code. It provides an interface similar to System.Guid but generates ids which are smaller (12 bytes vs 16 in raw format, 20 vs 36 when converted to a string). Generating Xids is faster than Guids, often significantly.

Xid uses the Mongo Object ID algorithm to generate globally unique ids with a different serialization (base32 vs base64) to make it shorter when transported as a string: https://docs.mongodb.org/manual/reference/object-id/.

GitHub license Build status NuGet Badge

Platforms

  • .Net 4.0+
  • .Net Standard 1.3

Install

    PM> Install-Package Xid.Net

Usage/API

Creating a Xid;

    var id = Xid.NewXid();

Converting to Xid to a string;

    var id = Xid.NewXid();
    var idString = id.ToString();

Converting a string to a Xid (TryParse method also provided);

    var idString = "9m4e2mr0ui3e8a215n4g";
    var id = Xid.Parse(idString);

Converting to Xid to a byte array;

    var id = Xid.NewXid();
    var bytes = id.ToBytes();

or

    var id = Xid.NewXid();
    var preallocatedByteArray = new byte[12];
    var bytes = id.ToBytes(preallocatedByteArray);

Getting components of a Xid;

    var xid = Xid.NewXid();
    DateTime timestamp = xid.GetTimeStamp();
    byte[] machineId = xid.GetMachineId();
    UInt16 processId = xid.GetProcessId();
    int counter = xid.GetCounter();

Also supported/other features of .Net implementation;

  • IFormattable
  • IComparable
  • IComparable<Xid>
  • IEquatable<Xid>
  • == > < >= ⇐ and != operators
  • Correctly implemented Equals and GetHashCode overrides
  • Xid.NewXid is thread-safe

Xid Format, Implementation & Comparison to other UUIDs

The format of a Xid is;

  • 4-byte value representing the seconds since the Unix epoch,
  • 3-byte machine identifier,
  • 2-byte process id, and
  • 3-byte counter, starting with a random value.

The binary representation of the id is compatible with Mongo 12 byte Object IDs. The string representation uses base32 hex (without padding) for better space efficiency when stored in that form (20 bytes). The hex variant of base32 is used to retain the sortable property of the id.

Xid doesn't use base64 because case sensitivity and the 2 non alphanum chars may be an issue when transported as a string between various systems. Base36 wasn't used because it's not standard, the resulting size is not predictable (not bit aligned), and it would not remain sortable. To validate a base32 xid, expect a 20 character long, all lowercase sequence using characters in the range of a to v and 0 to 9 numbers ([0-9a-v]{20}).

UUIDs are 16 bytes (128 bits) and 36 chars as string representation. Twitter Snowflake ids are 8 bytes (64 bits) but require machine/data-center configuration and/or central generator servers. Xid stands in between at 12 bytes (96 bits) with a more compact URL-safe string representation (20 chars). No configuration or central generator server is required so it can be used directly in application code.

Name Binary Size String Size Features
UUID 16 bytes 36 chars configuration free, not sortable
shortuuid 16 bytes 22 chars configuration free, not sortable
Snowflake 8 bytes up to 20 chars needs machine/DC configuration, needs central server, sortable
MongoID 12 bytes 24 chars configuration free, sortable
xid 12 bytes 20 chars configuration free, sortable

Features:

  • Size: 12 bytes (96 bits), smaller than UUID, larger than snowflake
  • Base32 hex encoded by default (20 chars when transported as printable string, still sortable)
  • Non configured, you don't need set a unique machine and/or data center id
  • K-ordered
  • Embedded time with 1 second precision
  • Unicity guaranteed for 16,777,216 (24 bits) unique ids per second and per host/process
  • Lock-free (i.e.: unlike UUIDv1 and v2)

Benchmarks

32-bit<br/> BenchmarkDotNet=v0.10.9, OS=Windows 10 Redstone 2 (10.0.15063)<br/> Processor=Intel Core i7-6820HQ CPU 2.70GHz (Skylake), ProcessorCount=8<br/> Frequency=2648436 Hz, Resolution=377.5813 ns, Timer=TSC<br/> [Host] : .NET Framework 4.7 (CLR 4.0.30319.42000), 32bit LegacyJIT-v4.7.2101.1<br/> DefaultJob : .NET Framework 4.7 (CLR 4.0.30319.42000), 32bit LegacyJIT-v4.7.2101.1<br/>

Method Mean Error StdDev
CreateXidBenchmark 36.94 ns 0.2248 ns 0.2103 ns
CreateGuidBenchmark 201.27 ns 6.9994 ns 6.5473 ns

64-bit<br/> BenchmarkDotNet=v0.10.9, OS=Windows 10 Redstone 2 (10.0.15063)<br/> Processor=Intel Core i7-6820HQ CPU 2.70GHz (Skylake), ProcessorCount=8<br/> Frequency=2648436 Hz, Resolution=377.5813 ns, Timer=TSC<br/> [Host] : .NET Framework 4.7 (CLR 4.0.30319.42000), 64bit RyuJIT-v4.7.2101.1<br/> DefaultJob : .NET Framework 4.7 (CLR 4.0.30319.42000), 64bit RyuJIT-v4.7.2101.1<br/>

Method Mean Error StdDev
CreateXidBenchmark 23.56 ns 0.1409 ns 0.1100 ns
CreateGuidBenchmark 82.41 ns 0.2656 ns 0.2354 ns

References:

License

All source code is licensed under the MIT License. Original Xid repo license at; Xid License.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  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 is compatible.  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 netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard1.3 is compatible.  netstandard1.4 was computed.  netstandard1.5 was computed.  netstandard1.6 was computed.  netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net40 is compatible.  net403 was computed.  net45 is compatible.  net451 was computed.  net452 was computed.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 is compatible.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap was computed.  uap10.0 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.

  • .NETFramework 4.0

    • No dependencies.

  • .NETFramework 4.5

    • No dependencies.

  • .NETFramework 4.8

    • No dependencies.

  • .NETStandard 1.3

  • .NETStandard 2.0

    • No dependencies.

  • net5.0

    • No dependencies.

  • net6.0

    • No dependencies.

  • net7.0

    • No dependencies.

  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.0.1 242 10/8/2024
2.0.1-beta 69 10/5/2024
2.0.0-beta 71 10/5/2024

A new version of the older Xid.Net package.

* Fixes for machine id generation
* Package id now uses reserved Yort. prefix
* Modernised projects/solution with multi-targeting
* Support for additional platforms