Docs Menu
Docs Home
/
Languages
/
C#/.NET
/
C#/.NET
/
Upgrade Driver Versions

Upgrade to Version 2.x

On this page

  • Overview
  • How to Upgrade
  • Breaking Changes by Version
  • Version 2.28.0 Breaking Change
  • Version 2.21.0 Breaking Changes
  • Version 2.19.0 Breaking Changes
  • Version 2.14.0 Breaking Changes

Overview

This page describes the changes you might need to make to your application when you upgrade the .NET/C# Driver to version 2.x.

How to Upgrade

Each section of this page lists the potential breaking changes introduced by a driver version. To upgrade the .NET/C# Driver to version 2.x, follow these steps:

  1. Review the Compatibility page to ensure the new driver version is compatible with the MongoDB Server versions your application connects to and the .NET or .NET framework version your application runs on.

  2. Address any breaking changes between the driver version your application uses and your target upgrade version in the Breaking Changes by Version section.

    Example

    If you are upgrading the driver from v2.14 to v2.21, address all breaking changes from the version after v2.14 (v2.19), including any changes for v2.21.

Breaking Changes by Version

The following sections describe the potential breaking changes introduced by each driver version. If a driver version is not included in this section, it doesn't introduce any breaking changes.

Version 2.28.0 Breaking Change

  • The driver uses strong naming for all driver components. If your application has dependencies that reference multiple .NET/C# Driver versions, you must create binding redirects, as shown in the following example:

    <configuration>
        <runtime>
            <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
                <dependentAssembly>
                    <assemblyIdentity name="MongoDB.Driver"
                                      publicKeyToken="94992a530f44e321"
                                      culture="neutral" />
                    <bindingRedirect oldVersion="2.28.0.0"
                                     newVersion="<version number to use>" />
                </dependentAssembly>
                <dependentAssembly>
                    <assemblyIdentity name="MongoDB.Bson"
                                      publicKeyToken="94992a530f44e321"
                                      culture="neutral" />
                    <bindingRedirect oldVersion="2.28.0.0"
                                     newVersion="<version number to use>" />
                </dependentAssembly>
                <dependentAssembly>
                    <assemblyIdentity name="MongoDB.Driver.Core"
                                      publicKeyToken="94992a530f44e321"
                                      culture="neutral" />
                    <bindingRedirect oldVersion="2.28.0.0"
                                     newVersion="<version number to use>" />
                </dependentAssembly>
            </assemblyBinding>
        </runtime>
    </configuration>

Version 2.21.0 Breaking Changes

  • The driver changes the signature of Render methods in the Atlas Search builders. In previous driver versions, these methods had the following signature:

    Render(IBsonSerializer<TDocument> documentSerializer, IBsonSerializerRegistry serializerRegistry);

    In version 2.21.0 and later, the Render methods have the following signature:

    Render(SearchDefinitionRenderContext<TDocument> renderContext);

Version 2.19.0 Breaking Changes

  • The ObjectSerializer only allows deserialization of types that are considered safe. If not specified otherwise, the ObjectSerializer uses the types returned by ObjectSerializer.DefaultAllowedTypes.

    To learn more about the ObjectSerializer, visit the FAQ. For more information on DefaultAllowedTypes, visit the API Documentation.

  • The default LinqProvider has been changed to LINQ3. The LinqProvider can be configured for LINQ2 in MongoClientSettings as shown in the following code example:

    var connectionString = "<connection string>";
    var clientSettings = MongoClientSettings
       .FromConnectionString(connectionString);
    clientSettings.LinqProvider = LinqProvider.V2;
    var client = new MongoClient(clientSettings);

Version 2.14.0 Breaking Changes

  • The driver drops support for MongoDB Server v3.4 and earlier. You must upgrade your MongoDB Server to v3.6 or later.

    To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual. To learn more about compatibility between the .NET/C# Driver and MongoDB Server, see the Compatibility page.

  • The driver drops support for .NET framework v4.5.2 and earlier. Your application must use .NET framework v4.7.2 or later, .NET Core 2.x or later, or .NET 5 or later.

    To learn more about compatibility between the .NET/C# Driver and .NET, see the Compatibility page.

  • The driver drops support for .NET Standard v1.5. Your application must use .NET Standard v2.0 or later.

Back

Upgrade Driver Versions

Next

Upgrade to Version 3.0