Upgrade Driver Versions

On this page

Overview

Breaking Changes
Server Release Compatibility Changes

Overview

In this section, you can identify essential changes you must make to your application when you upgrade your driver to a new version.

Before you upgrade, perform the following actions:

Ensure the new version is compatible with the MongoDB Server versions your application connects to and the .NET framework version your application runs on. See the .NET/C# Driver Compatibility page for this information.
Address any breaking changes between the current version of the driver your application is using and your planned upgrade version in the Breaking Changes section. To learn more about the MongoDB Server release compatibility changes, see the Server Release Compatibility Changes section.

Tip

To minimize the number of changes your application may require when upgrading driver versions in the future, use the Stable API.

Breaking Changes

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 not addressed before upgrading the driver.

The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions. For example, if you are upgrading the driver from v2.0 to v2.20, address all breaking changes from the version after v2.0 including any listed under v2.20.

Version 2.28.0 Potential Breaking Change

All .NET/C# Driver components are strongly named. If you are using driver version 2.28 or later, and 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 function signature of Render methods in the Atlas Search builders changed. The following code snippet shows the function signature prior to the change and after the change:

// Render function signature prior to v2.21.0
Render(IBsonSerializer<TDocument> documentSerializer, IBsonSerializerRegistry serializerRegistry);
// Render function signature in v2.21.0 and later
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

This MongoDB .NET/C# Driver version removed support for .NET framework v4.5.2 or earlier; the minimum .NET framework supported is v4.7.2.
This version of the MongoDB .NET/C# Driver does not support .NET Standard v1.5; the minimum .NET Standard supported is v2.0.

Version 2.13.0 Breaking Changes

The slave0k connection string option was removed; the readPreference option is now used instead.

Server Release Compatibility Changes

A server release compatibility change is a modification to the MongoDB .NET/C# Driver that discontinues support for a set of MongoDB Server versions.

The driver discontinues support for a MongoDB Server version after it reaches end-of-life (EOL).

To learn more about the MongoDB support for EOL products see the Legacy Support Policy.

To learn more about the compatibility between .NET/C# driver versions and MongoDB Server versions, visit the Compatibility page.

Version 2.14 Release Support Changes

The v2.14 driver drops support for MongoDB Server v3.4 and earlier. To use any driver from v2.14 and later, your MongoDB Server must be v3.6 or later.

To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.

Back

Compatibility