Be.Vlaanderen.Basisregisters.Generators.Deterministic

Goal

Create a deterministic GUID based on a namespace, a string and an optional version.

Although a new GUID is typically created in order to provide a unique ID, there are occasions when it’s useful for two different systems to generate the same GUID independently. RFC 4122 provides an algorithm for deterministic creation of a GUID based on a namespace ID (itself a GUID) and a name within that namespace. These name-based GUIDs will never collide with GUIDs from other sources (e.g., Guid.NewGuid), and have a very (very) small chance of colliding with other name-based GUIDs. As per section 4.3:

• The UUIDs generated at different times from the same name in the same namespace MUST be equal.
• The UUIDs generated from two different names in the same namespace should be different (with very high probability).
• The UUIDs generated from the same name in two different namespaces should be different with (very high probability).
• If two UUIDs that were generated from names are equal, then they were generated from the same name in the same namespace (with very high probability).

Because .NET doesn’t provide a way to create these GUIDs, it’s tempting to create a custom solution (e.g., using a MD5 hash as a GUID, because it has the same number of bytes), but because that doesn’t follow the rules of GUID creation, it’s not guaranteed to be unique with respect to other GUIDs.

Usage

Determine a namespace for your use case, this is just a random GUID you can store somewhere.

Using Deterministic.Create you can now pass in the namespace and a value and it will always return the same GUID.

By default a version 5 GUID is created.

var namespaceGuid = new Guid("6ba7b810-9dad-11d1-80b4-00c04fd430c8");
var value = "hello.example.com";
var deterministicGuid = Deterministic.Create(namespaceGuid, value);

A version 3 GUID uses MD5 to compute a hash of the namespace and name.

var namespaceGuid = new Guid("6ba7b810-9dad-11d1-80b4-00c04fd430c8");
var value = "hello.example.com";
var version = 5;
var deterministicGuid = Deterministic.Create(namespaceGuid, value, version);

A version 5 GUID uses SHA1 to compute a hash of the namespace and name.

var namespaceGuid = new Guid("6ba7b810-9dad-11d1-80b4-00c04fd430c8");
var value = "hello.example.com";
var version = 5;
var deterministicGuid = Deterministic.Create(namespaceGuid, value, version);

License

MIT License

Credits

Languages & Frameworks

• .NET Core - MIT
• .NET Core Runtime - CoreCLR is the runtime for .NET Core. It includes the garbage collector, JIT compiler, primitive data types and low-level classes. - MIT
• .NET Core APIs - CoreFX is the foundational class libraries for .NET Core. It includes types for collections, file systems, console, JSON, XML, async and many others. - MIT
• .NET Core SDK - Core functionality needed to create .NET Core projects, that is shared between Visual Studio and CLI. - MIT
• Roslyn and C# - The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs. - Apache License 2.0
• F# - The F# Compiler, Core Library & Tools - MIT
• F# and .NET Core - F# and .NET Core SDK working together. - MIT

Libraries

• Paket - A dependency manager for .NET with support for NuGet packages and Git repositories. - MIT
• FAKE - "FAKE - F# Make" is a cross platform build automation system. - MIT
• xUnit - xUnit.net is a free, open source, community-focused unit testing tool for the .NET Framework. - Apache License 2.0
• Shouldly - Should testing for .NET - the way Asserting Should be! - BSD
• Faithlife.Utility - Common .NET utility code in use at Faithlife - MIT

Tooling

• npm - A package manager for JavaScript. - Artistic License 2.0
• semantic-release - Fully automated version management and package publishing. - MIT
• semantic-release/changelog - Semantic-release plugin to create or update a changelog file. - MIT
• semantic-release/commit-analyzer - Semantic-release plugin to analyze commits with conventional-changelog. - MIT
• semantic-release/exec - Semantic-release plugin to execute custom shell commands. - MIT
• semantic-release/git - Semantic-release plugin to commit release assets to the project's git repository. - MIT
• semantic-release/github - Semantic-release plugin to publish a GitHub release. - MIT
• semantic-release/npm - Semantic-release plugin to publish a npm package. - MIT
• semantic-release/release-notes-generator - Semantic-release plugin to generate changelog content with conventional-changelog. - MIT
• commitlint - Lint commit messages. - MIT
• commitizen/cz-cli - The commitizen command line utility. - MIT
• commitizen/cz-conventional-changelog A commitizen adapter for the angular preset of conventional-changelog. - MIT
• husky - Git hooks made easy. - MIT

Flemish Government Libraries

• Be.Vlaanderen.Basisregisters.Build.Pipeline - Contains generic files for all Basisregisters Vlaanderen pipelines. - MIT