DOCSP-45943: dateonly serialization

source/fundamentals/serialization.txt

@@ -54,15 +54,26 @@ Serializer Registry
 The serializer registry contains all registered serializers that are available
 to your application. Many of the built-in serializers are automatically
 registered to the serializer registry during startup of your application.
-However, before you can use a custom serializer, you must add it to the
+
+Register a Serializer
+~~~~~~~~~~~~~~~~~~~~~
+
+Before you can use a custom serializer, you must add it to the
 serializer registry, as shown in the following example:
 
 .. code-block:: csharp
 
-   BsonSerializer.RegisterSerializer(new CustomTypeSerializer()); 
+   BsonSerializer.RegisterSerializer(new CustomTypeSerializer());
+
+After you register the serializer, the driver uses it to serialize any
+values that are mapped by the serializer.
+
+Access a Serializer from the Registry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To access the serializer registry, use the ``SerializerRegistry`` property
-of the ``BsonSerializer`` class as follows:
+To access a specific serializer from the registry, use the
+``SerializerRegistry`` property of the ``BsonSerializer`` class as
+follows:
 
 .. code-block:: csharp
 

source/fundamentals/serialization/poco.txt

@@ -542,8 +542,6 @@ The previous code example sets the following serialization behavior:
 - Because ``1900`` is the default value for this property, the driver will ignore the
   property if it has this value.
 
-
-
 Customize DateTime Serialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -610,6 +608,58 @@ registering the class map:
    The ``DateTimeKind`` enum is part of the {+framework+}. For more information on
    its members, see the `Microsoft documentation for the DateTimeKind enum. <https://learn.microsoft.com/en-us/dotnet/api/system.datetimekind?view=net-8.0>`__
 
+.. _csharp-poco-dateonly-attr:
+
+Custom DateOnly Serialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To customize how the {+driver-short+} serializes `DateOnly
+<https://learn.microsoft.com/en-us/dotnet/api/system.dateonly?view=net-8.0>`__
+properties, use the ``[BsonDateOnlyOptions()]`` attribute and specify
+the following settings:
+
+- ``Representation``: Set to a ``BsonType`` instance that specifies how
+  the ``DateOnly`` value is stored in MongoDB.
+
+- ``DocumentFormat``: Set only if you set the ``Representation``
+  property to ``BsonType.Document``. You can set ``DocumentFormat`` to
+  one of the following ``DateOnlyDocumentFormat`` enum values:
+
+  - ``DateTimeTicks`` (default): Document contains ``DateTime``
+    (``BsonType.DateTime``) and ``Ticks`` (``BsonType.Int64``) fields
+
+  - ``YearMonthDay``: Document contains ``Year``, ``Month``, and
+    ``Day`` fields, which have ``BsonType.Int32`` values
+
+In the following code example, the ``PatientRecord`` class contains a
+``DateOfBirth`` property that has a ``DateOnly`` value. The
+attribute directs the driver to store the value as a nested document
+that contains fields for the given year, month, and day.
+
+.. code-block:: csharp
+   :copyable: true
+   :emphasize-lines: 5
+
+   public class PatientRecord
+   {
+       public Guid Id { get; set; }
+
+       [BsonDateOnlyOptions(BsonType.Document, DateOnlyDocumentFormat.YearMonthDay)]
+       public DateOnly DateOfBirth { get; set; }
+   }
+
+.. tip:: Use the DateOnlySerializer to Set Global Behavior
+
+   Instead of using the ``[BsonDateOnlyOptions()]`` attribute at the
+   property level, you can register a ``DateOnlySerializer`` object to
+   apply serialization behavior globally:
+
+   .. code-block:: csharp
+
+      BsonSerializer.RegisterSerializer(
+          new DateOnlySerializer(BsonType.Document, DateOnlyDocumentFormat.YearMonthDay)
+      );
+
 Customize Dictionary Serialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -752,4 +802,5 @@ guide, see the following API documentation:
 - `[BsonDateTimeOptions()] <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Attributes.BsonDateTimeOptionsAttribute.html>`__
 - `[BsonDictionaryOptions()] <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Attributes.BsonDictionaryOptionsAttribute.html>`__
 - `ConventionPack <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ConventionPack.html>`__
-- `InsertOne() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertMany.html>`__
+- `InsertOne()
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertMany.html>`__

source/whats-new.txt

@@ -122,6 +122,13 @@ The 3.2 driver release includes the following new features:
   To learn more about Atlas Vector Search with the {+driver-short+}, see the
   :ref:`csharp-atlas-vector-search` guide.
 
+- Adds the ``DocumentFormat`` property to the ``DateOnlySerializer``.
+  This property allows you to customize the way that the driver stores
+  ``DateOnly`` values in nested documents. This release also adds the
+  ``[BsonDateOnlyOptions()]`` attribute to customize serialization
+  behavior for ``DateOnly`` values at the property level. To learn more,
+  see the :ref:`csharp-poco-dateonly-attr` section of the POCOs guide.
+
 .. _csharp-version-3.1:
 
 What's New in 3.1