cuid.net 5.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package cuid.net --version 5.0.0
NuGet\Install-Package cuid.net -Version 5.0.0
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="cuid.net" Version="5.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add cuid.net --version 5.0.0
#r "nuget: cuid.net, 5.0.0"
#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 cuid.net as a Cake Addin
#addin nuget:?package=cuid.net&version=5.0.0

// Install cuid.net as a Cake Tool
#tool nuget:?package=cuid.net&version=5.0.0

cuid.net

GitHub Workflow Status Code Quality Coverage

Nuget Downloads GitHub

A .NET implementation of collision-resistant ids. You can read more about CUIDs from the official project website.

A command-line utility, cuidgen, is also available that implements the cuid.net library for those wishing to leverage CUIDs in scripting environments.

Table of Contents

Getting Started

You can install cuid.net as a nuget package:

dotnet add package cuid.net 

Implementations

cuid.net supports the construction and use of both CUIDv1 (deprecated) and CUIDv2 instances.


CUIDv1

❗ CUIDv1 has been deprecated for security reasons. Efforts should be made towards migrating to Cuid2.

⚠️ It is possible to derive with a degree of certainty when and where a CUIDv1 has been created.

📝 Usage of CUIDv1 will emit the compiler warning VISLIB0001.

Designed and optimized for horizontal scaling and binary searches, Cuid is an immutable structure that can be a potential alternative to Guid for situations where a clean "string safe" unique and sortable identifier is needed and where security is not of the upmost concern.

Structure

CUIDv1 values are composed of several data points which are base 36 encoded.

clbvi4441000007ld63liebkf

Segment Source
c CUIDv1 identifier
lbvi4441 Unix timestamp (in milliseconds)
0000 Session counter
07ld Client fingerprint (host process identifier + system hostname)
63liebkf Random data

Instantiation

using Visus.Cuid;

// new
Cuid cuid = Cuid.NewCuid();
Console.WriteLine(cuid); // clbvi4441000007ld63liebkf

// constructor
Cuid cuid = new("clbvi4441000007ld63liebkf");

// explicit parsing
Cuid cuid = Cuid.Parse("clbvi4441000007ld63liebkf");

// implicit parsing
bool success = Cuid.TryParse("clbvi4441000007ld63liebkf", out Cuid cuid);

Cuid fully implements IComparable, IComparable<T>, and IEquatable<T> along with including Cuid.Empty for comparing against empty or uninitialized Cuid objects.

Serialization

Cuid has built-in support for serialization either with System.Text.Json or XmlSerializer.

JSON

using Visus.Cuid;

// serialize
Cuid cuid = Cuid.NewCuid();
string json = JsonSerializer.Serialize(cuid);

Console.WriteLine(json); // "clbvi4441000007ld63liebkf"

// deserialize
Cuid cuid = JsonSerializer.Deserialize<Cuid>("\"clbvi4441000007ld63liebkf\"");

XML

using Visus.Cuid;

// serialize
Cuid cuid = Cuid.NewCuid();

XmlSerializer serializer = new(typeof(Cuid));
XmlWriterSettings settings = new() { Indent = false };

using (StringWriter sw = new())
{
    using XmlWriter xw = XmlWriter.Create(stringWriter, settings);

    serializer.Serialize(xw, cuid);

    Console.WriteLine(sw); // <?xml version="1.0" encoding="utf-16"?><cuid>clbvi4441000007ld63liebkf</cuid>
}

// deserialize

string xml = "<?xml version=\"1.0\" encoding=\"utf-16\"?><cuid>clbvi4441000007ld63liebkf</cuid>";
using (TextReader sr = new StringReader(xml))
{
    using XmlReader xr = XmlReader.Create(sr);
    
    Cuid cuid = (Cuid) serializer.Deserialize(xr);
}

CUIDv2

📝 Cuid2 implements IEquatable<T> but does not implement IComparable or IComparable<T>.

Cuid2 is an immutable structure that generates a cryptographically strong identity. Cuid2 and is recommended for use over Cuid where security context is important. The length of the value can also be adjusted to be anywhere from 4 characters to 32 characters in length, the default is 24.

Structure

CUIDv2 values follow a different variable structure length than that of their predecessor. As such, there is no predefined pattern of how they will look once generated. However, with that said, they do use the following data sources:

Segments
Single character (a-z) randomly chosen as the prefix
Unix timestamp (in milliseconds)
32-byte array containing cryptographically strong random data
Session counter value from a cryptographically weak random number generator
32-byte array containing non-sensitive host information and padding with cryptographically strong random data

The information is then combined and a SHA-512 (SHA-3 Keccak) salted hash is computed and then encoded into a base 36 string.

Instantiation

using Visus.Cuid;

// new (default length of 24)
Cuid2 cuid = new Cuid2();
Console.WriteLine(cuid); // x8kvch3q341xr1wa5ida3ns0

// new (with custom length)
Cuid2 cuid = new Cuid2(10);
Console.WriteLine(cuid); // rolaz6ek3u
Product Compatible and additional computed target framework versions.
.NET 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on cuid.net:

Package Downloads
Shoppy.Toolkit.IdGenerator.Cuid

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.0.2 4,364 12/8/2023
5.0.1 508 11/17/2023
5.0.0 189 11/15/2023
4.1.0 4,313 8/29/2023
4.0.1 242 8/19/2023