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:

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.

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

• 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 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 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, 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 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 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:

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

• 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, Double.PositiveInfinity, and 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 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, 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 guide.