From 33b4fbe28340420cab14699c7e2c0256ad09383a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 19 Sep 2024 17:06:40 -0500 Subject: [PATCH 1/5] wip --- .../serialization/guid-serialization.txt | 66 ++++--------------- source/upgrade.txt | 23 +++++++ 2 files changed, 36 insertions(+), 53 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 4c14d239..1f0fa4d5 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -41,66 +41,26 @@ created ``BsonBinaryData`` subtype 4. Use ``BsonBinaryData`` subtype 4 for all new GUIDs. -GuidRepresentationMode ----------------------- In many MongoDB collections, all GUID fields use the same subtype of ``BsonBinaryData``. Some older collections, however, may contain some GUID fields that use subtype 3 and others that use subtype 4. -To ensure that the driver serializes and deserializes all GUIDs correctly, -you should set the ``BsonDefaults.GuidRepresentationMode`` property to one of the -following ``GuidRepresentationMode`` values: - -V2 -~~ - -``GuidRepresentationMode.V2`` assumes that all GUIDs in a document use the same -``BsonBinaryData`` subtype. In this mode, GUID representation is -controlled by the reader or writer, not the serializer. - -``V2`` is the default ``GuidRepresentationMode``. - -.. note:: - - When version 3 of the {+driver-short+} is released, support for ``GuidRepresentationMode.V2`` - will be removed from the driver and ``V3`` will become the default. - -V3 -~~ -``GuidRepresentationMode.V3`` allows fields in the same document to use different -GUID formats. -In this mode, GUID representation is controlled at the property level by configuring the +The driver allows fields in the same document to use different +GUID formats. GUID representation is controlled at the property level by configuring the serializer for each property. -To use ``GuidRepresentationMode.V3``, run the following line of code. You should run this -code during the bootstrapping phase of your application, before creating -a ``MongoClient`` object. +Serializing GUIDs +----------------- -.. code-block:: csharp - - BsonDefaults.GuidRepresentationMode = GuidRepresentationMode.V3; - -Running in ``V3`` mode changes the behavior of the driver in the following ways: - -- The ``BsonBinaryReader.ReadBinaryData()`` method ignores ``readerSettings.GuidRepresentation`` -- The ``BsonBinaryWriter.WriteBinaryData()`` method ignores ``writerSettings.GuidRepresentation`` -- The ``JsonReader.ReadBinaryData()`` method ignores ``readerSettings.GuidRepresentation`` -- ``JsonWriter`` ignores ``writerSettings.GuidRepresentation`` -- Calling the ``BsonBinaryData.ToGuid()`` method without the ``GuidRepresentation`` - parameter works only on GUIDs of subtype 4. +The driver handles GUID serialization at the level of individual +properties. You must ensure that +each GUID field is serialized and deserialized correctly. .. note:: - You can't use both ``GuidRepresentationMode.V2`` and ``GuidRepresentationMode.V3`` - in a single application. - -Serializing GUIDs in V3 ------------------------ - -``GuidRepresentationMode.V3`` handles GUID serialization at the level of individual -properties. This mode is more flexible than ``V2``, but it also means you must ensure that -each GUID field is serialized and deserialized correctly. + Default value is unspecified. Driver throws an exception rather than guessing. + You must specify the format for every GUID, or globally register a serializer. If you're using the {+driver-short+} to :ref:`automap your {+language+} classes to document schemas `, you can use the ``BsonGuidRepresentation`` attribute on a GUID property @@ -150,12 +110,12 @@ in your application, such as during the bootstrapping phase: serializer for the most commonly used GUID subtype, then use the ``BsonGuidRepresentation`` attribute to denote any GUID properties of another subtype. -Serializing Objects in V3 -------------------------- +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 when using -``V3``, you should select the correct GUID representation when constructing your +To ensure that GUIDs in these objects are serialized and deserialized correctly, +you should select the correct GUID representation when constructing your ``ObjectSerializer``. The following code sample shows how to diff --git a/source/upgrade.txt b/source/upgrade.txt index c8b7c9b3..7ab72209 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -72,6 +72,29 @@ Version 3.0 Potential Breaking Change - The LINQ2 provider has been removed from this version of the driver. You must use LINQ3 for all LINQ queries. +- In driver v2.x, you could choose between two GUID representation modes. + ``GuidRepresentationMode.V2`` was the default. This mode assumed that all GUIDs in a + document use the same ``BsonBinaryData`` subtype, and GUID representation was + controlled by the reader or writer, not the serializer. + + In driver v3.0, ``GuidRepresentationMode.V3`` is the only option. Running in this mode + changes the behavior of the driver in the following ways: + This mode is more flexible than ``V2``, but it also means you must ensure that + each GUID field is serialized and deserialized correctly. + + - The methods in the ``BsonBinaryReader``, ``BsonBinaryWriter``, ``JsonReader``, and + ``JsonWriter`` classes no longer check the ``GuidRepresentationMode``. + - Removed the ``BsonBinaryData(Guid)`` constructor. To construct a ``BsonBinaryData`` + object from a GUID, use the ``BsonBinaryData.Create(Guid, GuidRepresentation)`` constructor. + - Removed the ``BsonBinaryData.GuidRepresentation`` property. This information is no + longer stored in the ``BsonBinaryData`` object and must be specified by the user. + - Calling the ``BsonBinaryData.ToGuid()`` method without the ``GuidRepresentation`` + parameter works only on GUIDs of subtype 4. + +If you map your data only to POCOs, you can ignore the GUID representation. However, if you +serialize and deserialize BSON documents directly, you must specify the GUID representation and ensure that +it matches the format used by your documents. + .. _csharp-breaking-changes-2.28.0: Version 2.28.0 Potential Breaking Change From e207f58b5df1ecd52cb1e069775d2a8301df51b4 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 20 Sep 2024 13:08:50 -0500 Subject: [PATCH 2/5] wip --- .../serialization/guid-serialization.txt | 130 +++++++++++++----- source/upgrade.txt | 32 ++--- 2 files changed, 107 insertions(+), 55 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 1f0fa4d5..6d9aaca6 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -24,47 +24,104 @@ In this guide, you can learn how to serialize **globally unique identifiers** (`GUIDs `__), also known as **universally unique identifiers** (UUIDs). -.. tip:: +A Short History of MongoDB GUIDs +-------------------------------- - In MongoDB applications, ``ObjectId`` can be used as a unique identifier for - a document. Consider using ``ObjectId`` in place of a GUID with MongoDB - applications where possible. +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: + +.. code-block:: -A GUID is a 16-byte integer that you can use as a unique ID for a MongoDB document. -Originally, GUIDs in MongoDB were represented as ``BsonBinaryData`` values of subtype 3. -Subtype 3 did not standardize the byte order during serialization, which led to -inconsistent serialization across MongoDB drivers. -To standardize the byte order and ensure consistent serialization across drivers, we -created ``BsonBinaryData`` subtype 4. + 00112233-4455-6677-8899-aabbccddeeff -.. note:: - - Use ``BsonBinaryData`` subtype 4 for all new GUIDs. +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. + +Use the following tabs to compare the ways in which different MongoDB language drivers +encoded the preceding GUID to ``BsonBinaryData`` subtype 3: + +.. tabs:: + .. tab:: {+driver-short+} + :tabid: csharp -In many MongoDB collections, all GUID fields use the same subtype of ``BsonBinaryData``. -Some older collections, however, may contain some GUID fields that -use subtype 3 and others that use subtype 4. + .. code-block:: csharp -The driver allows fields in the same document to use different -GUID formats. GUID representation is controlled at the property level by configuring the -serializer for each property. + 33221100-5544-7766-8899-aabbccddeeff + + .. tab:: PyMongo + :tabid: pymongo + + .. code-block:: python + + 00112233-4455-6677-8899-aabbccddeeff + + .. tab:: Java Driver + :tabid: java + + .. code-block:: java + + 77665544-3322-1100-ffee-ddccbbaa9988 + +To standardize GUID byte order, we added ``BsonBinaryData`` subtype 4, which all +MongoDB drivers encode in the same way. We recommend using +``BsonBinaryData`` subtype 4 for all new GUIDs. + +For a list of all ``BsonBinaryData`` subtypes, see the +API documentation for the `BsonBinarySubType <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonBinarySubType.html>`__ +enum. + +.. tip:: + + In MongoDB applications, ``ObjectId`` can be used as a unique identifier for + a document. Consider using ``ObjectId`` in place of a GUID with MongoDB + applications where possible. Serializing GUIDs ----------------- -The driver handles GUID serialization at the level of individual -properties. You must ensure that -each GUID field is serialized and deserialized correctly. +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 {+driver-short+} handles GUID +serialization at the level of individual properties. -.. note:: +If you're using the {+driver-short+} to +:ref:`automap your {+language+} 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 +``GuidRepresentation`` enum, which contains the following members: - Default value is unspecified. Driver throws an exception rather than guessing. - You must specify the format for every GUID, or globally register a serializer. +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 10 10 -If you're using the {+driver-short+} to :ref:`automap your {+language+} classes to document schemas `, -you can use the ``BsonGuidRepresentation`` attribute on a GUID property -to specify the representation: + * - 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 code example specifies the ``Standard`` GUID representation for the +``G`` property: .. code-block:: csharp @@ -76,20 +133,13 @@ to specify the representation: public Guid G { get; set; } } -.. note:: - - ``GuidRepresentation.Standard`` is equivalent to ``BsonBinaryData`` subtype 4. - Other GUID representations in the {+driver-short+}, such as ``CSharpLegacy``, - ``JavaLegacy``, and ``PythonLegacy``, are equivalent to subtype 3 but use - different byte orders. - 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 ``GuidSerializer`` -for serializing GUID representations of subtype 4: +The following code sample creates an instance of the ``GuidSerializer`` class +for serializing properties that use ``BsonBinaryData`` subtype 4: .. code-block:: @@ -110,6 +160,12 @@ in your application, such as during the bootstrapping phase: 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 ------------------- diff --git a/source/upgrade.txt b/source/upgrade.txt index 7ab72209..0a50b3ce 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -72,28 +72,24 @@ Version 3.0 Potential Breaking Change - The LINQ2 provider has been removed from this version of the driver. You must use LINQ3 for all LINQ queries. -- In driver v2.x, you could choose between two GUID representation modes. - ``GuidRepresentationMode.V2`` was the default. This mode assumed that all GUIDs in a - document use the same ``BsonBinaryData`` subtype, and GUID representation was - controlled by the reader or writer, not the serializer. - - In driver v3.0, ``GuidRepresentationMode.V3`` is the only option. Running in this mode - changes the behavior of the driver in the following ways: - This mode is more flexible than ``V2``, but it also means you must ensure that - each GUID field is serialized and deserialized correctly. +- Previous versions of the {+driver-short+} supported two GUID representation modes. + In version 3.0, ``GuidRepresentationMode.V3`` is the only supported mode. This change + has the following effects on the driver: - The methods in the ``BsonBinaryReader``, ``BsonBinaryWriter``, ``JsonReader``, and ``JsonWriter`` classes no longer check the ``GuidRepresentationMode``. - - Removed the ``BsonBinaryData(Guid)`` constructor. To construct a ``BsonBinaryData`` + - The ``BsonBinaryData(Guid)`` constructor has been removed. To construct a ``BsonBinaryData`` object from a GUID, use the ``BsonBinaryData.Create(Guid, GuidRepresentation)`` constructor. - - Removed the ``BsonBinaryData.GuidRepresentation`` property. This information is no - longer stored in the ``BsonBinaryData`` object and must be specified by the user. - - Calling the ``BsonBinaryData.ToGuid()`` method without the ``GuidRepresentation`` - parameter works only on GUIDs of subtype 4. - -If you map your data only to POCOs, you can ignore the GUID representation. However, if you -serialize and deserialize BSON documents directly, you must specify the GUID representation and ensure that -it matches the format used by your documents. + - The ``BsonBinaryData.GuidRepresentation`` property has been removed. + - You can call the ``BsonBinaryData.ToGuid()`` method only on ``BsonBinaryData`` + objects of subtype 4. If the object has any other subtype, you must call the + ``BsonBinaryData.ToGuid(GuidRepresentation)`` method and specify the subtype. + + .. note:: + + The preceding changes affect your application only if you serialize and deserialize + BSON documents directly. If you map your MongoDB documents only to :ref:`csharp-poco`, + the ``GuidRepresentationMode`` doesn't affect your application. .. _csharp-breaking-changes-2.28.0: From b2e682dbf45748da00934c1121d6f5ce61723001 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 20 Sep 2024 13:25:57 -0500 Subject: [PATCH 3/5] fixes --- source/fundamentals/serialization/guid-serialization.txt | 8 ++++---- source/upgrade.txt | 8 +++----- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 6d9aaca6..851640bd 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -155,10 +155,10 @@ in your application, such as during the bootstrapping phase: .. tip:: - When you're working with two 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. + 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:: diff --git a/source/upgrade.txt b/source/upgrade.txt index 0a50b3ce..368826e2 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -85,11 +85,9 @@ Version 3.0 Potential Breaking Change objects of subtype 4. If the object has any other subtype, you must call the ``BsonBinaryData.ToGuid(GuidRepresentation)`` method and specify the subtype. - .. note:: - - The preceding changes affect your application only if you serialize and deserialize - BSON documents directly. If you map your MongoDB documents only to :ref:`csharp-poco`, - the ``GuidRepresentationMode`` doesn't affect your application. + The preceding changes affect your application only if you serialize and deserialize + BSON documents directly. If you map your MongoDB documents only to :ref:`csharp-poco`, + the ``GuidRepresentationMode`` doesn't affect your application. .. _csharp-breaking-changes-2.28.0: From cda9e0524d41d164d90cf253587dd2015a00baf7 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Sat, 21 Sep 2024 10:32:14 -0500 Subject: [PATCH 4/5] feedback --- .../serialization/guid-serialization.txt | 55 ++++++++++++------- source/upgrade.txt | 5 +- 2 files changed, 38 insertions(+), 22 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 851640bd..174ff30e 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -24,13 +24,21 @@ In this guide, you can learn how to serialize **globally unique identifiers** (`GUIDs `__), also known as **universally unique identifiers** (UUIDs). -A Short History of MongoDB GUIDs --------------------------------- +.. tip:: ObjectId + + In MongoDB applications, you can use the + `ObjectId <{+new-api-root+}/api/MongoDB.Bson/MongoDB.Bson.ObjectId.html>`__ type + as a unique identifier for a document. Consider using ``ObjectId`` in place of a GUID + 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: .. code-block:: + :copyable: false 00112233-4455-6677-8899-aabbccddeeff @@ -47,6 +55,7 @@ encoded the preceding GUID to ``BsonBinaryData`` subtype 3: :tabid: csharp .. code-block:: csharp + :copyable: false 33221100-5544-7766-8899-aabbccddeeff @@ -54,6 +63,7 @@ encoded the preceding GUID to ``BsonBinaryData`` subtype 3: :tabid: pymongo .. code-block:: python + :copyable: false 00112233-4455-6677-8899-aabbccddeeff @@ -61,23 +71,18 @@ encoded the preceding GUID to ``BsonBinaryData`` subtype 3: :tabid: java .. code-block:: java + :copyable: false 77665544-3322-1100-ffee-ddccbbaa9988 -To standardize GUID byte order, we added ``BsonBinaryData`` subtype 4, which all -MongoDB drivers encode in the same way. We recommend using -``BsonBinaryData`` subtype 4 for all new GUIDs. +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 <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonBinarySubType.html>`__ enum. -.. tip:: - - In MongoDB applications, ``ObjectId`` can be used as a unique identifier for - a document. Consider using ``ObjectId`` in place of a GUID with MongoDB - applications where possible. - Serializing GUIDs ----------------- @@ -86,11 +91,9 @@ MongoDB collections might contain some GUID fields that use subtype 3 and others subtype 4. To account for these differences, the {+driver-short+} handles GUID serialization at the level of individual properties. -If you're using the {+driver-short+} to -:ref:`automap your {+language+} 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 -``GuidRepresentation`` enum, which contains the following members: +The {+driver-short+} uses the ``GuidRepresentation`` enum to represent the different +``BsonBinaryData`` subtypes. The following table shows the ``GuidRepresentation`` enum +members and the corresponding ``BsonBinaryData`` subtypes: .. list-table:: :header-rows: 1 @@ -120,6 +123,17 @@ to specify its representation. This attribute accepts a value from the 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 {+driver-short+} to +:ref:`automap your {+language+} 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: @@ -133,6 +147,9 @@ The following code example specifies the ``Standard`` GUID representation for th 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 @@ -171,8 +188,7 @@ 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, -you should select the correct GUID representation when constructing your -``ObjectSerializer``. +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: @@ -208,5 +224,4 @@ guide, see the following API documentation: - `GuidRepresentationMode <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.GuidRepresentationMode.html>`__ - `BsonGuidRepresentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Attributes.BsonGuidRepresentationAttribute.html>`__ - `GuidSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Serializers.GuidSerializer.html>`__ -- `ObjectSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Serializers.ObjectSerializer.html>`__ - +- `ObjectSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Serializers.ObjectSerializer.html>`__ \ No newline at end of file diff --git a/source/upgrade.txt b/source/upgrade.txt index 368826e2..6af3f655 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -76,8 +76,6 @@ Version 3.0 Potential Breaking Change In version 3.0, ``GuidRepresentationMode.V3`` is the only supported mode. This change has the following effects on the driver: - - The methods in the ``BsonBinaryReader``, ``BsonBinaryWriter``, ``JsonReader``, and - ``JsonWriter`` classes no longer check the ``GuidRepresentationMode``. - The ``BsonBinaryData(Guid)`` constructor has been removed. To construct a ``BsonBinaryData`` object from a GUID, use the ``BsonBinaryData.Create(Guid, GuidRepresentation)`` constructor. - The ``BsonBinaryData.GuidRepresentation`` property has been removed. @@ -89,6 +87,9 @@ Version 3.0 Potential Breaking Change BSON documents directly. If you map your MongoDB documents only to :ref:`csharp-poco`, the ``GuidRepresentationMode`` doesn't affect your application. + To learn more about serializing GUIDs in the {+driver-short+}, see the + :ref:`GUIDs ` page. + .. _csharp-breaking-changes-2.28.0: Version 2.28.0 Potential Breaking Change From 7067dbda308e21597e51b8e640805bce5479b649 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 23 Sep 2024 09:53:15 -0500 Subject: [PATCH 5/5] feedback --- .../fundamentals/serialization/guid-serialization.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 174ff30e..647cc6d1 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -28,8 +28,8 @@ also known as **universally unique identifiers** (UUIDs). In MongoDB applications, you can use the `ObjectId <{+new-api-root+}/api/MongoDB.Bson/MongoDB.Bson.ObjectId.html>`__ type - as a unique identifier for a document. Consider using ``ObjectId`` in place of a GUID - in MongoDB applications where possible. + as a unique identifier for a document. Consider using ``ObjectId`` instances in place + of GUIDs in MongoDB applications where possible. GUIDs in MongoDB ---------------- @@ -43,11 +43,12 @@ 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 +values of :manual:`subtype 3. ` +Because subtype 3 didn't standardize the byte order of GUIDs during encoding, different MongoDB drivers encoded GUIDs with different byte orders. -Use the following tabs to compare the ways in which different MongoDB language drivers -encoded the preceding GUID to ``BsonBinaryData`` subtype 3: +The following tabs show different driver encodings of the preceding GUID to +``BsonBinaryData`` subtype 3: .. tabs::