From 96dff1716b50517c6c154bf15601ca6397ff6adb Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 9 Jun 2025 13:07:45 -0400 Subject: [PATCH 1/3] DOCSP-50559: query guids --- .../serialization/guid-serialization.txt | 37 +++++++++++++++++-- source/upgrade/v3.txt | 11 ++++-- 2 files changed, 41 insertions(+), 7 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 0b45bf53..19dd7beb 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: @@ -217,6 +218,35 @@ method: var objectSerializer = new ObjectSerializer(objectDiscriminatorConvention, GuidRepresentation.Standard); BsonSerializer.RegisterSerializer(objectSerializer); +.. _csharp-guid-query: + +Query GUIDs +----------- + +You can query on standard (subtype 4) GUID values by using the +``BsonValue.Create()`` method. First, create a GUID value by using the +``Guid()`` constructor. Then, pass the GUID to the +``BsonValue.Create()`` method to instantiate a ``BsonValue`` to use in +your query filter, as shown in the following code: + +.. code-block:: csharp + + var guid = new Guid("33221100-5544-7766-8899-aabbccddeeff"); + var filter = new BsonDocument("guidField", BsonValue.Create(guid)); + +To query on 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 + + var guid = new Guid("00112233-4455-6677-8899-aabbccddeeff"); + var legacyGuid = new BsonBinaryData(guid, GuidRepresentation.CSharpLegacy); + var filter = new BsonDocument("legacyGuidField", legacyGuid); + Additional Information ---------------------- @@ -227,4 +257,5 @@ 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..a617e96b 100644 --- a/source/upgrade/v3.txt +++ b/source/upgrade/v3.txt @@ -111,9 +111,11 @@ 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, see :ref:`csharp-guid-query` in the GUIDs 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 +259,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. From ada9b5f482d6b93dcb48e7fd6dfc23f2a76d4b15 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 10 Jun 2025 10:17:44 -0400 Subject: [PATCH 2/3] RB restructure --- .../serialization/guid-serialization.txt | 54 +++++++------------ source/upgrade/v3.txt | 3 +- 2 files changed, 22 insertions(+), 35 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 19dd7beb..7ca9331e 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -120,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-query: + +.. 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: - The ``CSharpLegacy``, ``JavaLegacy``, and ``PythonLegacy`` GUID representations are - all equivalent to ``BsonBinaryData`` subtype 3, but use different byte orders. + .. code-block:: csharp + :emphasize-lines: 2 + + 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. @@ -218,35 +234,6 @@ method: var objectSerializer = new ObjectSerializer(objectDiscriminatorConvention, GuidRepresentation.Standard); BsonSerializer.RegisterSerializer(objectSerializer); -.. _csharp-guid-query: - -Query GUIDs ------------ - -You can query on standard (subtype 4) GUID values by using the -``BsonValue.Create()`` method. First, create a GUID value by using the -``Guid()`` constructor. Then, pass the GUID to the -``BsonValue.Create()`` method to instantiate a ``BsonValue`` to use in -your query filter, as shown in the following code: - -.. code-block:: csharp - - var guid = new Guid("33221100-5544-7766-8899-aabbccddeeff"); - var filter = new BsonDocument("guidField", BsonValue.Create(guid)); - -To query on 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 - - var guid = new Guid("00112233-4455-6677-8899-aabbccddeeff"); - var legacyGuid = new BsonBinaryData(guid, GuidRepresentation.CSharpLegacy); - var filter = new BsonDocument("legacyGuidField", legacyGuid); - Additional Information ---------------------- @@ -257,5 +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>`__ +- `GuidRepresentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.GuidRepresentation.html>`__ diff --git a/source/upgrade/v3.txt b/source/upgrade/v3.txt index a617e96b..5fd1b806 100644 --- a/source/upgrade/v3.txt +++ b/source/upgrade/v3.txt @@ -114,7 +114,8 @@ Version 3.0 Breaking Changes - 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, see :ref:`csharp-guid-query` in the GUIDs guide. + view an example, 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 From 7bfd6140088da9e024a94a520fa390d7ddb51e6e Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 10 Jun 2025 10:56:34 -0400 Subject: [PATCH 3/3] RB small fix --- source/fundamentals/serialization/guid-serialization.txt | 2 +- source/upgrade/v3.txt | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/fundamentals/serialization/guid-serialization.txt index 7ca9331e..24ba397f 100644 --- a/source/fundamentals/serialization/guid-serialization.txt +++ b/source/fundamentals/serialization/guid-serialization.txt @@ -124,7 +124,7 @@ The ``CSharpLegacy``, ``JavaLegacy``, and ``PythonLegacy`` GUID representations are all equivalent to ``BsonBinaryData`` subtype 3, but use different byte orders. -.. _csharp-guid-query: +.. _csharp-guid-legacy-construct: .. note:: Construct Legacy GUIDs diff --git a/source/upgrade/v3.txt b/source/upgrade/v3.txt index 5fd1b806..87b79d80 100644 --- a/source/upgrade/v3.txt +++ b/source/upgrade/v3.txt @@ -114,8 +114,9 @@ Version 3.0 Breaking Changes - 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, see the :ref:`Construct Legacy GUIDs - ` note in the GUID Serialization guide. + 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