> This page location: /docs.md > /docs/drivers.md > /docs/languages/csharp.md > /docs/drivers/csharp/current.md > /docs/drivers/csharp/current/reference/upgrade.md

> 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](https://www.mongodb.com/docs/drivers/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.13 Breaking Changes

- The driver now rejects malformed raw BSON. Writing a raw BSON document or array throws an `ArgumentException` if its declared length is inconsistent with the buffer. The driver ignores bytes past the declared length.

- The driver no longer interns `BsonSymbol` values, and `BsonSymbolTable` is obsolete. Use `BsonSymbol.Create()` or the implicit string conversion instead.

- The driver now rejects binary subtypes outside the range 0 through 255. This affects the `BsonBinaryData` class, the JSON reader (`BinData`, `HexData`, and the legacy `$type` representation), and the binary writer.

- `PushEach()` and `AddToSetEach()` with a single value now always render `$each`, and `PullAll()` with a single value now always renders `$pullAll`. Earlier driver versions unwrapped a single value or rendered it as `$pull`.

- The `PatternProperty()` overload that takes a field expression is obsolete and produces a compiler warning. Use `Property()` to configure a specific field. The driver now matches field names that you pass to `PatternProperty()` both as literal field names and as regular expressions.

- GeoJSON serialization throws a `BsonSerializationException` when an extra member has the same name as a declared member.

- Automatic encryption passes the database name to `libmongocrypt` as UTF-8 instead of using the Windows ANSI code page. Databases with non-ASCII names now match their schema map namespaces.

- If you use a dictionary key, `BsonDocument` key, or `Mql.Field` name that MongoDB Server would reinterpret, LINQ translation now throws a `NotSupportedException`. This includes names that contain ".", names that start with "$" at the start of a path, and positional operators.

- To determine whether two `MongoClient` instances can share a cluster, the driver uses SHA-256 to compare their full client certificates. It also checks whether each certificate has a private key. The driver reads these settings from each client's `SslSettings` object. Earlier driver versions compared only the certificate issuer and serial number.

- `FindOneAndReplace()` throws an `ArgumentException` when the first element name of the replacement document starts with "$", consistent with `ReplaceOne()` behavior.

## 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](https://www.mongodb.com/docs/manual/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](https://www.mongodb.com/docs/drivers/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](https://www.mongodb.com/docs/manual/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](https://www.mongodb.com/docs/drivers/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](https://www.mongodb.com/docs/manual/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](https://www.mongodb.com/docs/drivers/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](https://www.mongodb.com/docs/drivers/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](https://www.mongodb.com/docs/manual/core/security-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.13.0/api/MongoDB.Bson/MongoDB.Bson.BsonValue.AsNullableLocalTime.html#MongoDB_Bson_BsonValue_AsNullableLocalTime) and [AsNullableUniversalTime](https://mongodb.github.io/mongo-csharp-driver/3.13.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.13.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.13.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()](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.Subscribe.html) 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; }
  }
  ```
