diff --git a/source/fundamentals/serialization/class-mapping.txt b/source/fundamentals/serialization/class-mapping.txt index db80899a..48f0d245 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. @@ -95,9 +98,34 @@ 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 +~~~~~~~~~~~ + +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,89 @@ 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 + :emphasize-lines: 4 + + 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 + :emphasize-lines: 4 + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + 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 + :emphasize-lines: 4 + + 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 +```````` + +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``. + +The following code specifies the ``Standard`` GUID representation when +registering the class map: + +.. code-block:: csharp + :emphasize-lines: 4 + + 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 7d7f2534..90be6d19 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,45 @@ the default value (``null``), the driver throws an exception: public Guid Id { get; set; } } +.. _csharp-poco-omit-fields: + +Omit Fields +~~~~~~~~~~~ + +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 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 ~~~~~~~~~~~~~~~~~ -By default, the driver serializes undefined properties to fields with ``null`` -values. To ignore undefined properties during serialization, use the ``[BsonIgnore]`` +By default, the driver serializes uninitialized properties with ``null`` +values. To ignore empty 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 uninitialized: .. code-block:: csharp :copyable: true @@ -443,11 +479,36 @@ serializing the ``YearBuilt`` property if it is undefined: { public Guid Id { get; set; } - [BsonIgnore] - public int YearBuilt { get; set; } + [BsonIgnoreIfNull] 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 + :emphasize-lines: 4 + + BsonClassMap.RegisterClassMap(classMap => + { + classMap.AutoMap(); + classMap.MapMember(h => h.Style).SetIgnoreIfNull(true); + }); + +.. note:: Value Type Properties + + You cannot use the ``[BsonIgnoreIfNull]`` attribute or + ``SetIgnoreIfNull()`` method to prevent uninitialized value type + 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. + +.. _csharp-poco-default-values: + Customize Default Values ~~~~~~~~~~~~~~~~~~~~~~~~