2.1.0

.NET Driver Version 2.1.0 Release Notes

This is a minor release which supports all MongoDB server versions since 2.4.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v2.1.0.md

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/issues/?filter=18283

Documentation on the .NET driver can be found at:

http://mongodb.github.io/mongo-csharp-driver/

New Features

Notable new features are listed below. For a full list, see the full list of JIRA issues linked above.

GridFS

CSHARP-1191 - GridFS support has been implemented.

LINQ

CSHARP-935 LINQ support has been rewritten and now targets the aggregation framework. It is a more natural translation and enables many features of LINQ that were previously not able to be translated.

Simply use the new AsQueryable method to work with LINQ.

Eventing

CSHARP-1374 - An eventing API has been added allowing a user to subscribe to one or more events from the core driver for insight into server discovery, server selection, connection pooling, and commands.

Upgrading

There are no known backwards breaking changes in this release.

1.10.1

C#/.NET Driver Version 1.10.1 Release Notes

This is a minor release and contains no API changes.

It also fixes some issues reported since 1.10.0 was released.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/v1.x/Release%20Notes/Release%20Notes%20v1.10.1.md

Documentation on the C# driver can be found at:

http://www.mongodb.org/display/DOCS/CSharp+Language+Center
http://api.mongodb.org/csharp/current/

General Changes

The 1.x releases will be the last non-bug fix release supporting .NET 3.5.

The issues fixed in 1.10.1 are:

CSHARP-1351 - ObjectSerializer should not be dependent on the order of the _t and _v elements.

Compatibility Changes

There were no intentional backwards breaking changes. If you come across any,
please inform us as soon as possible by email dotnetdriver@mongodb.com or by reporting
an issue at jira.mongodb.com.

2.0.1

.NET Driver Version 2.0.1 Release Notes

This is a patch release which fixes some issues reported since 2.0 was released. It is a recommended
upgrade for anyone using 2.0.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/v2.0.x/Release%20Notes/Release%20Notes%20v2.0.1.md

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/issues/?filter=17849

Documentation on the .NET driver can be found at:

http://mongodb.github.io/mongo-csharp-driver/

General Changes

The key issues fixed in 2.0.1 are:

• CSHARP-1264 WaitQueueSize now properly configures the server selection wait queue.
• CSHARP-1280 Deserializing fails if a document contains unmapped field which name starts with the same name as currently mapped class property.
• CSHARP-1265 Update variants allow sending empty documents as update statements, which results in a replacement.

Compatibility Changes

There were no intentional backwards breaking changes. If you come across any,
please inform us as soon as possible by email dotnetdriver@mongodb.com or by reporting
an issue at jira.mongodb.com.

2.0.0

.NET Driver Version 2.0.0 Release Notes

This is a major release which supports all MongoDB server versions since 2.4.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v2.0.0.md

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/issues/?jql=project%20%3D%20CSHARP%20AND%20fixVersion%20%3D%202.0%20ORDER%20BY%20key%20ASC

Documentation on the .NET driver can be found at:

http://mongodb.github.io/mongo-csharp-driver/

New Features

Notable new features are listed below. For a full list, see the full list of JIRA issues linked above.

Async

As has been requested for a while now, the driver now offers a full async stack. Since it uses Tasks, it is fully usable with async and await.

While we offer a mostly backwards-compatible sync API, it is calling into the async stack underneath. Until you are ready to move to async, you should measure against the 1.x versions to ensure performance regressions don't enter your codebase.

All new applications should utilize the New API.

New API

Because of our async nature, we have rebuilt our entire API. The new API is accessible via MongoClient.GetDatabase.

• Interfaces are used (IMongoClient, IMongoDatabase, IMongoCollection<TDocument>) to support easier testing.

• A fluent Find API is available with full support for expression trees including projections.

  var names = await db.GetCollection<Person>("people")
      .Find(x => x.FirstName == "Jack")
      .SortBy(x => x.Age)
      .Project(x => x.FirstName + " " + x.LastName)
      .ToListAsync();

• A fluent Aggregation API is available with mostly-full support for expression trees.

  var totalAgeByLastName = await db.GetCollection<Person>("people")
      .Aggregate()
      .Match(x => x.FirstName == "Jack")
      .GroupBy(x => x.LastName, g => new { _id = g.Key, TotalAge = g.Sum(x => x.Age)})
      .ToListAsync();

• Support for dynamic.

  var person = new ExpandoObject();
  person.FirstName = "Jane";
  person.Age = 12;
  person.PetNames = new List<dynamic> { "Sherlock", "Watson" }
  await db.GetCollection<dynamic>("people").InsertOneAsync(person);

Upgrading

As 2.0 is a major revision, there are some breaking changes when coming from the 1.x assemblies. We've tried our best to mitigate those breaking changes, but some were inevitable. These changes may not affect everyone, but take a moment to review the list of known changes below:

System Requirements

• .NET 3.5 and .NET 4.0 are no longer supported. If you still must use these platforms, the 1.x series of the driver will continue to be developed.
• CSHARP-952: We've removed support for partially trusted callers.

Packaging

• The nuget package mongocsharpdriver now includes the legacy driver. It depends on 3 new nuget packages, MongoDB.Bson, MongoDB.Driver.Core, and MongoDB.Driver. MongoDB.Driver is the replacement for mongocsharpdriver.
• CSHARP-616: We are no longer strong naming our assemblies. Our previous strong naming was signed with a key in our public repository. This did nothing other than satisfy certain tools. If you need MongoDB assemblies to be strongly named, it is relatively straight-forward to build the assemblies yourself.

BSON

• CSHARP-933: Improved the BSON Serializer infrastructure. Anyone who has written a custom serializer will be affected by this. The changes are minor, but were necessary to support dynamic serializers as well as offering great speed improvements and improved memory management.
• Certain methods, such as BsonMemberMap.SetRepresentation have been removed. The proper way to set a representation, for instance, would be to use SetSerializer and configure the serializer with the appropriate representation.
• CSHARP-939: Dynamic DictionaryRepresentation has been removed. Its intent was to store, in some manner, anything in a .NET dictionary. In practice, this leads to the same values getting stored in different ways depending on factors such as a "." inside the key name. We made the decision to eliminate this variability. This means that documents that used to serialize correctly may start throwing a BsonSerializationException with a message indicating the key must be a valid string. CSHARP-1165 has a solution to this problem. It should be noted that we will continue to read these disparate representations without error.

Driver

• CSHARP-979: MongoConnectionStringBuilder has been removed. Use the documented mongodb connection string format and/or MongoUrlBuilder.

• MongoServer is a deprecated class. Anyone using MongoClient.GetServer() will encounter a deprecation warning and, depending on how your build is setup, may receive an error. It is still safe to use this API until your code is ported to the new API. *Note that this API requires the use of the mongocsharpdriver to include the legacy API.

• CSHARP-1043 and CSHARP-1044: ReadPreference and WriteConcern were rewritten. These classes are now immutable. Any current application code that sets values on these classes will no longer function. Instead, you should use the With method to alter a ReadPreference or WriteConcern.

  var writeConcern = myCurrentWriteConcern.With(journal: true);

1.10.0

C#/.NET Driver Version 1.10 Release Notes

This is a minor release which is fully compatible with server version 3.0 and fully supports
the new features introduced by server version 3.0.

It also fixes some issues reported since 1.9.2 was released.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/v1.x/Release%20Notes/Release%20Notes%20v1.10.md

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/issues/?filter=16411

Documentation on the C# driver can be found at:

http://www.mongodb.org/display/DOCS/CSharp+Language+Center
http://api.mongodb.org/csharp/current/

General Changes

The 1.x releases will be the last non-bug fix release supporting .NET 3.5.

The issues fixed in 1.10 are:

• Support for changes in server 3.0
• Support SCRAM-SHA1 authentication
• Deprecate classes, properties and methods that will be removed in version 2.0
• other minor fixes (see JIRA tickets)

Note about SCRAM-SHA1 authenticaton

Starting with the MongoDB 3.0 release, the SCRAM-SHA1 authentication protocol is supported. By
itself, this will not cause any compatibility issues. However, before updating the server's
authentication schema such that the MONGODB-CR protocol is no longer available, you must
replace any calls to:

MongoCredential.CreateMongoCRCredential(...)

with calls to:

MongoCredential.CreateCredential(...)

Compatibility Changes

There were no intentional backwards breaking changes. If you come across any,
please inform us as soon as possible by email dotnetdriver@mongodb.com or by reporting
an issue at jira.mongodb.com.

1.9.2

C#/.NET Driver Version 1.9.2 Release Notes

This is a minor release which fixes some issues reported since 1.9.1 was released. It is a recommended
upgrade for anyone using 1.9.1.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/v1.x/Release%20Notes/Release%20Notes%20v1.9.2.md

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/issues/?filter=15440

Documentation on the C# driver can be found at:

http://www.mongodb.org/display/DOCS/CSharp+Language+Center
http://api.mongodb.org/csharp/current/

General Changes

The 1.9.x releases will be the last non-bug fix release supporting .NET 3.5.

The issues fixed in 1.9.2 are:

Kerberos authentication occasionally crashes runtime
Allow $external special database to be used
Handle pre-2.6 upserted identifier
Altered ObjectId generation to take into account the AppDomain
Added 2.6 extended json support to JsonReader
SetMaxScan rendered $maxscan instead of $maxScan
Updated output of JsonWriter to include 2.6 extended json support
Replica set tags GetHashCode was calculated improperly

Compatibility Changes

There were no intentional backwards breaking changes. If you come across any,
please inform us as soon as possible by email dotnetdriver@mongodb.com or by reporting
an issue at jira.mongodb.com.

1.9.1

C#/.NET Driver Version 1.9.1 Release Notes

This is a minor release which fixes some issues reported since 1.9.0 was released. It is a recommended
upgrade for anyone using 1.9.0.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/v1.x/Release%20Notes/Release%20Notes%20v1.9.1.md

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/issues/?filter=15166

Documentation on the C# driver can be found at:

http://www.mongodb.org/display/DOCS/CSharp+Language+Center
http://api.mongodb.org/csharp/current/

General Changes

The 1.9.x releases will be the last non-bug fix release supporting .NET 3.5.

The issues fixed in 1.9.1 are:

• LINQ queries against BsonValue properties whose value is C# null
• $maxDistance must go inside $near when using GeoJson data
• Allow ParallelScan to go to secondaries
• Allow Aggreagate to go to secondaries as long as the pipeline doesn't contain $out
• Support automatically setting the _id even when using an interface as the document type
• Don't consider any wnote and jnote values to be errors
• Fixed a stack overflow when deserializing an interface with a missing _t discriminator value
• Added SetBits to IndexOptions builder
• JsonReader support for new $date format with ISO8601 strings as used by 2.6 version mongoexport

Compatibility Changes

There were no intentional backwards breaking changes. If you come across any,
please inform us as soon as possible by email dotnetdriver@mongodb.com or by reporting
an issue at jira.mongodb.com.

1.9.0

C#/.NET Driver Version 1.9.0 Release Notes

This is a major release which supports all MongoDB server versions since 2.0.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v1.9.md

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=14713

Documentation on the C# driver can be found at:

http://www.mongodb.org/display/DOCS/CSharp+Language+Center
http://api.mongodb.org/csharp/current/

General Changes

This release is primarily in support of new features offered by server 2.6.
Additionally, this will be the last non-bug fix release supporting .NET 3.5.

Some of the notable features:

• Bulk Write Commands
• Text Search
• $out for aggregation
• Aggregation cursors
• Improved sorting in aggregation
• Aggregation explain
• x.509 Authentication
• LDAP Support for Authentication
• Max execution time enforcement

A full set of server changes in server 2.6 can be found here.

Compatibility Changes

There were no intentional backwards breaking changes. If you come across any,
please inform us as soon as possible by email dotnetdriver@mongodb.com or by reporting
an issue at jira.mongodb.com.

1.8.3

C#/.NET Driver Version 1.8.3 Release Notes

This is a minor release but is a recommended upgrade for all 1.8.2 users, particularly
if you use the limit option with queries (1.8.3 fixes a performance issue that occurs
when small limits are used with queries that would otherwise return a large number of
results).

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/v1.8.3/Release%20Notes/Release%20Notes%20v1.8.3.md

File by file change logs are available at:

https://github.com/mongodb/mongo-csharp-driver/blob/v1.8.3/Release%20Notes/Change%20Log%20v1.8.3-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/v1.8.3/Release%20Notes/Change%20Log%20v1.8.3-Driver.txt

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/issues/?filter=14059

Documentation on the C#/.NET driver can be found at:

http://docs.mongodb.org/ecosystem/drivers/csharp/
http://api.mongodb.org/csharp/current/

BSON Library Changes

Id mapping change

If the Id field is declared abstract or virtual in a base class and later overridden
in a derived class we were incorrectly mapping it twice. We now only map it once in
the class where it is first declared.

Driver Changes

Better handling of server state when errors occurr

When an error occurred on one connection we were setting the server instance state
to Unknown, which caused problems on other connections. Now we simply tell the server
instance to refresh its state as soon as possible.

GeoJson deserialization accepts numeric types besides doubles

In 1.8.2 the GeoJson deserializers required that the coordinate values be stored as
doubles. In 1.8.3 the Serialize method still stores them as doubles but the Deserialize
method can convert from other numeric types to doubles.

Id generators

The container parameter to the GenerateId method of the IIdGenerator interface was
inadvertently changed in 1.8.2. In 1.8.3 the value of the container parameter is once
again the MongoCollection instance for which an Id needs to be generated.

Performance problem with queries that used limit

The Execute method of the new QueryOperation class would in certain cases fetch one
more batch of results than necessary from the server. This did not affect the correctness
of the results but could result in a substantial loss of performance. This has been
fixed in 1.8.3.

Save method and _id values

The Save method has been simplified to correctly serialize the _id value for all
possible serializers. The new approach is slightly less efficient in some cases but
is the only approach that will work if custom serializers are being used. Since all
Save does is call either Insert or Update you can get slightly better performance
by calling Insert or Update yourself (call Insert if you know it's a new document
or call Update with an appropriate query and the Upsert flag if you are not sure).

1.8.2

C#/.NET Driver Version 1.8.2 Release Notes

This is a minor release.

An online version of these release notes is available at:

https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v1.8.2.md

File by file change logs are available at:

https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8.2-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8.2-Driver.txt

The full list of JIRA issues resolved in this release is available at:

https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=13830

Documentation on the C#/.NET driver can be found at:

http://docs.mongodb.org/ecosystem/drivers/csharp/
http://api.mongodb.org/csharp/current/

BSON Library Changes

Performance improvements

Serialization and deserialization of enumerable types that serialize to BSON
arrays has been sped up. The serializer for the nominal type is only looked
up once, and when using polymorphic types, the actual serializer only has to
be looked up when the actual type changes so runs of identical subtypes are
handled more efficiently.

WriteCString error checking

The BSON spec does not allow CStrings to have embedded nulls. The driver now
enforces this restriction thoroughly.

BsonMemberMaps are now frozen when BsonClassMap is frozen

The BsonMemberMap now has a Freeze method, and BsonClassMap now calls Freeze
on all the member maps when the Freeze is called on the class map.

Better support for mutable default values

A default value for mutable types is vulnerable to being altered by the
application, which would affect future uses of the default value. When using
a mutable type we really need a new instance of the default value every time.
There is now a new overload of SetDefaultValue that allows you to provide a
creator function instead of a value, so the creator function can instantiate
a new instance of the default value each time one is needed.

Driver Changes

Improved tracking of the primary for replica sets

Tracking of the current primary for replica sets has been made more reliable.
There were certain scenarios in which the driver might have two members
marked as being the current primary. With these changes there is a single
field that tracks the most recently seen primary so by definition there will
never be more than one.

Internal restructuring

Some changes were made to the internal implementation of the driver which do
not affect the public API. There is a new set of operation classes that
encapsulate the handling of wire protocol messages and some logic that used
to exist in MongoCollection has been moved to the operations. In addition,
the way commands are run has been refactored somewhat.

IndexCache removed

In the past drivers and the mongo shell kept track of calls to EnsureIndex in
order to optimize away additional round trips to the server for the same index.
But this approach has inherent problems, one of which is that it can't see
any changes made to the indexes by other processes. Therefore, the driver
no longer tracks calls to EnsureIndex and all calls to EnsureIndex are sent to
the server and it is up to the server to decide if the index already exists or
not. Typically this will not cause any backward compatibility problems and
the performance hit will be very small (unless you were calling EnsureIndex
very frequently).