diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 0b45bf53..24ba397f 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -40,12 +40,13 @@ The following code block shows an example GUID: .. code-block:: :copyable: false - 00112233-4455-6677-8899-aabbccddeeff + 00112233-4455-6677-8899-aabbccddeeff Originally, MongoDB represented GUIDs as ``BsonBinaryData`` 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. +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: @@ -119,10 +120,26 @@ members and the corresponding ``BsonBinaryData`` subtypes: * - ``Unspecified`` - N/A -.. note:: +The ``CSharpLegacy``, ``JavaLegacy``, and ``PythonLegacy`` GUID +representations are all equivalent to ``BsonBinaryData`` subtype 3, but +use different byte orders. + +.. _csharp-guid-legacy-construct: + +.. note:: Construct Legacy GUIDs + + To construct legacy (subtype 3) GUID values, you must use the + ``BsonBinaryData()`` constructor to explicitly specify the legacy GUID + type by passing the ``GuidRepresentation.CSharpLegacy`` parameter. The + following code demonstrates how to create a legacy GUID to use in a + query filter: + + .. code-block:: csharp + :emphasize-lines: 2 - The ``CSharpLegacy``, ``JavaLegacy``, and ``PythonLegacy`` GUID representations are - all equivalent to ``BsonBinaryData`` subtype 3, but use different byte orders. + var guid = new Guid("00112233-4455-6677-8899-aabbccddeeff"); + var legacyGuid = new BsonBinaryData(guid, GuidRepresentation.CSharpLegacy); + var filter = new BsonDocument("legacyGuidField", legacyGuid); The following sections describe the ways in which you can configure GUID representation in your application. @@ -227,4 +244,4 @@ guide, see the following API documentation: - `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>`__ -- `GuidRepresentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.GuidRepresentation.html>`__ \ No newline at end of file +- `GuidRepresentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.GuidRepresentation.html>`__ diff --git a/source/upgrade/v3.txt b/source/upgrade/v3.txt index 7d45c479..87b79d80 100644 --- a/source/upgrade/v3.txt +++ b/source/upgrade/v3.txt @@ -111,9 +111,13 @@ Version 3.0 Breaking Changes In version 3.0, ``GuidRepresentationMode.V3`` is the only supported mode. This change has the following effects on the driver: - - 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. + - The ``BsonBinaryData(Guid)`` constructor has been removed. To + construct a ``BsonBinaryData`` object from a GUID, use the + ``BsonBinaryData.Create(Guid, GuidRepresentation)`` constructor. To + view an example of creating a legacy GUID, see the :ref:`Construct + Legacy GUIDs ` note in the GUID + Serialization guide. + - 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. @@ -257,4 +261,5 @@ Version 3.0 Breaking Changes configure ``GUID`` serialization on a case-by-case basis without registering a global ``GuidSerializer``. - To learn more about GUID serialization, see the :ref:`csharp-guids` guide. \ No newline at end of file + To learn more about GUID serialization, see the :ref:`csharp-guids` + guide.