Skip to content

Commit e207f58

Browse files
mongoKartmongoKart
committed
wip
1 parent 33b4fbe commit e207f58

File tree

2 files changed

+107
-55
lines changed

2 files changed

+107
-55
lines changed

‎source/fundamentals/serialization/guid-serialization.txt

Lines changed: 93 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -24,47 +24,104 @@ In this guide, you can learn how to serialize **globally unique identifiers**
2424
(`GUIDs <https://learn.microsoft.com/en-us/dynamicsax-2012/developer/guids>`__),
2525
also known as **universally unique identifiers** (UUIDs).
2626

27-
.. tip::
27+
A Short History of MongoDB GUIDs
28+
--------------------------------
2829

29-
In MongoDB applications, ``ObjectId`` can be used as a unique identifier for
30-
a document. Consider using ``ObjectId`` in place of a GUID with MongoDB
31-
applications where possible.
30+
A GUID is a 16-byte integer that you can use as a unique ID for a MongoDB document.
31+
The following code block shows an example GUID:
32+
33+
.. code-block::
3234

33-
A GUID is a 16-byte integer that you can use as a unique ID for a MongoDB document.
34-
Originally, GUIDs in MongoDB were represented as ``BsonBinaryData`` values of subtype 3.
35-
Subtype 3 did not standardize the byte order during serialization, which led to
36-
inconsistent serialization across MongoDB drivers.
37-
To standardize the byte order and ensure consistent serialization across drivers, we
38-
created ``BsonBinaryData`` subtype 4.
35+
00112233-4455-6677-8899-aabbccddeeff
3936

40-
.. note::
41-
42-
Use ``BsonBinaryData`` subtype 4 for all new GUIDs.
37+
Originally, MongoDB represented GUIDs as ``BsonBinaryData``
38+
values of subtype 3. Because subtype 3 didn't standardize the byte order of GUIDs
39+
during encoding, different MongoDB drivers encoded GUIDs with different byte orders.
40+
41+
Use the following tabs to compare the ways in which different MongoDB language drivers
42+
encoded the preceding GUID to ``BsonBinaryData`` subtype 3:
43+
44+
.. tabs::
4345

46+
.. tab:: {+driver-short+}
47+
:tabid: csharp
4448

45-
In many MongoDB collections, all GUID fields use the same subtype of ``BsonBinaryData``.
46-
Some older collections, however, may contain some GUID fields that
47-
use subtype 3 and others that use subtype 4.
49+
.. code-block:: csharp
4850

49-
The driver allows fields in the same document to use different
50-
GUID formats. GUID representation is controlled at the property level by configuring the
51-
serializer for each property.
51+
33221100-5544-7766-8899-aabbccddeeff
52+
53+
.. tab:: PyMongo
54+
:tabid: pymongo
55+
56+
.. code-block:: python
57+
58+
00112233-4455-6677-8899-aabbccddeeff
59+
60+
.. tab:: Java Driver
61+
:tabid: java
62+
63+
.. code-block:: java
64+
65+
77665544-3322-1100-ffee-ddccbbaa9988
66+
67+
To standardize GUID byte order, we added ``BsonBinaryData`` subtype 4, which all
68+
MongoDB drivers encode in the same way. We recommend using
69+
``BsonBinaryData`` subtype 4 for all new GUIDs.
70+
71+
For a list of all ``BsonBinaryData`` subtypes, see the
72+
API documentation for the `BsonBinarySubType <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonBinarySubType.html>`__
73+
enum.
74+
75+
.. tip::
76+
77+
In MongoDB applications, ``ObjectId`` can be used as a unique identifier for
78+
a document. Consider using ``ObjectId`` in place of a GUID with MongoDB
79+
applications where possible.
5280

5381
Serializing GUIDs
5482
-----------------
5583

56-
The driver handles GUID serialization at the level of individual
57-
properties. You must ensure that
58-
each GUID field is serialized and deserialized correctly.
84+
Although we recommend using subtype 4 for all new ``BsonBinaryData`` GUIDs, some older
85+
MongoDB collections might contain some GUID fields that use subtype 3 and others that use
86+
subtype 4. To account for these differences, the {+driver-short+} handles GUID
87+
serialization at the level of individual properties.
5988

60-
.. note::
89+
If you're using the {+driver-short+} to
90+
:ref:`automap your {+language+} classes to document schemas <csharp-class-mapping>`,
91+
you can add the ``BsonGuidRepresentation`` attribute to a GUID property
92+
to specify its representation. This attribute accepts a value from the
93+
``GuidRepresentation`` enum, which contains the following members:
6194

62-
Default value is unspecified. Driver throws an exception rather than guessing.
63-
You must specify the format for every GUID, or globally register a serializer.
95+
.. list-table::
96+
:header-rows: 1
97+
:stub-columns: 1
98+
:widths: 10 10
6499

65-
If you're using the {+driver-short+} to :ref:`automap your {+language+} classes to document schemas <csharp-class-mapping>`,
66-
you can use the ``BsonGuidRepresentation`` attribute on a GUID property
67-
to specify the representation:
100+
* - GuidRepresentation Member
101+
- BsonBinaryData Subtype
102+
103+
* - ``Standard``
104+
- 4
105+
106+
* - ``CSharpLegacy``
107+
- 3
108+
109+
* - ``JavaLegacy``
110+
- 3
111+
112+
* - ``PythonLegacy``
113+
- 3
114+
115+
* - ``Unspecified``
116+
- N/A
117+
118+
.. note::
119+
120+
The ``CSharpLegacy``, ``JavaLegacy``, and ``PythonLegacy`` GUID representations are
121+
all equivalent to ``BsonBinaryData`` subtype 3, but use different byte orders.
122+
123+
The following code example specifies the ``Standard`` GUID representation for the
124+
``G`` property:
68125

69126
.. code-block:: csharp
70127

@@ -76,20 +133,13 @@ to specify the representation:
76133
public Guid G { get; set; }
77134
}
78135

79-
.. note::
80-
81-
``GuidRepresentation.Standard`` is equivalent to ``BsonBinaryData`` subtype 4.
82-
Other GUID representations in the {+driver-short+}, such as ``CSharpLegacy``,
83-
``JavaLegacy``, and ``PythonLegacy``, are equivalent to subtype 3 but use
84-
different byte orders.
85-
86136
If you're writing your own serialization code, you can use the
87137
``GuidSerializer`` class to serialize and deserialize individual GUID values to and
88138
from BSON fields. To ensure that the driver handles GUIDs correctly, use the
89139
``GuidRepresentation`` parameter when you construct a ``GuidSerializer``.
90140

91-
The following code sample creates an instance of ``GuidSerializer``
92-
for serializing GUID representations of subtype 4:
141+
The following code sample creates an instance of the ``GuidSerializer`` class
142+
for serializing properties that use ``BsonBinaryData`` subtype 4:
93143

94144
.. code-block::
95145

@@ -110,6 +160,12 @@ in your application, such as during the bootstrapping phase:
110160
serializer for the most commonly used GUID subtype, then use the ``BsonGuidRepresentation``
111161
attribute to denote any GUID properties of another subtype.
112162

163+
.. important::
164+
165+
If you don't globally register a serializer, you must apply the ``BsonGuidRepresentation``
166+
attribute to every serializable GUID property. Otherwise, the driver throws an exception
167+
when it tries to serialize the property.
168+
113169
Serializing Objects
114170
-------------------
115171

‎source/upgrade.txt

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -72,28 +72,24 @@ Version 3.0 Potential Breaking Change
7272
- The LINQ2 provider has been removed from this version of the driver.
7373
You must use LINQ3 for all LINQ queries.
7474

75-
- In driver v2.x, you could choose between two GUID representation modes.
76-
``GuidRepresentationMode.V2`` was the default. This mode assumed that all GUIDs in a
77-
document use the same ``BsonBinaryData`` subtype, and GUID representation was
78-
controlled by the reader or writer, not the serializer.
79-
80-
In driver v3.0, ``GuidRepresentationMode.V3`` is the only option. Running in this mode
81-
changes the behavior of the driver in the following ways:
82-
This mode is more flexible than ``V2``, but it also means you must ensure that
83-
each GUID field is serialized and deserialized correctly.
75+
- Previous versions of the {+driver-short+} supported two GUID representation modes.
76+
In version 3.0, ``GuidRepresentationMode.V3`` is the only supported mode. This change
77+
has the following effects on the driver:
8478

8579
- The methods in the ``BsonBinaryReader``, ``BsonBinaryWriter``, ``JsonReader``, and
8680
``JsonWriter`` classes no longer check the ``GuidRepresentationMode``.
87-
- Removed the ``BsonBinaryData(Guid)`` constructor. To construct a ``BsonBinaryData``
81+
- The ``BsonBinaryData(Guid)`` constructor has been removed. To construct a ``BsonBinaryData``
8882
object from a GUID, use the ``BsonBinaryData.Create(Guid, GuidRepresentation)`` constructor.
89-
- Removed the ``BsonBinaryData.GuidRepresentation`` property. This information is no
90-
longer stored in the ``BsonBinaryData`` object and must be specified by the user.
91-
- Calling the ``BsonBinaryData.ToGuid()`` method without the ``GuidRepresentation``
92-
parameter works only on GUIDs of subtype 4.
93-
94-
If you map your data only to POCOs, you can ignore the GUID representation. However, if you
95-
serialize and deserialize BSON documents directly, you must specify the GUID representation and ensure that
96-
it matches the format used by your documents.
83+
- The ``BsonBinaryData.GuidRepresentation`` property has been removed.
84+
- You can call the ``BsonBinaryData.ToGuid()`` method only on ``BsonBinaryData``
85+
objects of subtype 4. If the object has any other subtype, you must call the
86+
``BsonBinaryData.ToGuid(GuidRepresentation)`` method and specify the subtype.
87+
88+
.. note::
89+
90+
The preceding changes affect your application only if you serialize and deserialize
91+
BSON documents directly. If you map your MongoDB documents only to :ref:`csharp-poco`,
92+
the ``GuidRepresentationMode`` doesn't affect your application.
9793

9894
.. _csharp-breaking-changes-2.28.0:
9995

0 commit comments

Comments
 (0)