GUIDs
On this page
Overview
In this guide, you can learn how to serialize globally unique identifiers (GUIDs), also known as universally unique identifiers (UUIDs).
Tip
ObjectId
In MongoDB applications, you can use the
ObjectId type
as a unique identifier for a document. Consider using ObjectId
instances in place
of GUIDs in MongoDB applications where possible.
GUIDs in MongoDB
A GUID is a 16-byte integer that you can use as a unique ID for a MongoDB document. The following code block shows an example GUID:
00112233-4455-6677-8899-aabbccddeeff
Originally, MongoDB represented GUIDs as BsonBinaryData
values of subtype 3.
Because subtype 3 didn't standardize the byte order of GUIDs
during encoding, different MongoDB drivers encoded GUIDs with different byte orders.
The following tabs show different driver encodings of the preceding GUID to
BsonBinaryData
subtype 3:
33221100-5544-7766-8899-aabbccddeeff
00112233-4455-6677-8899-aabbccddeeff
77665544-3322-1100-ffee-ddccbbaa9988
To standardize GUID byte order across applications, we added BsonBinaryData
subtype 4,
which all MongoDB drivers encode in the same way. If your application uses GUIDs, we
recommend using BsonBinaryData
subtype 4 to store them.
For a list of all BsonBinaryData
subtypes, see the
API documentation for the BsonBinarySubType
enum.
Serializing GUIDs
Although we recommend using subtype 4 for all new BsonBinaryData
GUIDs, some older
MongoDB collections might contain some GUID fields that use subtype 3 and others that use
subtype 4. To account for these differences, the .NET/C# Driver handles GUID
serialization at the level of individual properties.
The .NET/C# Driver uses the GuidRepresentation
enum to represent the different
BsonBinaryData
subtypes. The following table shows the GuidRepresentation
enum
members and the corresponding BsonBinaryData
subtypes:
GuidRepresentation Member | BsonBinaryData Subtype |
---|---|
Standard | 4 |
CSharpLegacy | 3 |
JavaLegacy | 3 |
PythonLegacy | 3 |
Unspecified | N/A |
Note
The CSharpLegacy
, JavaLegacy
, and PythonLegacy
GUID representations are
all equivalent to BsonBinaryData
subtype 3, but use different byte orders.
The following sections describe the ways in which you can configure GUID representation in your application.
Configure with Attributes
If you're using the .NET/C# Driver to
automap your C# classes to document schemas,
you can add the BsonGuidRepresentation
attribute to a GUID property
to specify its representation. This attribute accepts a value from the
The following code example specifies the Standard
GUID representation for the
G
property:
public class Widget { public int Id { get; set; } [ ] public Guid G { get; set; } }
Configure in Code
If you're writing your own serialization code, you can use the
GuidSerializer
class to serialize and deserialize individual GUID values to and
from BSON fields. To ensure that the driver handles GUIDs correctly, use the
GuidRepresentation
parameter when you construct a GuidSerializer
.
The following code sample creates an instance of the GuidSerializer
class
for serializing properties that use BsonBinaryData
subtype 4:
var guidSerializer = new GuidSerializer(GuidRepresentation.Standard);
If most of your GUIDs use the same representation, you can register a GuidSerializer
globally. To create and register a GuidSerializer
, run the following code early
in your application, such as during the bootstrapping phase:
BsonSerializer.RegisterSerializer(new GuidSerializer(GuidRepresentation.Standard));
Tip
When you're working with two BsonBinaryData
subtypes, you can combine a global
serializer with the BsonGuidRepresentation
property attribute. For example, you
can register a global serializer for the most commonly used GUID subtype, then use
the BsonGuidRepresentation
attribute to denote any GUID properties of another subtype.
Important
If you don't globally register a serializer, you must apply the BsonGuidRepresentation
attribute to every serializable GUID property. Otherwise, the driver throws an exception
when it tries to serialize the property.
Serializing Objects
You can use an ObjectSerializer
to serialize hierarchical objects to subdocuments.
To ensure that GUIDs in these objects are serialized and deserialized correctly,
select the correct GUID representation when constructing your ObjectSerializer
.
The following code sample shows how to
create an ObjectSerializer
for a GUID representation of subtype 4:
var objectDiscriminatorConvention = BsonSerializer.LookupDiscriminatorConvention(typeof(object)); var objectSerializer = new ObjectSerializer(objectDiscriminatorConvention, GuidRepresentation.Standard);
If your application relies on an ObjectSerializer
to serialize any GUIDs, you
must also register the serializer early in your application, such as during the
bootstrapping phase. The serializer that you
register will be used globally whenever an object serializer is needed and has not
been otherwise specified.
To register your ObjectSerializer
, pass it to the BsonSerializer.RegisterSerializer()
method:
var objectDiscriminatorConvention = BsonSerializer.LookupDiscriminatorConvention(typeof(object)); var objectSerializer = new ObjectSerializer(objectDiscriminatorConvention, GuidRepresentation.Standard); BsonSerializer.RegisterSerializer(objectSerializer);
Additional Information
To learn more about any of the methods or types discussed in this guide, see the following API documentation: