DOCSP-50559: query guids (#646)

* DOCSP-50559: query guids

* RB restructure

* RB small fix

Author: rustagir

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. </reference/bson-types/#binary-data>`
 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>`__
+- `GuidRepresentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.GuidRepresentation.html>`__

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 <csharp-guid-legacy-construct>` 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.
+  To learn more about GUID serialization, see the :ref:`csharp-guids`
+  guide.