From 64727cdc5f42e81c3ac13cb5679ee6d792c0ae1e Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 4 Apr 2025 14:17:25 -0400 Subject: [PATCH 1/9] DOCSP-45943: dateonly serialization --- source/fundamentals/serialization.txt | 19 ++++++-- source/fundamentals/serialization/poco.txt | 56 ++++++++++++++++++++-- source/whats-new.txt | 7 +++ 3 files changed, 75 insertions(+), 7 deletions(-) diff --git a/source/fundamentals/serialization.txt b/source/fundamentals/serialization.txt index a3f8de15..ab0af251 100644 --- a/source/fundamentals/serialization.txt +++ b/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 diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index a7fab8a5..c7bb7732 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/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,57 @@ 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. `__ +.. _csharp-poco-dateonly-attr: + +Custom DateOnly Serialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To customize how the {+driver-short+} serializes `DateOnly +`__ +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 to one of the following + ``DateOnlyDocumentFormat`` enum values: + + - ``DateTimeTicks`` (default): Document contains ``DateTime`` + (``BsonType.DateTime``) and ``Ticks`` (``BsonType.Int64``) fields + + - ``DateTimeTicks``: 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 +801,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>`__ \ No newline at end of file +- `InsertOne() + <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertMany.html>`__ diff --git a/source/whats-new.txt b/source/whats-new.txt index 4ac55477..3b865a92 100644 --- a/source/whats-new.txt +++ b/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`` to + allow you to customize the way that the driver stores ``DateOnly`` + values. This release also adds the ``[BsonDateOnlyOptions()]`` + attribute to customize serialization behavior at the property level. + To learn more, see the :ref:`csharp-poco-dateonly-attr` section of the + Serialization guide. + .. _csharp-version-3.1: What's New in 3.1 From d837fdaa64e6c08672f0429495a88b45adf4f95b Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 7 Apr 2025 09:58:17 -0400 Subject: [PATCH 2/9] MW PR fixes 1 --- source/fundamentals/serialization/poco.txt | 2 +- source/whats-new.txt | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index c7bb7732..27426213 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -627,7 +627,7 @@ the following settings: - ``DateTimeTicks`` (default): Document contains ``DateTime`` (``BsonType.DateTime``) and ``Ticks`` (``BsonType.Int64``) fields - - ``DateTimeTicks``: Document contains ``Year``, ``Month``, and + - ``YearMonthDay``: Document contains ``Year``, ``Month``, and ``Day`` fields, which have ``BsonType.Int32`` values In the following code example, the ``PatientRecord`` class contains a diff --git a/source/whats-new.txt b/source/whats-new.txt index 3b865a92..24b88d4e 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -122,12 +122,12 @@ 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`` to - allow you to customize the way that the driver stores ``DateOnly`` - values. This release also adds the ``[BsonDateOnlyOptions()]`` - attribute to customize serialization behavior at the property level. - To learn more, see the :ref:`csharp-poco-dateonly-attr` section of the - Serialization guide. +- Adds the ``DocumentFormat`` property to the ``DateOnlySerializer``. + This property allows you to customize the way that the driver stores + ``DateOnly`` values. 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: From 043d985c831d88735f5fdc27c67e81e90a4ff25c Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 8 Apr 2025 12:46:17 -0400 Subject: [PATCH 3/9] FP tech review --- source/fundamentals/serialization/poco.txt | 5 +++-- source/whats-new.txt | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index 27426213..d9bef914 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -621,8 +621,9 @@ the following settings: - ``Representation``: Set to a ``BsonType`` instance that specifies how the ``DateOnly`` value is stored in MongoDB. -- ``DocumentFormat``: Set to one of the following - ``DateOnlyDocumentFormat`` enum values: +- ``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 diff --git a/source/whats-new.txt b/source/whats-new.txt index 24b88d4e..529348e4 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -124,7 +124,7 @@ The 3.2 driver release includes the following new features: - Adds the ``DocumentFormat`` property to the ``DateOnlySerializer``. This property allows you to customize the way that the driver stores - ``DateOnly`` values. This release also adds the + ``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. From d8c425813dfc8342c9e902b9c4e91d986e6676ab Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 7 Apr 2025 10:23:20 -0500 Subject: [PATCH 4/9] DOCSP-48936 - Add title length check (#571) --- .github/pull_request_template.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index c1033fdd..14cb2c0d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -5,6 +5,7 @@ JIRA - ### Staging Links + ## Self-Review Checklist @@ -14,3 +15,4 @@ JIRA - - [ ] 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)? From 1b838ddcc5714bb9bb16696376743ea321084451 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 8 Apr 2025 11:25:08 -0400 Subject: [PATCH 5/9] DOCSP-48921: Server 8.1 compat (#555) * DOCSP-48921: Server 8.1 compat * fix --- .../mongodb-compatibility-table-csharp.rst | 57 ++++++++++--------- 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/source/includes/mongodb-compatibility-table-csharp.rst b/source/includes/mongodb-compatibility-table-csharp.rst index c180ad3c..0fa39dd2 100644 --- a/source/includes/mongodb-compatibility-table-csharp.rst +++ b/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 + - - ⊛ - ⊛ - ⊛ @@ -96,7 +106,9 @@ - - - + * - 2.13 + - - ⊛ - ⊛ - ⊛ @@ -109,7 +121,9 @@ - ✓ - ✓ - ✓ + * - 2.12 + - - ⊛ - ⊛ - ⊛ @@ -122,7 +136,9 @@ - ✓ - ✓ - ✓ + * - 2.11 + - - ⊛ - ⊛ - ⊛ @@ -135,7 +151,9 @@ - ✓ - ✓ - ✓ + * - 2.10 + - - ⊛ - ⊛ - ⊛ @@ -148,7 +166,9 @@ - ✓ - ✓ - ✓ + * - 2.9 + - - ⊛ - ⊛ - ⊛ @@ -161,7 +181,9 @@ - ✓ - ✓ - ✓ + * - 2.8 + - - ⊛ - ⊛ - ⊛ @@ -175,6 +197,7 @@ - ✓ - ✓ * - 2.7 + - - ⊛ - ⊛ - ⊛ @@ -187,20 +210,9 @@ - ✓ - ✓ - ✓ - * - 2.6 - - - - - - - - + + * - 2.5 to 2.6 - - - - - - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - * - 2.5 - - - @@ -213,6 +225,7 @@ - ✓ - ✓ - ✓ + * - 2.4 - - @@ -222,24 +235,14 @@ - - - + - - ✓ - ✓ - ✓ - ✓ - * - 2.3 - - - - - - - - - - - - - - - - + + * - 2.2 to 2.3 - - - ✓ - - ✓ - - ✓ - * - 2.2 - - - @@ -252,6 +255,7 @@ - ✓ - ✓ - ✓ + * - 2.0 - - @@ -263,6 +267,7 @@ - - - + - - ✓ - ✓ From 8760037298f7000987909e7adcc5f520132229cf Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 9 Apr 2025 09:20:31 -0400 Subject: [PATCH 6/9] Update upgrade.txt --- source/upgrade.txt | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index fd55892c..2552a118 100644 --- a/source/upgrade.txt +++ b/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` \ No newline at end of file +- :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 `__. + +.. _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. From ce67ea38f0e62a8bc7d0c888642012e2d506f55c Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 9 Apr 2025 09:23:55 -0400 Subject: [PATCH 7/9] add xs and note --- .../mongodb-compatibility-table-csharp.rst | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/source/includes/mongodb-compatibility-table-csharp.rst b/source/includes/mongodb-compatibility-table-csharp.rst index 0fa39dd2..31c663cb 100644 --- a/source/includes/mongodb-compatibility-table-csharp.rst +++ b/source/includes/mongodb-compatibility-table-csharp.rst @@ -93,7 +93,7 @@ - * - 2.14 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -108,7 +108,7 @@ - * - 2.13 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -123,7 +123,7 @@ - ✓ * - 2.12 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -138,7 +138,7 @@ - ✓ * - 2.11 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -153,7 +153,7 @@ - ✓ * - 2.10 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -168,7 +168,7 @@ - ✓ * - 2.9 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -183,7 +183,7 @@ - ✓ * - 2.8 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -197,7 +197,7 @@ - ✓ - ✓ * - 2.7 - - + - ✗ [#8.1-note]_ - ⊛ - ⊛ - ⊛ @@ -212,7 +212,7 @@ - ✓ * - 2.5 to 2.6 - - + - ✗ [#8.1-note]_ - - - @@ -227,7 +227,7 @@ - ✓ * - 2.4 - - + - ✗ [#8.1-note]_ - - - @@ -242,7 +242,7 @@ - ✓ * - 2.2 to 2.3 - - + - ✗ [#8.1-note]_ - - - @@ -257,7 +257,7 @@ - ✓ * - 2.0 - - + - ✗ [#8.1-note]_ - - - @@ -271,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. From 294b36e700c04c70c75d2208842b06d149a6c817 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 9 Apr 2025 10:54:16 -0400 Subject: [PATCH 8/9] DOCSP-45803: atlas search queries null & guid values (#582) --- source/fundamentals/atlas-search.txt | 2 ++ source/whats-new.txt | 10 ++++++++++ 2 files changed, 12 insertions(+) diff --git a/source/fundamentals/atlas-search.txt b/source/fundamentals/atlas-search.txt index 3a845f2f..54c2df3c 100644 --- a/source/fundamentals/atlas-search.txt +++ b/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 guide. +.. _csharp-atlas-search-operators: + Atlas Search Operators and Collectors ------------------------------------- diff --git a/source/whats-new.txt b/source/whats-new.txt index 529348e4..9187195f 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -145,6 +145,16 @@ The 3.1 driver release includes the following new features: builders for the ``equals`` operator. To learn more about using Atlas Search with the {+driver-short+}, see :ref:`csharp-atlas-search`. +- Adds support for the following Atlas Search queries: + + - Using the ``Equals()`` operator method on ``null`` and ``Guid`` values + + - Using the ``In()`` operator method on ``Guid`` values + + To learn more about these methods, see the + :ref:`csharp-atlas-search-operators` section of the Atlas Search + guide. + - Adds support for sequential pagination in Atlas Search. - Adds support for valid SRV hostnames with fewer than 3 parts. From 9a85c7d6468f3fd1ec406d5796a143b2e7bf495a Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 9 Apr 2025 13:11:49 -0400 Subject: [PATCH 9/9] FP tech review2 --- source/fundamentals/serialization/poco.txt | 7 ++++--- source/whats-new.txt | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index d9bef914..3e907f63 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -621,9 +621,10 @@ 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: +- ``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 diff --git a/source/whats-new.txt b/source/whats-new.txt index 9187195f..bb5ff603 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -123,8 +123,8 @@ The 3.2 driver release includes the following new features: :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 + This property allows you to customize the way that the driver serializes + ``DateOnly`` values. 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.