The CreateUuid8 method generates a unique 128-bit
value that conforms to the Version 8 UUID format as described in RFC
9562. Version 8 UUIDs are designed to support application-specific
customization while preserving the structural format of standard
UUIDs, including proper version and variant bits.
Unlike Version 1 and Version 7 UUIDs, which encode timestamps,
Version 8 UUIDs allow the application to define the semantics of part
or all of the UUID content. This implementation stores the 32-bit
CustomValue in the Data1 field of the GUID, followed
by 96 bits of cryptographically secure random data. This provides
a balance between custom application meaning and guaranteed uniqueness.
If the CustomValue parameter is zero, the method will use a randomly
generated 32-bit value to avoid producing UUIDs that begin with
all-zero bits, which may be interpreted as placeholders or uninitialized
values in some systems.
This method is particularly useful for:
- Generating UUIDs that embed object or session identifiers.
- Encoding a partition key, process ID, or user-defined code
for categorization or routing.
- Maintaining backward compatibility with systems that require
uniqueness but also need embedded metadata.
When a custom value is specified, only the first 32 bits of the
UUID are application-defined. The remaining 96 bits are cryptographically
random, making collisions extremely unlikely. The probability of a
collision after generating n UUIDs with the same value is
approximately:
p ≈ n² / 297
After generating one million UUIDs with the same custom value, the
probability of a collision would still be less than 1 in 1020.
In practice, even if the same 32-bit custom value is embedded millions
or billions of times, the risk of a collision is negligible.
If you need to create a unique value that uses more than 96 bits of
entropy, or you prefer to create a unique token value which is not
formatted as a UUID, use the CreateToken method. This method
allows you to specify the number of bits of entropy used to create a
cryptographically secure token and the algorithm used to encode the
randomized data.