DOCSP-45943: dateonly serialization

.github/pull_request_template.md

@@ -5,6 +5,7 @@
 JIRA - <https://jira.mongodb.org/browse/DOCSP-NNNNN>
 
 ### Staging Links
+
 <!-- start insert-links --><!-- end insert-links -->
 
 ## Self-Review Checklist
@@ -14,3 +15,4 @@ JIRA - <https://jira.mongodb.org/browse/DOCSP-NNNNN>
 - [ ] Did you run a grammar-check?
 - [ ] Are all the links working?
 - [ ] Are the [facets and meta keywords](https://wiki.corp.mongodb.com/display/DE/Docs+Taxonomy) accurate?
+- [ ] Are the page titles greater than 20 characters long and [SEO relevant](https://docs.google.com/spreadsheets/d/1Wkt0-5z04KmcMNscN5bjUKnzwWAtMq9VESp-Lz6r2o8/edit?usp=sharing)?

source/fundamentals/atlas-search.txt

@@ -73,6 +73,8 @@ categorizes data in a searchable format.
 To learn how to create an Atlas Search Index see the
 :atlas:`Create an Atlas Search Index </atlas-search/create-index>` Atlas guide.
 
+.. _csharp-atlas-search-operators:
+
 Atlas Search Operators and Collectors
 -------------------------------------
 

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,59 @@ 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``: This option applies only if you set the ``Representation``
+  property to ``BsonType.Document`` and is ignored otherwise. 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 +803,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/includes/mongodb-compatibility-table-csharp.rst

@@ -4,6 +4,7 @@
    :class: compatibility-large
 
    * - {+driver-short+} Version
+     - MongoDB 8.1
      - MongoDB 8.0
      - MongoDB 7.0
      - MongoDB 6.0
@@ -25,6 +26,7 @@
      - ✓
      - ✓
      - ✓
+     - ✓
      -
      -
      -
@@ -40,11 +42,13 @@
      - ✓
      - ✓
      - ✓
+     - ✓
      -
      -
      -
      -
    * - 2.20 to 2.28
+     - ⊛
      - ⊛
      - ✓
      - ✓
@@ -57,7 +61,9 @@
      -
      -
      -
+
    * - 2.16 to 2.19
+     - ⊛
      - ⊛
      - ⊛
      - ✓
@@ -70,10 +76,12 @@
      -
      -
      -
+
    * - 2.15
      - ⊛
      - ⊛
      - ⊛
+     - ⊛
      - ✓
      - ✓
      - ✓
@@ -83,7 +91,9 @@
      -
      -
      -
+
    * - 2.14
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -96,7 +106,9 @@
      -
      -
      -
+
    * - 2.13
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -109,7 +121,9 @@
      - ✓
      - ✓
      - ✓
+
    * - 2.12
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -122,7 +136,9 @@
      - ✓
      - ✓
      - ✓
+
    * - 2.11
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -135,7 +151,9 @@
      - ✓
      - ✓
      - ✓
+
    * - 2.10
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -148,7 +166,9 @@
      - ✓
      - ✓
      - ✓
+
    * - 2.9
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -161,7 +181,9 @@
      - ✓
      - ✓
      - ✓
+
    * - 2.8
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -175,6 +197,7 @@
      - ✓
      - ✓
    * - 2.7
+     - ✗ [#8.1-note]_
      - ⊛
      - ⊛
      - ⊛
@@ -187,20 +210,9 @@
      - ✓
      - ✓
      - ✓
-   * - 2.6
-     -
-     -
-     -
-     -
-     -
-     -
-     -
-     - ✓
-     - ✓
-     - ✓
-     - ✓
-     - ✓
-   * - 2.5
+
+   * - 2.5 to 2.6
+     - ✗ [#8.1-note]_
      -
      -
      -
@@ -213,7 +225,9 @@
      - ✓
      - ✓
      - ✓
+
    * - 2.4
+     - ✗ [#8.1-note]_
      -
      -
      -
@@ -226,20 +240,9 @@
      - ✓
      - ✓
      - ✓
-   * - 2.3
-     -
-     -
-     -
-     -
-     -
-     -
-     -
-     -
-     -
-     - ✓
-     - ✓
-     - ✓
-   * - 2.2
+
+   * - 2.2 to 2.3
+     - ✗ [#8.1-note]_
      -
      -
      -
@@ -252,7 +255,9 @@
      - ✓
      - ✓
      - ✓
+
    * - 2.0
+     - ✗ [#8.1-note]_
      -
      -
      -
@@ -266,4 +271,6 @@
      - ✓
      - ✓
 
+.. [#v3-note] These driver versions are not compatible with MongoDB 8.1 or later because of an authentication issue. To learn more, see :ref:`csharp-server-8.1-incompatibility`.
+
 The driver doesn't support older versions of MongoDB.

source/upgrade.txt

@@ -28,7 +28,9 @@ Overview
 --------
 
 Use the guides on this page to identify the potentially *breaking changes* that each
-version of the {+driver-short+} introduces. 
+version of the {+driver-short+} introduces. This page also provides information about
+breaking compatibility changes between the driver and MongoDB.
+
 A breaking change is a modification of a convention or a behavior starting in
 a specific version of the driver. This type of change may prevent your application from
 working properly if you don't address it.
@@ -45,4 +47,29 @@ Upgrade Guides
 --------------
 
 - :ref:`csharp-upgrade-v2`
-- :ref:`csharp-upgrade-v3`
+- :ref:`csharp-upgrade-v3`
+
+.. _csharp-server-release-changes:
+
+Server Release Compatibility Changes
+------------------------------------
+
+A server release compatibility change is a modification
+to the {+driver-long+} that discontinues support for a set of
+{+mdb-server+} versions.
+
+The driver discontinues support for a {+mdb-server+} version after it reaches
+end-of-life (EOL).
+
+To learn more about the MongoDB support for EOL products,
+see the `Legacy Support Policy <https://www.mongodb.com/support-policy/legacy>`__.
+
+.. _csharp-server-8.1-incompatibility:
+
+Server Version 8.1 Support Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You cannot use v2.14.1 or earlier versions of the {+driver-short+} to connect to a
+deployment running {+mdb-server+} v8.1. Starting in {+mdb-server+} v8.1,
+the ``buildinfo`` command requires authentication, causing an
+incompatibility with these driver versions.