From 403ad48acee5ee5e329b1e6380085518ce180672 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 14 Apr 2025 09:15:38 -0400 Subject: [PATCH 1/3] DOCSP-42606: class maps improvements --- source/fundamentals/serialization/poco.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index 7d7f2534..540a1bc3 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -431,7 +431,7 @@ Omit Empty Fields ~~~~~~~~~~~~~~~~~ By default, the driver serializes undefined properties to fields with ``null`` -values. To ignore undefined properties during serialization, use the ``[BsonIgnore]`` +values. To ignore undefined properties during serialization, use the ``[BsonIgnoreIfNull]`` attribute. The following code shows how you can prevent the driver from serializing the ``YearBuilt`` property if it is undefined: @@ -443,7 +443,7 @@ serializing the ``YearBuilt`` property if it is undefined: { public Guid Id { get; set; } - [BsonIgnore] + [BsonIgnoreIfNull] public int YearBuilt { get; set; } public string Style { get; set; } } From f37f64c89508c2805369044d493aaba902810da1 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 15 Apr 2025 10:48:56 -0400 Subject: [PATCH 2/3] wip --- .../serialization/class-mapping.txt | 111 +++++++++++++++++- source/fundamentals/serialization/poco.txt | 60 +++++++++- 2 files changed, 166 insertions(+), 5 deletions(-) diff --git a/source/fundamentals/serialization/class-mapping.txt b/source/fundamentals/serialization/class-mapping.txt index db80899a..8a5187e8 100644 --- a/source/fundamentals/serialization/class-mapping.txt +++ b/source/fundamentals/serialization/class-mapping.txt @@ -21,10 +21,13 @@ Overview -------- In this guide, you can learn how to customize the way the {+driver-long+} -maps BSON documents to and from {+language+} classes. You should read this page +maps BSON documents to and from {+language+} classes. You can read this page to learn more about the default class mapping behavior, or if you need to customize the way the driver serializes or deserializes your data. +You can also use POCO attributes to set serialization behavior. To learn +more, see the :ref:`csharp-poco` guide. + Automatic Class Mapping ----------------------- @@ -69,7 +72,7 @@ class: classMap.MapMember(p => p.Hobbies); }); -.. important:: +.. important:: When to Register a Class Map You must register a class map *before* it's needed in your code. We recommend registering class maps prior to initializing a connection with MongoDB. @@ -98,6 +101,31 @@ You can customize how the driver serializes and deserializes documents at the cl level by using attributes with the class or by calling methods while registering a class map. +Omit Fields +~~~~~~~~~~~ + +By default, the driver serializes all fields in your POCOS, whether you +define them or not. You can prevent specified fields from being +serialized by using the ``UnmapMember()`` method when registering a +class map. + +The following example shows how to create a class map to prevent the +``Age`` property from being serialized: + +.. code-block:: csharp + :emphasize-lines: 4 + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + classMap.UnmapMember(p => p.Age); + }); + +.. tip:: + + To learn about how to set this behavior by using a field attribute, + see the :ref:`csharp-poco-omit-fields` section of the POCOs guide. + Ignore Extra Elements ~~~~~~~~~~~~~~~~~~~~~ @@ -134,6 +162,85 @@ You can also ignore any extra elements when registering a class map: classMap.SetIgnoreExtraElements(true); }); +Identify Id Field +~~~~~~~~~~~~~~~~~ + +By default, the driver maps any public property named ``Id``, ``id``, or +``_id`` to the BSON ``_id`` field. To explicitly select the +property to map to the ``_id`` field, use the ``MapIdMember()`` class +map method. + +The following code sample maps the ``Identifier`` property to the +``_id`` field: + +.. code-block:: csharp + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + classMap.MapIdMember(p => p.Identifier); + }); + +String IDs +`````````` + +If you are using strings to represent your +documement IDs, you can use the ``IdMemberMap.SetSerializer()`` class +map method to serialize these values to ``ObjectId`` instances in +MongoDB. This way, you can customize how your ID values are represented +in your application while adhering to MongoDB best practices for ID +management in the database. + +The following example directs the driver to serialize string ID values +as ``ObjectId`` values: + +.. code-block:: csharp + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + classMap.MapIdMember(p => p.Identifier); + classMap.IdMemberMap.SetSerializer(new StringSerializer(BsonType.ObjectId)); + }); + +If you want the driver to generate valid 24-digit hex strings to +use as your ID values, you can chain the ``SetIdGenerator()`` method to +the ``MapIdMember()`` method and pass an instance of +``StringObjectIdGenerator``: + +.. code-block:: csharp + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + classMap.MapIdMember(p => p.Identifier).SetIdGenerator(StringObjectIdGenerator.Instance); + }); + +To learn more about ID generators, see the +:ref:`csharp-poco-specify-id-gen` section of the POCOs guide. + +GUID IDs +```````` + +You can use GUIDs instead of ``ObjectId`` values to represent your +document IDs in MongoDB. By default, the driver uses the +``GuidGenerator`` type to generate a unique value for the ID property. +You must specify the GUID representation by initializing a +``GuidSerializer``. + +The following code specifies the ``Standard`` GUID representation when +registering the class map: + +.. code-block:: csharp + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + classMap.IdMemberMap.SetSerializer(new GuidSerializer(GuidRepresentation.Standard)); + }); + +To learn more about serializing GUIDs, see the :ref:`csharp-guids` guide. + Mapping with Constructors ------------------------- diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index 540a1bc3..eea7c18c 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -266,6 +266,8 @@ The following code sample maps the ``Identifier`` property to the The ``_id`` field mapping logic described in this section only applies to the root document and does not apply to nested documents. +.. _csharp-poco-specify-id-gen: + Specify an ID Generator ``````````````````````` @@ -312,7 +314,9 @@ The following table describes the ID generators available in the public class House { public Guid Id { get; set; } - } + } + + To learn more, see the :ref:`csharp-guids` guide. * - ``ObjectId`` - The driver automatically uses the ``ObjectIdGenerator`` type for ID properties with @@ -427,13 +431,39 @@ the default value (``null``), the driver throws an exception: public Guid Id { get; set; } } +.. _csharp-poco-omit-fields: + +Omit Fields +~~~~~~~~~~~ + +By default, the driver serializes all fields in your POCOS, whether you +define them or not. To prevent the driver from serializing a specified +field, use the ``[BsonIgnore]`` attribute. The following code shows how +you can prevent the driver from serializing the ``YearBuilt`` property: + +.. code-block:: csharp + :copyable: true + :emphasize-lines: 5 + + public class House + { + public Guid Id { get; set; } + + [BsonIgnore] + public int YearBuilt { get; set; } + public string Style { get; set; } + } + +Even if you specify a value for the ``YearBuilt`` property, the field is +not saved in MongoDB. + Omit Empty Fields ~~~~~~~~~~~~~~~~~ By default, the driver serializes undefined properties to fields with ``null`` values. To ignore undefined properties during serialization, use the ``[BsonIgnoreIfNull]`` attribute. The following code shows how you can prevent the driver from -serializing the ``YearBuilt`` property if it is undefined: +serializing the ``Style`` property if it is undefined: .. code-block:: csharp :copyable: true @@ -444,10 +474,34 @@ serializing the ``YearBuilt`` property if it is undefined: public Guid Id { get; set; } [BsonIgnoreIfNull] - public int YearBuilt { get; set; } public string Style { get; set; } + public int YearBuilt { get; set; } } +You can also instruct the driver to ignore a property that contains a +``null`` value when you register the class map, as shown in the +following example: + +.. code-block:: csharp + :copyable: true + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + classMap.MapMember(h => h.Style).SetIgnoreIfNull(true); + }); + +.. note:: Numerical Properties + + You cannot use the ``[BsonIgnoreIfNull]`` attribute or + ``SetIgnoreIfNull()`` method to prevent undefined numerical + properties from being serialized, unless you set the properties as + nullable. Instead, use the ``[BsonIgnoreIfDefault]`` attribute or + ``SetIgnoreIfDefault()`` class map method, which are described in the + :ref:`csharp-poco-default-values` section of this guide. + +.. _csharp-poco-default-values: + Customize Default Values ~~~~~~~~~~~~~~~~~~~~~~~~ From 243c3c7c64ff7e1dce451da257aec073912bb920 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 15 Apr 2025 14:42:50 -0400 Subject: [PATCH 3/3] RM PR fixes 1 --- .../fundamentals/serialization/class-mapping.txt | 14 ++++++++++---- source/fundamentals/serialization/poco.txt | 12 ++++++++++-- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/source/fundamentals/serialization/class-mapping.txt b/source/fundamentals/serialization/class-mapping.txt index 8a5187e8..77b8332c 100644 --- a/source/fundamentals/serialization/class-mapping.txt +++ b/source/fundamentals/serialization/class-mapping.txt @@ -98,9 +98,11 @@ Customize Class Serialization ----------------------------- You can customize how the driver serializes and deserializes documents at the class -level by using attributes with the class or by calling methods while registering +level by applying attributes to the class or by calling methods while registering a class map. +.. _csharp-class-map-omit-fields: + Omit Fields ~~~~~~~~~~~ @@ -174,6 +176,7 @@ The following code sample maps the ``Identifier`` property to the ``_id`` field: .. code-block:: csharp + :emphasize-lines: 4 BsonClassMap.RegisterClassMap(classMap => { @@ -195,11 +198,11 @@ The following example directs the driver to serialize string ID values as ``ObjectId`` values: .. code-block:: csharp + :emphasize-lines: 4 BsonClassMap.RegisterClassMap(classMap => { classMap.AutoMap(); - classMap.MapIdMember(p => p.Identifier); classMap.IdMemberMap.SetSerializer(new StringSerializer(BsonType.ObjectId)); }); @@ -209,6 +212,7 @@ the ``MapIdMember()`` method and pass an instance of ``StringObjectIdGenerator``: .. code-block:: csharp + :emphasize-lines: 4 BsonClassMap.RegisterClassMap(classMap => { @@ -222,8 +226,9 @@ To learn more about ID generators, see the GUID IDs ```````` -You can use GUIDs instead of ``ObjectId`` values to represent your -document IDs in MongoDB. By default, the driver uses the +If your application uses GUIDs as unique identifiers in your documents, +you can register a class map to specify how ``Guid`` values are +serialized. By default, the driver uses the ``GuidGenerator`` type to generate a unique value for the ID property. You must specify the GUID representation by initializing a ``GuidSerializer``. @@ -232,6 +237,7 @@ The following code specifies the ``Standard`` GUID representation when registering the class map: .. code-block:: csharp + :emphasize-lines: 4 BsonClassMap.RegisterClassMap(classMap => { diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index eea7c18c..2c03ff20 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -454,9 +454,16 @@ you can prevent the driver from serializing the ``YearBuilt`` property: public string Style { get; set; } } -Even if you specify a value for the ``YearBuilt`` property, the field is +Even if you define the ``YearBuilt`` property, the field is not saved in MongoDB. +.. note:: + + You can define a class map to prevent specific fields from being + serialized. To learn more and view an example, see the + :ref:`csharp-class-map-omit-fields` section of the Class Mapping + guide. + Omit Empty Fields ~~~~~~~~~~~~~~~~~ @@ -484,6 +491,7 @@ following example: .. code-block:: csharp :copyable: true + :emphasize-lines: 4 BsonClassMap.RegisterClassMap(classMap => { @@ -495,7 +503,7 @@ following example: You cannot use the ``[BsonIgnoreIfNull]`` attribute or ``SetIgnoreIfNull()`` method to prevent undefined numerical - properties from being serialized, unless you set the properties as + properties from being serialized unless you mark the properties as nullable. Instead, use the ``[BsonIgnoreIfDefault]`` attribute or ``SetIgnoreIfDefault()`` class map method, which are described in the :ref:`csharp-poco-default-values` section of this guide.