Upgrade to Version 3.x

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Upgrade to Version 3.x

Overview

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

How to Upgrade

This page lists the potential breaking changes introduced by a 3.x .NET/C# Driver version. To upgrade the .NET/C# Driver to version 3.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. If you're using a 2.x version of the .NET/C# Driver, upgrade to v2.30. To do so, follow the [v2.x upgrade guide.](https://www.mongodb.com/docs/drivers/csharp/current/reference/upgrade/v2.md#std-label-csharp-upgrade-v2

  3. Address the breaking changes described in the [Version 3.0 Breaking Changes](https://www.mongodb.com/docs/drivers/csharp/current/reference/upgrade/v3.md#std-label-csharp-breaking-changes-v3 section.

Example:

If you are upgrading the driver from v2.14 to v3.0, first use the v2.x upgrade guide to upgrade your driver to v2.30. Then, address all breaking changes for v3.0.

Version 3.10 Breaking Changes

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

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

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

Version 3.5 Breaking Changes

  • The driver drops support for MongoDB Server 4.0 and earlier. You must upgrade your MongoDB Server to v4.2 or later.

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

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

Version 3.0 Breaking Changes

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

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

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

  • The driver drops support for .NET Core 2.x and .NET Framework 4.6. You must upgrade to .NET Core 3.x or later, or .NET Framework 4.7.2 or later.

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

  • The driver removes the [mongocsharpdriver](https://www.nuget.org/packages/mongocsharpdriver/#readme-body-tab NuGet package, which implements the legacy v1.x API in driver versions 2.x. If you're using the v1.x API, you must migrate to the new API.

  • The classes, methods, and properties in the MongoDB.Driver.Core namespace that were deprecated in v2.30 are marked internal. If the driver provides a replacement for a deprecated class, method, or property, the compiler messages in v2.30 will display it.

  • The methods, properties, and constructors in the MongoDB.Bson namespace that were deprecated in previous versions of the driver have been removed. If the driver provides a replacement for a deprecated method, property, or constructor, the compiler messages in v2.30 will display it.

  • The driver drops support for the MONGODB-CR authentication mechanism. To learn more about configuring authentication in the .NET/C# Driver, see [Authentication Mechanisms.](https://www.mongodb.com/docs/drivers/csharp/current/security/authentication.md#std-label-csharp-authentication-mechanisms

  • The driver replaces the IMongoQueryable interface with the IQueryable interface, following the pattern used by most other LINQ providers. If your application contains references to IMongoQueryable, replace them with IQueryable.

  • The driver removes the ClusterBuilder.ConfigureSdamLogging() method. To configure logging in your application, see the [Logging](https://www.mongodb.com/docs/drivers/csharp/current/logging-and-monitoring/logging.md#std-label-csharp-logging guide.

  • The LINQ2 provider has been removed from this version of the driver. You must use LINQ3 for all LINQ queries.

Queries that use client-side projections will throw an ExpressionNotSupportedException error by default. To enable client-side projections, set the EnableClientSideProjections property of a TranslationOptions object to true. You can pass this TranslationOptions object to an AggregateOptions or FindOptions object to enable client-side projections for a single query, or to a MongoClientSettings object to enable client-side projections for all queries in an application.

  • Previous versions of the .NET/C# Driver supported two GUID representation modes. In version 3.0, GuidRepresentationMode.V3 is the only supported mode. This change has the following effects on the driver:

  • The BsonBinaryData(Guid) constructor has been removed. To construct a BsonBinaryData object from a GUID, use the BsonBinaryData.Create(Guid, GuidRepresentation) constructor. To view an example of creating a legacy GUID, see the [Construct Legacy GUIDs](https://www.mongodb.com/docs/drivers/csharp/current/serialization/guids.md#std-label-csharp-guid-legacy-construct note in the GUID Serialization guide.

  • The BsonBinaryData.GuidRepresentation property has been removed.

  • You can call the BsonBinaryData.ToGuid() method only on BsonBinaryData objects of subtype 4. If the object has any other subtype, you must call the BsonBinaryData.ToGuid(GuidRepresentation) method and specify the subtype.

  • GUID conversion by using the BsonTypeMapper class has been removed. To convert GUID values to BSON, use the BsonBinaryData(<GUID>, GuidRepresentation.Standard) constructor.

The preceding changes affect your application only if you serialize and deserialize BSON documents directly. If you map your MongoDB documents only to [POCOs](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-poco, the GuidRepresentationMode doesn't affect your application.

To learn more about serializing GUIDs in the .NET/C# Driver, see the [GUIDs](https://www.mongodb.com/docs/drivers/csharp/current/serialization/guids.md#std-label-csharp-guids page.

  • Exception classes and their related types no longer contain the [Serializable] attribute, and therefore no longer support the Microsoft legacy serialization API. To learn how to use the .NET/C# Driver to serialize objects, see the [Serialization](https://www.mongodb.com/docs/drivers/csharp/current/serialization.md#std-label-csharp-serialization guide.

  • TLS 1.0 and 1.1 are no longer supported. You must use TLS 1.2 or higher. To learn more about configuring TLS/SSL in the .NET/C# Driver, see [Enable TLS on a Connection.](https://www.mongodb.com/docs/drivers/csharp/current/security/tls-ssl.md#std-label-csharp-tls

  • By default, the driver serializes Decimal128 and decimal values as BSON Decimal128 values. In previous versions of the driver, the driver serialized these values as BSON string values by default. To serialize a decimal or Decimal128 value as a string in v3.0, apply the [BsonRepresentation(BsonType.String)] attribute to the field.

To learn more about specifying BSON types during serialization, see the [Custom Serialization](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-custom-serialization section of the POCOs page.

  • By default, the driver serializes DateTimeOffset values as BSON documents. In previous versions of the driver, the driver serialized these values as BSON arrays by default. To serialize a DateTimeOffset value as an array in v3.0, apply the [BsonRepresentation(BsonType.Array)] attribute to the field.

  • The default JSON output mode is Relaxed Extended JSON, a string format based on the JSON standard that describes BSON documents. Relaxed Extended JSON emphasizes readability and interoperability at the expense of type preservation.

To use a different JSON output mode, create a new JsonWriterSettings object. Set the OutputMode property of this object to a value from the JsonOutputMode enum, then pass the object to the ToJson() method when you serialize your document. The following code example shows how to serialize a BSON document to Strict JSON:

```csharp // Configure JsonWriterSettings var jsonWriterSettings = new JsonWriterSettings { OutputMode = JsonOutputMode.Strict };

// Serialize the document to JSON using the configured settings var json = document.ToJson(jsonWriterSettings); ```

  • The MongoClient constructor accepts only one Credential object instead of an array.

  • To use Amazon Web Services (AWS) authentication, you must add the MongoDB.Driver.Authentication.AWS package to your project and register the authentication provider in your application's bootstrap code. To learn more about using AWS authentication with the .NET/C# Driver, see [AWS IAM Authentication.](https://www.mongodb.com/docs/drivers/csharp/current/security/authentication/aws-iam.md#std-label-csharp-mongodb-aws

  • To use In-Use Encryption, you must add the MongoDB.Driver.Encryption package to your project and register the encryption mechanism in your application's bootstrap code. To learn more about using In-Use Encryption with the .NET/C# Driver, see In-Use Encryption in the MongoDB Server manual.

  • If you try to serialize or deserialize a floating-point Infinity or NaN value to an integral representation, the driver throws an OverflowException. To learn more about floating-point Infinity and NaN values, see [Double.NaN,](https://learn.microsoft.com/en-us/dotnet/api/system.double.nan?view=net-8.0#system-double-nan [Double.PositiveInfinity,](https://learn.microsoft.com/en-us/dotnet/api/system.double.positiveinfinity?view=net-8.0#system-double-positiveinfinity and [Double.NegativeInfinity.](https://learn.microsoft.com/en-us/dotnet/api/system.double.negativeinfinity?view=net-8.0#system-double-negativeinfinity on MSDN.

  • The driver includes the following changes to the BsonValue class:

  • Removes the [Obsolete] attribute from the AsLocalTime and AsUniversalTime properties.

  • Adds the [AsNullableLocalTime](https://mongodb.github.io/mongo-csharp-driver/3.12.0/api/MongoDB.Bson/MongoDB.Bson.BsonValue.AsNullableLocalTime.html#MongoDB_Bson_BsonValue_AsNullableLocalTime and [AsNullableUniversalTime](https://mongodb.github.io/mongo-csharp-driver/3.12.0/api/MongoDB.Bson/MongoDB.Bson.BsonValue.AsNullableUniversalTime.html#MongoDB_Bson_BsonValue_AsNullableUniversalTime properties.

  • Removes the AsDateTime property. Use the [AsUniversalTime](https://mongodb.github.io/mongo-csharp-driver/3.12.0/api/MongoDB.Bson/MongoDB.Bson.BsonValue.AsUniversalTime.html#MongoDB_Bson_BsonValue_AsUniversalTime property instead.

  • Removes the AsNullableDateTime property. Use the [AsNullableUniversalTime](https://mongodb.github.io/mongo-csharp-driver/3.12.0/api/MongoDB.Bson/MongoDB.Bson.BsonValue.AsNullableUniversalTime.html#MongoDB_Bson_BsonValue_AsNullableUniversalTime property instead.

  • The driver removes individual cluster events from MongoClient.Cluster. To listen for cluster events, call the ClusterBuilder.Subscribe() method.

  • If any type in a collection uses a scalar discriminator, the driver throws an exception if you perform either of the following actions on the collection:

  • Call the Aggregate().OfType<T>() method, as in the following example:

    csharp collection.Aggregate().OfType<T>()

  • Call the Aggregate().Match(item => item is T) method, as in the following example:

    csharp collection.Aggregate().Match(item => item is T)

To use either of the preceding methods on a collection, you can apply a hierarchical discriminator to each class in the collection. See the [Polymorphic Objects](https://www.mongodb.com/docs/drivers/csharp/current/serialization/polymorphic-objects.md#std-label-csharp-discriminator-hierarchical page to learn how.

Alternatively, you can check each item's type in a different way. For example, you can call the Where() method and pass an expression that compares the item's type to the type you're looking for, as in the following example:

csharp collection.AsQueryable().Where(item => item.GetType() == typeof(T));

To learn more about type discriminators, see [Polymorphic Objects.](https://www.mongodb.com/docs/drivers/csharp/current/serialization/polymorphic-objects.md#std-label-csharp-polymorphism

  • The driver has sealed some types that were not designed for extension by using inheritance. This includes the following changes:

  • The driver seals all concrete serializers. To implement a custom serializer, implement the IBsonSerializer interface.

  • The driver seals the MongoClient, MongoDatabase, and MongoCollection classes. We recommend using the IMongoClient, IMongoDatabase, and IMongoCollection interfaces directly.

  • The driver requires applications to explicitly configure how to serialize GUIDs by using the GuidSerializer and ObjectSerializer classes. .NET/C# Driver users building new applications can implement a global GuidSerializer by registering it. We recommend that users with older applications verify that all GUIDs are serialized the same way when implementing a global GuidSerializer. You can also configure GUID serialization on a case-by-case basis without registering a global GuidSerializer.

To learn more about GUID serialization, see the [GUIDs](https://www.mongodb.com/docs/drivers/csharp/current/serialization/guids.md#std-label-csharp-guids guide.

  • By default, the driver serializes TimeOnly values as BSON int64 values representing Ticks. Previous versions of the driver serialized TimeOnly values as BSON documents by default.

To serialize a TimeOnly value as a document in .NET/C# Driver v3.0 through v3.5, register the TimeOnly type with a BsonClassMapSerializer, as shown in the following example:

csharp var timeOnlyClassMap = new BsonClassMap<TimeOnly>(cm => cm.AutoMap()).Freeze(); var serializer = new BsonClassMapSerializer<TimeOnly>(timeOnlyClassMap); BsonSerializer.RegisterSerializer(serializer);

Note: TimeOnly Feature Update for v3.6 and Later

To serialize a TimeOnly value as a document in .NET/C# Driver v3.6 or later, register a TimeOnlySerializer with BsonType.Document representation, as shown in the following example:

csharp BsonSerializer.RegisterSerializer(new TimeOnlySerializer(BsonType.Document));

You can also apply the BsonRepresentation(BsonType.Document) attribute to TimeOnly fields, as shown in the following example:

csharp public class Person { [BsonRepresentation(BsonType.Document)] public TimeOnly TimeBirth { get; set; } }