CSharpVitamins.ShortGuid 2.0.0

dotnet add package CSharpVitamins.ShortGuid --version 2.0.0
NuGet\Install-Package CSharpVitamins.ShortGuid -Version 2.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="CSharpVitamins.ShortGuid" Version="2.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add CSharpVitamins.ShortGuid --version 2.0.0
#r "nuget: CSharpVitamins.ShortGuid, 2.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 CSharpVitamins.ShortGuid as a Cake Addin
#addin nuget:?package=CSharpVitamins.ShortGuid&version=2.0.0

// Install CSharpVitamins.ShortGuid as a Cake Tool
#tool nuget:?package=CSharpVitamins.ShortGuid&version=2.0.0

CSharpVitamins.ShortGuid

A convenience wrapper for dealing with URL-safe base64 encoded globally unique identifier (GUID), making a shorter string value (22 vs 36 characters long).

URL-safe base64? That's just a base64 string with well known special characters replaced (/, +) or removed (==) to make it a consistent 22 characters long and URI friendly.

Originally seen on @madskristensen's blog, this helper class that extended on his idea existed only as a blog post from around 2007.

Available on NuGet. To install, run the following command in the Package Manager Console:

PM> Install-Package CSharpVitamins.ShortGuid

Strict Parsing (v2.0.0)

As of version 2.0.0, ShortGuid performs a sanity check when decoding strings to ensure they haven't been tampered with, i.e. allowing the end of a Base64 string to be tweaked where it still produces that same byte array to create the underlying Guid. Effectively there is "unused space" in the Base64 string which is ignored, but will now result in an FormatException being thrown.

ShortGuid will never produce an invalid string, however if one is supplied, it could result in an unintended collision where multiple URL-safe Base64 strings can point to the same Guid. To avoid this uncertainty, a round-trip check is performed to ensure a 1-1 match with the input string.

Stick with version 1.1.0 if you require the old behaviour with opt-in strict parsing.


The Gist

It takes a standard guid like this:

c9a646d3-9c61-4cb7-bfcd-ee2522c8f633

and shortens it to a smaller string like this:

00amyWGct0y_ze4lIsj2Mw

Ultimately the encoding/decoding can be distilled down a pair of one-liner functions. What the ShortGuid gives you is a new Type that both

  1. Aids in parsing and converting between types (strings and Guids)
  2. Denotes your intention of expecting this type of data in your code

Using the ShortGuid

The ShortGuid is compatible with normal Guids and other ShortGuid strings. Let's see an example:

Guid guid = Guid.NewGuid();
ShortGuid sguid1 = guid; // implicitly cast the guid as a shortguid
Console.WriteLine(sguid1);
Console.WriteLine(sguid1.Guid);

This produces a new guid, uses that guid to create a ShortGuid, and displays the two equivalent values in the console. Results would be something along the lines of:

FEx1sZbSD0ugmgMAF_RGHw
b1754c14-d296-4b0f-a09a-030017f4461f

Or you can implicitly cast a string to a ShortGuid as well.

string code = "Xy0MVKupFES9NpmZ9TiHcw";
ShortGuid sguid2 = code; // implicitly cast the string as a shortguid
Console.WriteLine(sguid2);
Console.WriteLine(sguid2.Guid);

Which produces the following:

Xy0MVKupFES9NpmZ9TiHcw
540c2d5f-a9ab-4414-bd36-9999f5388773

Flexible with your other data types

The ShortGuid is made to be easily used with the different types, so you can simplify your code. Take note of the following examples:

// for a new ShortGuid, just like Guid.NewGuid()
ShortGuid sguid = ShortGuid.NewGuid();

// to cast the string "myString" as a ShortGuid,
string myString = "Xy0MVKupFES9NpmZ9TiHcw";

// the following 3 lines are equivalent
ShortGuid sguid = new ShortGuid(myString); // traditional
ShortGuid sguid = (ShortGuid)myString;     // explicit cast
ShortGuid sguid = myString;                // implicit cast

// Likewise, to cast the Guid "myGuid" as a ShortGuid
Guid myGuid = new Guid("540c2d5f-a9ab-4414-bd36-9999f5388773");

// the following 3 lines are equivalents
ShortGuid sguid = new ShortGuid(myGuid); // traditional
ShortGuid sguid = (ShortGuid)myGuid;     // explicit cast
ShortGuid sguid = myGuid;                // implicit cast

After you've created your ShortGuid's the 3 members of most interest are the original Guid value, the new short string (the short encoded guid string), and the ToString() method, which also returns the short encoded guid string.

sguid.Guid;       // gets the Guid part
sguid.Value;      // gets the encoded Guid as a string
sguid.ToString(); // same as sguid.Value

Easy comparison with guids and strings

You can also do equals comparison against the three types, Guid, string and ShortGuid like in the following example:

Guid myGuid = new Guid("540c2d5f-a9ab-4414-bd36-9999f5388773");
ShortGuid sguid = (ShortGuid)"Xy0MVKupFES9NpmZ9TiHcw";

if (sguid == myGuid) {
  // logic if guid and sguid are equal
}

if (sguid == "Xy0MVKupFES9NpmZ9TiHcw") {
  // logic if string and sguid are equal
}

Use within SQL

ShortGuid.sql is also included in the project source files if you want to work with ShortGuids directly in SQL Server (SQL 2005+).

SET @sguid = dbo.EncodeShortGuid(@myUniqueIdentifier)
-- output 'Xy0MVKupFES9NpmZ9TiHcw'

SET @guid = dbo.DecodeShortGuid(@myShortGuidValue)
-- output 540c2d5f-a9ab-4414-bd36-9999f5388773
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  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 was computed.  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 was computed.  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 netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net40 is compatible.  net403 was computed.  net45 was computed.  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 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 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.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on CSharpVitamins.ShortGuid:

Package Downloads
Orbital7.Extensions The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

.NET Extensions/Utilities

StructuredDataCapture.ObjectModel.Test

Object Model (OM) for IHE Structured Data Capture (SDC)

Auditable

Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on CSharpVitamins.ShortGuid:

Repository Stars
RaythaHQ/raytha
Raytha is a powerful CMS with an easy-to-use interface and fast performance. It offers custom content types, a template engine, and various access controls. It supports multiple storage providers and an automatically generated REST API. Upgrade your development workflow with Raytha.
Version Downloads Last updated
2.0.0 1,148,668 3/11/2021
1.1.0 1,559 3/11/2021
1.0.2 188,955 5/8/2020
1.0.1 43,040 11/22/2019

- 2.0.0 Strict is now always on.
       Reduces surface area that exposed `strict` parsing options.
       Stick with `v1.1.0` if you require the loose form of decoding.

- 1.1.0 Adds overloads for strict parsing to (Try)Decode/Parse methods. Default: strict=false for backwards compatibility.
       Signals intent to move to strict only parsing in version 2+.
- 1.0.3 Improves documentation.
       Adds symbols package to enable SourceLink.
- 1.0.2 Fix: Ambiguous use of `==` operator when comparing Guid and ShortGuid instances.
- 1.0.1 Target netstandard2.0 and net40.
- 1.0.0 Initial release.