Releases: mongodb/mongo-csharp-driver
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:
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:
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).
1.8.1
C#/.NET Driver Version 1.8.1 Release Notes
This is a minor release. It should be considered a mandatory upgrade from 1.8. The
issues fixed were minor changes but their impact is not minor. In particular, if
you are using replica sets or are using InsertBatch with very large batches you
should consider 1.8.1 a mandatory upgrade.
An online version of these release notes is available at:
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8.1-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8.1-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=13252
Documentation on the C#/.NET driver can be found at:
http://www.mongodb.org/display/DOCS/CSharp+Language+Center
http://api.mongodb.org/csharp/current/
BSON Library Changes
Handling of closed sockets
There was an unfortunate regression in 1.8 with respect to sockets closed by the
server which causes the driver to hang waiting for data that is never going to
arrive.
This was discovered by a user who called Shutdown (which of course resulted in
all sockets being closed), but you could also encounter this issue if
you are connecting to replica sets and the primary closes all sockets when it
steps down (either due to an explicit step down or a re-election).
AscendingGuidGenerator
If you are using Guids as your _ids and you want the values to be ascending so
that they are always inserted at the right hand side of the index you can use
this IdGenerator. Note that for the server to see the Guids as ascending you
have to make sure to store them in the right representation, which is
GuidRepresentation.Standard.
We used to recommend CombGuidGenerator for this use case, but we have since
realized that the Guids generated by the CombGuid are only considered ascending
when Guids are compared using SQL Server's method of comparing Guids.
Driver Changes
MongoCollection
There is a new overload of Distinct which returns the values as TValue(s)
instead of as BsonValue(s).
There was a bug in InsertBatch that resulted in a high probability of
InsertBatch failing if the batch was big enough to have to be split into
multiple sub-batches.
MongoDatabase
RunCommandAs now uses the standard serialization mechanisms to deserialize
all command results returned from the server.
1.8
C# Driver Version 1.8 Release Notes
This is a major release.
This release has two major goals: to support the new features of the 2.4 release
of the server and to begin preparing the path for some major cleanup in the 2.0
release of the driver by marking as obsolete in the 1.8 release items that we plan to
remove in the 2.0 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.md
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8-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=13193
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
In this release we are deprecating a large number of methods that we intend to
remove in a subsequent release. With few exceptions, these deprecated methods
still exist and continue to work as they used to, so you can choose when to
transition off of them. Because they are deprecated they will result in
compile time warnings.
BSON Library Changes
Changes to the IO classes
The ReadBinaryData, ReadObjectId and ReadRegularExpression methods have simplified
signatures. There is a new ReadBytes method, as well as new ReadRawBsonArray
and ReadRawBsonDocument methods.
The WriteBinaryData, WriteObjectId and WriteRegularExpression methods have simplified
signatures. There is a new WriteBytes method, as well as new WriteRawBsonArray
and WriteRawBsonDocument methods.
The settings classes for the binary readers and writers now have an Encoding property
that you can use to provide an encoding. The value you supply must be an instance of a
UTF8Encoding, but you can configure that encoding any way you want. In particular,
you would want to configure lenient decoding if you have existing data that does not
conform strictly to the UTF8 standard.
BsonDocument object model changes
We are deprecating all the static Create factory methods and encourage you to
simply call the constructors instead. We are also no longer attempting to
cache any precreated instances of any BSON value (e.g. BsonInt32.Zero). These
classes are so light weight that there is no need to cache them.
A really helpful change is that you can now use indexers on documents and
arrays without having to use AsBsonDocument or AsBsonArray first. You can
now write:
var zip = person["Addresses"][0]["Zip"].AsString;
instead of
var zip = person["Addresses"].AsBsonArray[0].AsBsonDocument["Zip"].AsString;
The new LazyBsonDocument and LazyBsonArray classes allow you to defer
deserialization of elements until you first access them. The document or
array is kept in its raw byte form until you first access it, at which point
one level is deserialized. This can be a big performance win if you only
access some parts of a large document.
The new RawBsonDocument and RawBsonArray classes are similar to their lazy
counterparts, except that the data is always kept in raw bytes form only
and any elements you access are deserialized every time you access them.
The new Lazy and Raw classes are useful when you want to copy large documents
from one place to another and only need to examine a small part of the
documents.
New conventions system for automatically creating class maps
The BsonClassMapSerializer relies on class maps to control how it
serializes documents. These class maps have to be created. The easiest
way to create the class maps is to let the driver create them automatically,
which it does based on a number of conventions that control the process.
The implementation of the conventions system is completely new in this
release. Conventions implemented using the old conventions architecture
are still supported but will be based on deprecated classes and interfaces
and should be rewritten to use the new architecture.
Deserialization can now call constructors or static factory methods
You can now identify constructors or static factory methods that can
be used during deserialization to instantiate objects. This means that
it is now possible to deserialize immutable classes. During deserialization
values from the serialized document are matched to parameters of a constructor
or static factory method. If there is more than one possible constructor
or factory method then the one with the most matching parameters is chosen.
Standard serializers are now created and registered as late as possible
The standard built-in serializers are now created and instantiated as late
as possible, giving you a chance to create and register your own if you
prefer. You can either register the standard built-in serializers with
different default serialization options, or you can write and register
your own.
BsonDocument object model serialization standardized
Serialization of BsonDocument object model classes has been completely
moved to IBsonSerializer based classes. The existing ReadFrom/WriteTo
methods in the BsonDocument object model have been deprecated.
Driver Changes
New authentication model
In previous versions of the driver there was only one kind of credential
(a username/password credential) and there was a mapping that specified
which credential to use for each database being accessed. Based on that
mapping the driver would determine which credential was needed for the
database being accessed and would ensure that the connection being used
was authenticated properly.
The authentication model on the server has changed drastically, and it is no
longer required that the credential used to access a database be stored
in that same database. Therefore it is impossible to determine in advance
which credential is the one that will give you access to a database. So
now the drivers simply work with a list of credentials, with no attempt
to figure out which credential should be used with which database. Instead,
all connections are authenticated against all of the credentials supplied.
Strict enforcement of MaxConnectionIdleTime and MaxConnectionLifeTime
Previously these values were only loosely enforced and were treated more
like hints. Now they are enforced strictly. This helps prevent network
errors in certain environments where the networking infrastructure will
terminate connections that are idle for a certain amount of time or that
have been open too long (for example, some firewalls and Azure).
Driver no longer opens and closes a connection every 10 seconds
The driver pings the state of any server it is connected to once every
10 seconds. In earlier releases it would open and close a new connection
each time. While this guaranteed that the ping would happen wihtout delay
it had the unfortunate consequence of filling the server logs with
messages reporting the opening and closing of the connections. The
driver now tries to reuse an existing connection for the ping, and will
only open a new one if it can't acquire an existing one rapidly.
Removed DeprecatedQuery and DeprecatedQueryBuilder classes
These classes have been deprecated for several releases now and have
been removed entirely.
Changes to Fields builder
There is a new ElemMatch method to select which elements of an array
to include in the result documents.
Changes to Query builder
The new GeoIntersects method supports the $geoIntersects query operator with
GeoJson values. In addition, new overloads of Near and Within support
using GeoJson values with these existing query operators.
Changes to Update builder
New SetOnInsert method to support the $setOnInsert update operator.
New overload of PushEach that has a PushEachOptions parameter that can
be used to provide advanced options to the $pushEach update operator.
Changes to Index builder
Added support for creating hashed and 2dsphere indexes.
GeoJson object model
The GeoJson object model is a type-safe in memory representation of GeoJSON
objects. When these objects are serialized to BSON documents the resulting
BSON documents will be valid GeoJSON documents. You can use the GeoJson
object model to represent GeoJSON properties in your POCOs and to provide
values to the new methods added to the Query builder to support GeoJson queries.
Simplified settings classes
The settings classes have been simplified a bit and we have standardized how
settings are stored internally and how default values are applied. See the
comments below on the different settings classes.
MongoClientSettings
The CredentialsStore and DefaultCredentials properties have been replaced by
the new Credentials property. The CredentialsStore property was a mapping from
a database name to the credential to use to access that database. The Credentials
property is simply a list of credentials that will be used with all connections,
regardless of which database is being accessed.
There is a new SslSettings property that lets you control every aspect of an
SSL connection to the server.
The new ReadEncoding and WriteEncoding settings can be used to configure the
details of UTF8 encoding.
MongoServerSettings
While this class has not yet been deprecated, it eventually will be. We recommend
you always use MongoClientSettings instead.
The new settings added to MongoClientSettings have also been added to
MongoServerSettings.
MongoDatabaseSettings
The database name has been moved out of the settings class and is now an
argument to the GetDatabase method. Therefore the DatabaseName property
has been deprecated.
The proper way to create an instance of MongoDatabaseSettings is to call the
constructor. The CreateDatabaseSettings method of MongoServer ...
v1.7.1.4791
Version 1.7.1.4719.
1.7
C# Driver Version 1.7 Release Notes
This is a major release.
This release has two major goals: to standardize on the name WriteConcern and
to make Acknowledged the new default WriteConcern.
The following classes are being replaced:
- SafeMode is replaced by WriteConcern
- SafeModeResult is replaced by WriteConcernResult
- MongoSafeModeException is replaced by WriteConcernException
To make Acknowledged the new default WriteConcern without breaking any existing
code that might rely on the old default we are introducing a new root class
called MongoClient.
An online version of these release notes is available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v1.7.md
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.7-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.7-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=12915
Documentation on the C# driver can be found at:
http://www.mongodb.org/display/DOCS/CSharp+Language+Center
http://api.mongodb.org/csharp/current/
Standardizing on WriteConcern instead of SafeMode
Some MongoDB drivers (the C# driver included) have used SafeMode as the name
for the class which determines whether writes to the database are checked for
errors. We are now standardizing across all drivers to use the name WriteConcern
instead of SafeMode. The C# driver will continue to support the SafeMode class
for a few releases but eventually it will be removed.
You should start using the new WriteConcern class, but we have also provided
an implicit conversion from SafeMode to WriteConcern so any code that passes
a SafeMode argument to a method taking a WriteConcern parameter will still
compile and work.
New MongoClient class and default WriteConcern
The new default WriteConcern is Acknowledged, but we have introduced the new
default in a way that doesn't alter the behavior of existing programs. We
are introducing a new root class called MongoClient that defaults the
WriteConcern to Acknowledged. The existing MongoServer Create methods are
deprecated but when used continue to default to a WriteConcern of Unacknowledged.
In prior releases you would start using the C# driver with code like this:
var connectionString = "mongodb://localhost";
var server = MongoServer.Create(connectionString); // deprecated
var database = server.GetDatabase("test"); // WriteConcern defaulted to Unacknowledged
The new way to start using the C# driver is:
var connectionString = "mongodb://localhost";
var client = new MongoClient(connectionString);
var server = client.GetServer();
var database = server.GetDatabase("test"); // WriteConcern defaulted to Acknowledged
If you use the old way to start using the driver the default WriteConcern will
be Unacknowledged, but if you use the new way (using MongoClient) the default
WriteConcern will be Acknowledged.
1.6.1
C# Driver Version 1.6.1 Release Notes
This is a minor release containing a few bug fixes, particularly related to ReadPreference support
and sending commands to secondaries.
An online version of these release notes is available at:
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.6.1-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.6.1-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=12609
Changes to ReadPreference
The implementation of ReadPreference has been changed to more accurately follow the ReadPreference spec:
http://docs.mongodb.org/manual/applications/replication/#read-preference
The changes are:
- SecondaryPreferred only uses the Primary if no secondaries are available (regardless of latency)
- SecondayAcceptableLatency is now configurable
- when sending queries to mongos:
- ReadPreference.Primary is encoded setting the SlaveOk bit on the wire protocol to 0
- ReadPreference.SecondaryPreferred (without tags) is encoded setting the SlaveOk bit on the wire protocol to 1
- all other ReadPreferences are encoded using $readPreference on the wire
- $query is now encoded before $readPreference as required by mongos
- commands now correctly use the collection settings (they were using the database settings)
Sending commands to secondaries
Only a limited set of commands are now allowed to be sent to secondaries. All other commands
will be sent to the primary regardless of the ReadPreference you specify. The commands
that can be sent to secondaries are:
- aggregate
- collStats
- count
- dbStats
- distinct
- geoNear
- geoSearch
- geoWalk
- group
- mapReduce (but only if using Inline results)
The corresponding helper methods in the C# driver are:
- MongoCollection.Aggregate
- MongoCollection.GetStats
- MongoCollection.Count, MongoCursor.Count and MongoCursor.Size
- MongoDatabase.GetStats
- MongoCollection.Distinct
- MongoCollection.GeoNear and MongoCollection.GeoNearAs
- MongoCollection.GeoHaystackSearch and MongoCollection.GeoHaystackSearchAs
- MongoCollection.Group
- MongoCollection.MapReduce (with MapReduceOutputMode.Inline)
There is no helper method (yet) for the geoWalk command.
1.6
C# Driver Version 1.6 Release Notes
This is a major release featuring support for server 2.2. The major change is
support for read preferences, allowing tag based granularity for selecting
servers to send commands and queries to. In addition, we have added support
for SSL and a helper method for the new aggregation framework.
An online version (with possible corrections) of these release notes is available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v1.6.md
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.6-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.6-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=12011
Information about read preferences is available online at:
http://docs.mongodb.org/manual/applications/replication/#read-preference
These release notes describe the changes at a higher level, and omits describing
some of the minor changes.
Breaking changes
- Commands are no longer always sent to primaries. If you are expecting this
behavior, ensure that your read preference is set to Primary. - ConnectWaitFor has been removed and replaced with read preferences. Anyone
using the ConnectWaitFor enumeration will need to change their code. - The serialized representation for a C# null of type BsonNull has been changed
from { $csharpnull : true } to { _csharpnull : true } to work around limitations
of the server. Existing data will still be correctly deserialized but new data
will be written in the new format. This is very unlikely to affect you because
it is very unlikely you have any properties of type BsonNull in your classes.
New features
- There is a new [BsonSerializer] attribute that can be used to specify which
serializer to use for a class. - Instances of ReadOnlyCollection are now serializable/deserializable.
- Queries involving Mod now work with 64-bit integers also.
- Support for TTL collections (see IndexOptions.SetTimeToLive).
- Simple helper method for aggregation framework (see MongoCollection.Aggregate).
- SlaveOK has been deprecated and replaced with the more flexible ReadPreference options.
- Support for SSL connections.
- Improved support for LINQ queries from VB.NET.
- Support for connecting to multiple mongos’ with load balancing