Release Notes

What's New in 3.5

The 3.5 driver release includes the following new features, improvements, and fixes:

• Adds experimental support for Queryable Encryption prefix, suffix, and substring queries. These features are unstable, and their security is not guaranteed until they're generally available (GA). Use them in experimental workloads only. To learn more about QE, see In-Use Encryption.

• Adds the CsfleSchemaBuilder class to the MongoDB.Driver.Encryption package. You can use this class to create JSON schemas for Client-Side Field Level Encryption (CSFLE), as shown in the following example:

   var builder = CsfleSchemaBuilder.Create(schemaBuilder =>
   {
       schemaBuilder.Encrypt<Patient>(_collectionNamespace, builder =>
       {
           builder
              .EncryptMetadata(keyId: _keyId)
              .Property(p => p.MedicalRecords, BsonType.Array,
                  EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random)
              .Property("bloodType", BsonType.String,
                  algorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random)
              .Property(p => p.Ssn, BsonType.Int32,
                  EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic)
              .Property(p => p.Insurance, innerBuilder =>
              {
                  innerBuilder
                      .Property(i => i.PolicyNumber, BsonType.Int32,
                          EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic);
              })
              .PatternProperty("_PIIString$", BsonType.String, EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic)
              .PatternProperty("_PIIArray$", BsonType.Array, EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random)
              .PatternProperty(p => p.Insurance, innerBuilder =>
              {
                  innerBuilder
                      .PatternProperty("_PIIString$", BsonType.String,
                          EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic)
                      .PatternProperty("_PIINumber$", BsonType.Int32,
                          algorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic);
              });
       });
   });
  var schema = builder.Build();

  To learn more about CSFLE, see In-Use Encryption.

• Adds the following LINQ methods:

  • Median(): Computes the median of a sequence of values.

  • Percentile(): Computes multiple percentile of a sequence of values.

  You can use these methods to perform calculations as part of the $group and $setWindowFields aggregation stages.

• Adds new Ascending() and Descending() method overloads to the SortDefinitionBuilder class. You can use these methods to sort elements by value when using the $sort update operator.

• Adds support for using a SOCKS5 proxy to connect to MongoDB. You can specify SOCKS5 connection settings in the connection string or by using the MongoClientSettings.Socks5ProxySettings property.

• Adds support for the IAsyncEnumerable<T> interface in cursors and LINQ. You can use await foreach syntax to asynchronously iterate over query results.

• Adds big-endian support to the BinaryVectorReader and BinaryVectorWriter classes.

• Changes internal subsystems in preparation for supporting client-side operations timeout (CSOT) in an upcoming release. We expect these changes to be be backward-compatible and not to affect existing driver behavior. Please contact MongoDB if you experience any of the following issues:

  • Operations timing out unexpectedly or not timing out when expected

  • Unusual delays or hangs in database calls

  • Behavior differences when cancelling commands

  For the best ways to find support, see the Issues & Help page. Please provide driver logs and a reproduction if possible.

For more information about this release, see the v3.5 release notes on GitHub.

What's New in 3.4

The 3.4 driver release includes the following new features, improvements, and fixes:

• Adds the Mql.Convert() LINQ method to convert between types when performing aggregations. To learn more, see the $convert section of the LINQ guide.

• Adds support for the KeyValuePair.Create() LINQ method.

• Adds the GeoNear() aggregation builder method to construct a $geoNear aggregation stage. To view examples, see the $geoNear reference in the MongoDB Server manual.

• Supports casting from an interface to a type that implements that interface in LINQ queries.

• Supports the Dictionary(IEnumerable<KeyValuePair<TKey, TValue>> collection) constructor in LINQ.

• Adds the following options for MongoDB Search queries:

  • MatchCriteria in SearchTextOptions to set match criteria for terms passed to the Text() operator method.

  • Synonyms in SearchPhraseOptions to set the name of the synonym mapping definition when using the Phrase() operator method.

  To learn more about performing MongoDB Search queries, see the MongoDB Search guide.

• Supports LINQ queries after casting IQueryable<Derived> objects to IQueryable<Base>.

• Corrects MongoDB Search operator behavior to use configured serializers instead of predefined serializers. To use the previous behavior, set the following option:

  SearchDefinition.UseConfiguredSerializers(false);

For more information about this release, see the v3.4 release notes on GitHub.

What's New in 3.3

The 3.3 driver release includes the following new features:

• Adds a new NamespaceType field that indicates the type of the created object for create events in the ChangeStreamDocument class. To learn more about change streams, see the Monitor Data Changes guide.

• Adds the following In-Use Encryption features:

  • Support for the $lookup aggregation stage

  • A ClientEncryptionOptions property that configures the data-encryption key cache lifetime

  To learn more about In-Use Encryption, see the In-Use Encryption guide.

• Adds the following LINQ features:

  • Support for the SkipWhile() and TakeWhile() LINQ aggregation methods. To learn more, see the Skip on a Condition and Limit on a Condition sections of the LINQ guide.

  • Support for the $sigmoid expression in LINQ queries.

  • Support for using LINQ syntax to access any dictionary key that is serialized as a string, regardless of its underlying data type.

• Adds support for the $rankFusion aggregation stage, which enables rank-based result scoring on combined results from multiple pipelines.

• Adds support for $elemMatch queries directly against values by providing an overload of the ElemMatch() method that takes only a filter parameter. To learn more, see Update Arrays in One Document and Update Arrays in Many Documents.

• Adds support for using the OfType<T>() method and is operator to check the type of a scalar discriminator.

For more information about this release, see the v3.3 release notes on GitHub.

What's New in 3.2

The 3.2 driver release includes the following new features:

• Adds a new ObjectSerializerAllowedTypesConvention convention that allows you to specify which types are allowed to be serialized and deserialized by the object serializer. To learn more about conventions, see the Conventions guide.

• Adds a new constructor for the EnumRepresentationConvention class that allows you use the topLevelOnly parameter to specify whether the convention applies to only enum properties or to all properties that include collections of enums.

  You can instantiate the EnumRepresentationConvention class by using the new constructor as shown in the following example:

  EnumRepresentationConvention(BsonType representation, bool topLevelOnly);

• Optimizes client-side projections to retrieve only the required fields from the server, rather than retrieving all fields and then filtering them.

• Adds the following classes to support binary vector representations in MongoDB Vector Search:

  • BinaryVectorFloat32

  • BinaryVectorInt8

  • BinaryVectorPackedBit

  To learn more about MongoDB Vector Search with the .NET/C# Driver, see the Run a MongoDB Vector Search Query guide.

• Adds the DocumentFormat property to the DateOnlySerializer. This property allows you to customize the way that the driver serializes DateOnly values. This release also adds the [BsonDateOnlyOptions()] attribute to customize serialization behavior for DateOnly values at the property level. To learn more, see the Custom DateOnly Serialization section of the POCOs guide.

For more information about this release, see the v3.2 release notes on GitHub.

What's New in 3.1

The 3.1 driver release includes the following new features:

• Adds new default serializers for immutable collections in the System.Collections.Immutable namespace. The driver can now serialize ImmutableArray objects, and serialization for other immutable collections is more memory efficient.

• Adds the SearchIndexType type to support creation of MongoDB Vector Search indexes programmatically. To learn more, see the MongoDB Search and MongoDB Vector Search Indexes guide.

• Adds support for the token field type and array field expressions with MongoDB Search builders for the equals operator. To learn more about using MongoDB Search with the .NET/C# Driver, see MongoDB Search.

• Adds support for the following MongoDB Search queries:

  • Using the Equals() operator method on null and Guid values

  • Using the In() operator method on Guid values

  To learn more about these methods, see the MongoDB Search Operators and Collectors section of the MongoDB Search guide.

• Adds support for sequential pagination in MongoDB Search.

• Adds support for valid SRV hostnames with fewer than 3 parts.

• Adds support for the Exists, IsMissing, and IsNullOrMissing methods in MongoDB Query API filters.

• Adds support for Exact Nearest Neighbor (ENN) vector search. To learn more about ENN Vector Search, see Run Vector Search Queries in the MongoDB Search documentation.

• Adds a sort option for update and replace operations. This change allows you to set a sort order if multiple documents match your filter when attempting to update or replace a single document. To learn more, see the Update One and Update Many guides.

For more information about this release, see the v3.1 release notes.

What's New in 3.0

The 3.0 driver release includes the following new features:

• Adds the MongoClientSettings.TranslationOptions connection option, which specifies options for translating LINQ queries to the Query API. See Specify Connection Options for more information.

• Adds support for the Half type, which represents a half-precision floating-point number. This type is available in .NET 5 and later. To learn more about the Half type, see the Half Struct API reference page on MSDN.

• The IMongoClient interface inherits the IDisposable interface. As a result, the MongoClient class and other classes that implement the IMongoClient interface contain a Disp- Adds support for the ``sort option to be passed to update commands.ose()`` method, which disposes of the client. This method does not dispose the underlying cluster and connections to the MongoDB server. To dispose of the cluster and connections, call the ClusterRegistry.UnregisterAndDisposeCluster() method. The implementation of the IDisposable interface is experimental.

  To learn more about the IDisposable interface and use of the Dispose() method, see Dispose Pattern on MSDN.

• Adds support for the DateOnly type, which represents a date value with no time component. This type is available in .NET 6 and later. To learn more about the DateOnly type, see the DateOnly Struct. API reference page on MSDN.

• Adds support for the TimeOnly type, which represents a time value with no date component. This type is available in .NET 6 and later. To learn more about the TimeOnly type, see the TimeOnly Struct. API reference page on MSDN.

• Adds support for implicit client-side projection when using the Find() method, the Select() method, or the Project() aggregation stage with the LINQ3 provider. In previous versions of the driver, you could perform client-side projection with the LINQ3 provider only after calling the ToEnumerable() or AsEnumerable() method.

  To learn how to enable and use client-side projection for a driver method, select the corresponding tab:

  Find() Method

  Select() Method

  Project() Method

  // Enable client-side projection
  var findOptions = new FindOptions();
  findOptions.TranslationOptions = new ExpressionTranslationOptions
  {
      EnableClientSideProjections = true
  };
  var find = collection
      .Find(doc => doc.Id == 1, findOptions);
      .Project(doc => new { R = MyFunction(doc.Name) });

  // Enable client-side projection
  var aggregateOptions = new AggregateOptions();
  aggregateOptions.TranslationOptions = new ExpressionTranslationOptions
  {
      EnableClientSideProjections = true
  };
  var queryable = collection
      .AsQueryable(aggregateOptions)
      .Where(doc => doc.Id == 1)
      .Select(doc => new { R = MyFunction(doc.Name) });

  // Enable client-side projection
  var aggregateOptions = new AggregateOptions();
  aggregateOptions.TranslationOptions = new ExpressionTranslationOptions
  {
      EnableClientSideProjections = true
  };
  var aggregate = collection
      .Aggregate(aggregateOptions)
      .Project(doc => new { R = MyFunction(doc.Name) });

  Tip

  MongoClientSettings

  To enable client-side projection for all queries on a client, set the TranslationOptions property of your MongoClientSettings object, as shown in the following example:

  clientSettings.TranslationOptions = new ExpressionTranslationOptions
  {
      EnableClientSideProjections = true
  };

  To learn more about using the aggregation pipeline with the .NET/C# Driver, see Aggregation Operations.

• Adds a MongoClient API for bulk write operations. To learn more about bulk write operations, see Bulk Write Operations.

For more information about this release, see the v3.0 release notes.

What's New in 2.30

The 2.30 driver doesn't introduce new features or bug fixes. Its purpose is to ease migration to v3.x of the .NET/C# Driver by marking the public APIs that were removed in v3.0 as obsolete.

What's New in 2.29

The 2.29 driver release adds support for MongoDB Server version 8.0 and includes the following new features:

• Adds support for v2 of the Queryable Encryption range protocol.

• Adds support for range indexes for Queryable Encryption. For more information about Queryable Encryption, see Queryable Encryption in the MongoDB Server manual.

For more information about this release, see the v2.29 release notes.

What's New in 2.28

The 2.28 driver release includes the following new features:

• Adds support for additional numeric conversions involving Nullable<T>.

• Adds support for the delegated option when using KMIP for CSFLE or Queryable Encryption.

For more information about this release, see the v2.28 release notes.

What's New in 2.27

The 2.27 driver release includes the following new features:

• Adds support for the $sample aggregation operator.

• Implements the Equals() method for serializers in LINQ3.

• Ensures that read and write concerns are not applied to MongoDB Search Index Helper commands to avoid errors.

• Disallows the use of the comma character in authMechanismProperties connection string values when using the MONGODB-OIDC authentication mechanism.

• Fixes a translation bug that caused an error during serialization involving numbers of different sizes.

• Adds support for Linux distributions that use the libdl.so.2 library.

For more information about this release, see the v2.27 release notes.

What's New in 2.26

The 2.26 driver release includes the following new features:

• Added support for using the SelectMany() aggregation method within Select() and Project() aggregation stages.

• Added support for Dictionary.ContainsValue() calls in LINQ queries.

• Added support for string concatenation of mixed types.

• Enabled use of native crypto in libmongocrypt bindings.

• Added support for serialization of Memory and ReadOnlyMemory structs. To learn more about implementing these types, see the Improve Array Serialization Performance section of the Serialization guide.

• Added support for the GCP Identity Provider when using the MONGODB-OIDC authentication mechanism. To learn more, see GCP IMDS in the Enterprise Authentication Mechanisms guide.

• Implemented signing of NuGet packages.

• Implemented read and write retries to other mongos instances when possible.

What's New in 2.25

The 2.25 driver release includes the following new features:

• Added support for the MONGODB-OIDC authentication mechanism and automatic token acquisition for Azure Identity Provider.

• Added the class name to the error message reported when BsonClassMapSerializer cannot locate a matching creator.

• Added a LoggedStages field to surface the MQL executed after performing a LINQ query.

• Added support for overriding the "mongodb" service name with a custom one by using the srvServiceName connection option. To learn more, see the Specify Connection Options guide.

• Improved behavior of bulk write operations to prevent enumerating the requests parameter more than once.