Upgrade to Version 3.0
Overview
This page describes the changes you might need to make to your application when you upgrade the .NET/C# Driver to version 3.0.
How to Upgrade
This page lists the potential breaking changes introduced by the .NET/C# Driver version 3.0. To upgrade the .NET/C# Driver to version 3.0, follow these steps:
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.
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.
Address the breaking changes described in the Version 3.0 Breaking Changes 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.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 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 markedinternal
. 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.The driver replaces the
IMongoQueryable
interface with theIQueryable
interface, following the pattern used by most other LINQ providers. If your application contains references toIMongoQueryable
, replace them withIQueryable
.The driver removes the
ClusterBuilder.ConfigureSdamLogging()
method. To configure logging in your application, see the 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 theEnableClientSideProjections
property of aTranslationOptions
object totrue
. You can pass thisTranslationOptions
object to anAggregateOptions
orFindOptions
object to enable client-side projections for a single query, or to aMongoClientSettings
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 aBsonBinaryData
object from a GUID, use theBsonBinaryData.Create(Guid, GuidRepresentation)
constructor.The
BsonBinaryData.GuidRepresentation
property has been removed.You can call the
BsonBinaryData.ToGuid()
method only onBsonBinaryData
objects of subtype 4. If the object has any other subtype, you must call theBsonBinaryData.ToGuid(GuidRepresentation)
method and specify the subtype.
The preceding changes affect your application only if you serialize and deserialize BSON documents directly. If you map your MongoDB documents only to POCOs, the
GuidRepresentationMode
doesn't affect your application.To learn more about serializing GUIDs in the .NET/C# Driver, see the 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 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.
By default, the driver serializes
Decimal128
anddecimal
values as BSONDecimal128
values. In previous versions of the driver, the driver serialized these values as BSONstring
values by default. To serialize adecimal
orDecimal128
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 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 aDateTimeOffset
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 theOutputMode
property of this object to a value from theJsonOutputMode
enum, then pass the object to theToJson()
method when you serialize your document. The following code example shows how to serialize a BSON document to Strict JSON:// 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 oneCredential
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 Identity and Access Management.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
orNaN
value to an integral representation, the driver throws anOverflowException
. To learn more about floating-pointInfinity
andNaN
values, see Double.NaN, Double.PositiveInfinity, and Double.NegativeInfinity. on MSDN.The driver includes the following changes to the
BsonValue
class:Removes the
[Obsolete]
attribute from theAsLocalTime
andAsUniversalTime
properties.Adds the AsNullableLocalTime and AsNullableUniversalTime properties.
Removes the
AsDateTime
property. Use the AsUniversalTime property instead.Removes the
AsNullableDateTime
property. Use the 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:collection.Aggregate().OfType<T>() Call the
Aggregate().Match(item => item is T)
method, as in the following example: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 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:collection.AsQueryable().Where(item => item.GetType() == typeof(T)); To learn more about type discriminators, see Polymorphic Objects.
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
, andMongoCollection
classes. We recommend using theIMongoClient
,IMongoDatabase
, andIMongoCollection
interfaces directly.