whats-new.txt

.. _csharp-whats-new:

==========
What's New
==========

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: update, new feature, deprecation, upgrade, driver v2.25, driver v2.26, driver v2.27, driver v2.28, driver v3.0
   :description: Discover the latest features and updates in the C# Driver, including new conventions, serializers, and support for various MongoDB functionalities.

Learn what's new in:

* :ref:`Version 3.3 <csharp-version-3.3>`
* :ref:`Version 3.2 <csharp-version-3.2>`
* :ref:`Version 3.1 <csharp-version-3.1>`
* :ref:`Version 3.0 <csharp-version-3.0>`
* :ref:`Version 2.30 <csharp-version-2.30>`
* :ref:`Version 2.29 <csharp-version-2.29>`
* :ref:`Version 2.28 <csharp-version-2.28>`
* :ref:`Version 2.27 <csharp-version-2.27>`
* :ref:`Version 2.26 <csharp-version-2.26>`
* :ref:`Version 2.25 <csharp-version-2.25>`

.. _upcoming-breaking-changes:

Upcoming Breaking Changes
-------------------------

In accordance with the `MongoDB Software Lifecycle Schedules
<https://www.mongodb.com/legal/support-policy/lifecycles>`__, an upcoming minor
version of {+driver-short+} will raise the minimum {+mdb-server+} version from
4.0 to 4.2. {+driver-short+} will no longer support {+mdb-server+} 4.0.

.. _csharp-version-3.3:

What's New in 3.3
-----------------

The 3.3 driver release includes the following new features:

- Adds a new ``NamespaceType`` field that indicates the type of the created object for
  ``create`` events in the ``ChangeStreamDocument`` class. To learn more
  about change streams, see the :ref:`csharp-change-streams` guide.

- Adds the following In-Use Encryption features:

  - Support for the :manual:`$lookup </reference/operator/aggregation/lookup/>`
    aggregation stage

  - A ``ClientEncryptionOptions`` property that configures the data-encryption
    key cache lifetime

  To learn more about In-Use Encryption, see the :ref:`In-Use Encryption <csharp-fle>` guide.

- Adds the following LINQ features:

  - Support for the ``SkipWhile()`` and ``TakeWhile()`` LINQ
    aggregation methods. To learn more, see the
    :ref:`csharp-linq-skipwhile` and :ref:`csharp-linq-takewhile`
    sections of the LINQ guide.

  - Support for the ``$sigmoid`` expression in LINQ queries.

  - Support for using LINQ syntax to access any dictionary key that is
    serialized as a string, regardless of its underlying data type.

- Adds support for the ``$rankFusion`` aggregation stage, which enables rank-based
  result scoring on combined results from multiple pipelines.

- Adds support for :manual:`$elemMatch </reference/operator/query/elemMatch/>`
  queries directly against values by providing an overload of the
  ``ElemMatch()`` method that takes only a filter parameter. To learn
  more, see the :ref:`csharp-builders-array-operators` section of the
  Builders guide.

- Adds support for using the ``OfType<T>()`` method and ``is`` operator to check
  the type of a scalar discriminator.

.. _csharp-version-3.2:

What's New in 3.2
-----------------

The 3.2 driver release includes the following new features:

- Adds a new ``ObjectSerializerAllowedTypesConvention`` convention that
  allows you to specify which types are allowed to be serialized and
  deserialized by the object serializer. To learn more about conventions,
  see the :ref:`csharp-conventions` guide.

- Adds a new constructor for the ``EnumRepresentationConvention`` class that
  allows you use the ``topLevelOnly`` parameter to specify whether the
  convention applies to only enum properties or to all properties that include
  collections of enums.

  You can instantiate the ``EnumRepresentationConvention`` class by using the new
  constructor as shown in the following example:

  .. code-block:: csharp

     EnumRepresentationConvention(BsonType representation, bool topLevelOnly);

- Optimizes client-side projections to retrieve only the required fields from
  the server, rather than retrieving all fields and then filtering them.

- Adds the following classes to support binary vector representations in Atlas
  Vector Search:

  - ``BinaryVectorFloat32``
  - ``BinaryVectorInt8``
  - ``BinaryVectorPackedBit``

  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
-----------------

The 3.1 driver release includes the following new features:

- Adds new default serializers for immutable collections in the
  `System.Collections.Immutable <https://learn.microsoft.com/en-us/dotnet/api/system.collections.immutable?view=net-8.0>`__
  namespace. The driver can now serialize ``ImmutableArray`` objects, and serialization
  for other immutable collections is more memory efficient.

- Adds support for the token field type and array field expressions with Atlas Search
  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.

- Adds support for the ``Exists``, ``IsMissing``, and ``IsNullOrMissing`` methods
  in MongoDB Query API filters.

- Adds support for Exact Nearest Neighbor (ENN) vector search. To learn more about ENN
  Vector Search, see :atlas:`Run Vector Search Queries </atlas-vector-search/vector-search-stage>`
  in the Atlas Search documentation.

- Adds support for the ``sort`` option to be passed to update commands. To learn more about
  using update commands with the {+driver-short+}, see :ref:`csharp-update-one` and
  :ref:`csharp-update-many`.

For more information about this release, see the :github:`v3.1 release notes
</mongodb/mongo-csharp-driver/releases/tag/v3.1.0>`.

.. _csharp-version-3.0:

What's New in 3.0
-----------------

.. warning:: Breaking Changes in v3.0

   The v3.0 driver contains breaking changes. See :ref:`<csharp-breaking-changes-v3>`
   for more information.

The 3.0 driver release includes the following new features:

- Adds the ``MongoClientSettings.TranslationOptions`` connection option, which specifies
  options for translating LINQ queries to the Query API. See :ref:`csharp-connection-options`
  for more information.

- Adds support for the ``Half`` type, which represents a half-precision floating-point number.
  This type is available in .NET 5 and later.
  To learn more about the ``Half`` type, see the
  `Half Struct <https://learn.microsoft.com/en-us/dotnet/api/system.half?view=net-8.0>`__
  API reference page on MSDN.

- The ``IMongoClient`` interface inherits the ``IDisposable`` interface. As a result, the
  ``MongoClient`` class and other classes that implement the ``IMongoClient`` interface
  contain a ``Dispose()`` method, which disposes of the client. This method does not
  dispose the underlying cluster and connections to the MongoDB server. To
  dispose of the cluster and connections, call the
  ``ClusterRegistry.UnregisterAndDisposeCluster()`` method. 
  The implementation of the ``IDisposable`` interface is experimental.
  
  To learn more about the ``IDisposable`` interface and use of the
  ``Dispose()`` method, see
  `Dispose Pattern <https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/dispose-pattern>`__
  on MSDN.

- Adds support for the ``DateOnly`` type, which represents a date value with no
  time component. This type is available in .NET 6 and later. To learn more about the
  ``DateOnly`` type, see the
  `DateOnly Struct. <https://learn.microsoft.com/en-us/dotnet/api/system.dateonly?view=net-6.0>`__
  API reference page on MSDN.

- Adds support for the ``TimeOnly`` type, which represents a time value with no
  date component. This type is available in .NET 6 and later. To learn more about the
  ``TimeOnly`` type, see the
  `TimeOnly Struct. <https://learn.microsoft.com/en-us/dotnet/api/system.timeonly?view=net-6.0>`__
  API reference page on MSDN.

- Adds support for implicit client-side projection when using the ``Find()`` method,
  the ``Select()`` method, or the ``Project()`` aggregation stage with the LINQ3 provider.
  In previous versions of the driver, you could perform client-side
  projection with the LINQ3 provider only after calling the ``ToEnumerable()`` or
  ``AsEnumerable()`` method.
  
  To learn how to enable and use client-side projection for a driver method, select the
  corresponding tab:

  .. tabs::

    .. tab:: Find() Method
       :tabid: find-method

       .. code-block:: csharp

          // Enable client-side projection
          var findOptions = new FindOptions();
          findOptions.TranslationOptions = new ExpressionTranslationOptions
          {
              EnableClientSideProjections = true
          };
         
          var find = collection
              .Find(doc => doc.Id == 1, findOptions);
              .Project(doc => new { R = MyFunction(doc.Name) });
  
    .. tab:: Select() Method
       :tabid: select-method

       .. code-block:: csharp

          // Enable client-side projection
          var aggregateOptions = new AggregateOptions();
          aggregateOptions.TranslationOptions = new ExpressionTranslationOptions
          {
              EnableClientSideProjections = true
          };
         
          var queryable = collection
              .AsQueryable(aggregateOptions)
              .Where(doc => doc.Id == 1)
              .Select(doc => new { R = MyFunction(doc.Name) });

    .. tab:: Project() Method
       :tabid: project-method

       .. code-block:: csharp

          // Enable client-side projection
          var aggregateOptions = new AggregateOptions();
          aggregateOptions.TranslationOptions = new ExpressionTranslationOptions
          {
              EnableClientSideProjections = true
          };

          var aggregate = collection
              .Aggregate(aggregateOptions)
              .Project(doc => new { R = MyFunction(doc.Name) });
  
  .. tip:: MongoClientSettings

     To enable client-side projection for all queries on a client, set the
     ``TranslationOptions`` property of your ``MongoClientSettings`` object, as shown
     in the following example:
     
     .. code-block:: csharp

        clientSettings.TranslationOptions = new ExpressionTranslationOptions
        {
            EnableClientSideProjections = true
        }; 
  
  To learn more about using the aggregation pipeline with the {+driver-short+}, see
  :ref:`csharp-aggregation`.

- Adds a ``MongoClient`` API for bulk write operations. To learn more about bulk write
  operations, see :ref:`csharp-bulk-write`.

For more information about this release, see the :github:`v3.0 release notes
</mongodb/mongo-csharp-driver/releases/tag/v3.0.0>`.

.. _csharp-version-2.30:

What's New in 2.30
------------------

The 2.30 driver doesn't introduce new features or bug fixes. Its purpose is to ease
migration to v3.x of the {+driver-short+} by marking the public APIs that were removed in
v3.0 as obsolete.

.. _csharp-version-2.29:

What's New in 2.29
------------------

The 2.29 driver release adds support for {+mdb-server+} version 8.0 and
includes the following new features:

- Adds support for v2 of the Queryable Encryption range protocol.

- Adds support for range indexes for Queryable Encryption. For more information about
  Queryable Encryption, see :manual:`Queryable Encryption </core/queryable-encryption>`
  in the {+mdb-server+} manual.

For more information about this release, see the :github:`v2.29 release notes
</mongodb/mongo-csharp-driver/releases/tag/v2.29.0>`.

.. _csharp-version-2.28:

What's New in 2.28
------------------

.. warning:: Potential Breaking Change in v2.28

   - All {+driver-short+} components are strongly named. If your application
     has dependencies that reference multiple {+driver-short+}
     versions, you must create binding redirects to manage those dependencies.
     For more information, see :ref:`csharp-breaking-changes-2.28.0`.

The 2.28 driver release includes the following new features:

- Adds support for additional numeric conversions involving ``Nullable<T>``.
- Adds support for the ``delegated`` option when using KMIP for :ref:`CSFLE or
  Queryable Encryption <csharp-fle>`.

For more information about this release, see the :github:`v2.28 release notes
</mongodb/mongo-csharp-driver/releases/tag/v2.28.0>`.

.. _csharp-version-2.27:

What's New in 2.27
------------------

The 2.27 driver release includes the following new features:

- Adds support for the ``$sample`` aggregation operator.

- Implements the ``Equals()`` method for serializers in LINQ3.

- Ensures that read and write concerns are not applied to Atlas Search Index
  Helper commands to avoid errors.

- Disallows the use of the comma character in ``authMechanismProperties``
  connection string values when using the ``MONGODB-OIDC`` authentication
  mechanism. 

- Fixes a translation bug that caused an error during serialization involving
  numbers of different sizes.

- Adds support for Linux distributions that use the ``libdl.so.2`` library.

For more information about this release, see the :github:`v2.27 release notes
</mongodb/mongo-csharp-driver/releases/tag/v2.27.0>`.

.. _csharp-version-2.26:

What's New in 2.26
------------------

The 2.26 driver release includes the following new features:

- Added support for using the ``SelectMany()`` aggregation method within
  ``Select()`` and ``Project()`` aggregation stages.

- Added support for ``Dictionary.ContainsValue()`` calls in LINQ queries.

- Added support for string concatenation of mixed types.

- Enabled use of native ``crypto`` in ``libmongocrypt`` bindings.

- Added support for serialization of ``Memory`` and ``ReadOnlyMemory``
  structs. To learn more about implementing these types, see the
  :ref:`csharp-array-serialization` section of the Serialization guide.

- Added support for the GCP Identity Provider when using the
  ``MONGODB-OIDC`` authentication mechanism. To learn more, see
  :ref:`csharp-mongodb-oidc-gcp-imds` in the Enterprise Authentication
  Mechanisms guide.

- Implemented signing of NuGet packages.

- Implemented read and write retries to other ``mongos`` instances when
  possible.

.. _csharp-version-2.25:
.. _version-2.25:

What's New in 2.25
------------------

The 2.25 driver release includes the following new features:

- Added support for the ``MONGODB-OIDC`` authentication mechanism and automatic
  token acquisition for Azure Identity Provider.

- Added the class name to the error message reported when
  ``BsonClassMapSerializer`` cannot locate a matching creator.

- Added a ``LoggedStages`` field to surface the MQL executed after performing
  a LINQ query.

- Added support for overriding the ``"mongodb"`` service name with a custom one
  by using the ``srvServiceName`` connection option. To learn more, see
  the :ref:`csharp-connection-options` guide.

- Improved behavior of bulk write operations to prevent enumerating the requests
  parameter more than once.