Description
Rationale
System.Guid represents .NETs support for Globally Unique Identifiers or GUIDs (sometimes also referred to as Universally Unique Identifiers or UUIDs).
This type represents a 128-bit value in the general format of xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx where each x represents a hexadecimal digit, where the 4 bits of M represent the version and the 4 bits of N represent the variant number. This is sometimes referred to as the 8-4-4-4-12 format string. And while the string representation is "well-defined", the actual underlying order of these bytes has a few different representation and there are several variants of the general RFC 4122 that may require a specific ordering or even may limit specific bytes to have a particular meaning.
.NET's System.Guid follows a field layout best matching variant 2 which is identical to variant 1 outside the endianness. In particular, variant 1 is "big endian" and variant 2 is "little endian". Variant 1 and 2 are used by the current UUID specification and are by far the most prominent while variant 0 is largely considered deprecated. Outside of the endianness these variants are differented by minor bit pattern requirements.
Given this is largely an endianness difference and is otherwise just a minor difference in the bits used for M and N, we would prefer to not introduce a new type just to handle this and would instead prefer to introduce explicit APIs and overloads on Guid that help identify and handle these differences.
Proposed APIs
namespace System
{
public partial struct Guid
{
// public Guid(byte[] value);
// public Guid(ReadOnlySpan<byte> value);
public Guid(ReadOnlySpan<byte> value, bool isBigEndian);
// public byte[] ToByteArray();
public byte[] ToByteArray(bool isBigEndian);
// public bool TryWriteBytes(Span<byte> destination);
// public bool TryWriteBytes(Span<byte> destination, out int bytesWritten); -- new in .NET 8
public bool TryWriteBytes(Span<byte> destination, bool isBigEndian, out int bytesWritten);
}
}
namespace System.Buffers.Binary
{
public static partial class BinaryPrimitives
{
public static Guid ReadGuidBigEndian(ReadOnlySpan<byte> source);
public static Guid ReadGuidLittleEndian(ReadOnlySpan<byte> source);
public static bool TryReadGuidBigEndian(ReadOnlySpan<byte> source, out Guid value);
public static bool TryReadGuidLittleEndian(ReadOnlySpan<byte> source, out Guid value);
public static bool TryWriteGuidBigEndian(ReadOnlySpan<byte> destination, Guid value);
public static bool TryWriteGuidLittleEndian(ReadOnlySpan<byte> destination, Guid value);
public static void WriteGuidBigEndian(ReadOnlySpan<byte> destination, Guid value);
public static void WriteGuidLittleEndian(ReadOnlySpan<byte> destination, Guid value);
}Drawbacks
As discussed on #86084, there is a general concern that users may not be aware that these other overloads exist -or- may not be aware that the difference between variant 1 and variant 2 is endianness and that .NET defaults to variant 2.
However, the same general considerations exists from exposing a new type such as System.Uuid. There are then additional considerations on top in that it further bifurcates the type system, doesn't easily allow polyfilling the support downlevel without shipping a new OOB package, and may further confuse users due to the frequent interchange of the GUID and UUID terminology.
After discussion with a few other API review team members, the general consensus was that shipping a new type is undesirable and we should prefer fixing this via new APIs/overloads and potentially looking into additional ways to surface the difference to users (such as analyzers, API documentation, etc).
Additional Considerations
Given the above, we may want to consider how to help point users towards their desired APIs given the overloads on Guid that do not require specifying endianness.
We can clearly update the documentation, but an analyzer seems like a desired addition that can help point devs towards specifying the endianness explicitly. Obsoleting the existing overloads was also proposed, but may be undesirable since the current behavior isn't "wrong", it just may be the undesired behavior in some scenarios.
We may also want to consider whether a static Guid NewGuid() overload that allows conforming to Version 4, Variant 1 is desired. The docs only indicate it is version 4 and calls into the underlying System APIs. It does not indicate if it produces Variant 1, Variant 2, or truly random bits for N.