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)? 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/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..3e907f63 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,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. `__ +.. _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``: 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>`__ \ No newline at end of file +- `InsertOne() + <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertMany.html>`__ diff --git a/source/includes/mongodb-compatibility-table-csharp.rst b/source/includes/mongodb-compatibility-table-csharp.rst index c180ad3c..31c663cb 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 + - ✗ [#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. 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. diff --git a/source/whats-new.txt b/source/whats-new.txt index 4ac55477..bb5ff603 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``. + 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. + .. _csharp-version-3.1: What's New in 3.1 @@ -138,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.