Releases: mongodb/mongo-csharp-driver
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:
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:
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:
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
1.5
C# Driver Version 1.5 Release Notes
This is a major release featuring Typed Builders, enhanced LINQ support, and serialization of custom collections. There are significant serialization performance improvements, specifically when using class maps. In addition, there are a number of other enhancements and bug fixes.
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.5-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.5-Driver.txt
These release notes describe the changes at a higher level, and omit describing
some of the minor changes.
Breaking changes
-
Any custom IBsonSerializer implementations utilizing the methods GetDocumentId, SetDocumentId, GetMemberSerializationInfo, or GetItemSerializationInfo will need to implement the corresponding interface to restore functionality; IBsonIdProvider, IBsonDocumentSerializer, IBsonArraySerializer
-
A call to BsonSerializer.RegisterSerializer will now fail for types that implement IBsonSerializable
-
The BsonDefaultSerializer methods IsTypeDiscriminated, LookupActualType, LookupDiscriminatorConvention, RegisterDiscriminator, and RegisterDiscriminatorConvention have been moved to BsonSerializer.
-
ObjectId.TryParse will now return false instead of throwing an exception when argument is null
-
BsonDocumentWrapper no longer ignores null, but wrather wraps it with a BsonNull.Value. Any code relying on BsonDocumentWrapper ignoring null will need to be evaluated.
-
Custom collection/dictionary classes are now serialized by a collection/dictionary serializer instead of the class map serializer. This means that the items will be serialized instead of the properties and fields. Any code relying on the old behaviour will need to use BsonClassMap.RegisterClassMap with their custom collection/dictionary to preserve the old behaviour.
-
The static Query class used to build queries has changed significantly. Users of this class can either modify their code or add a using statement alias to the old version. The DeprecatedQuery version will get dropped in version 2.0.
using Query = MongoDB.Driver.Builders.DeprecatedQuery;
JIRA issues resolved
The full list of JIRA issues resolved in this release is available at:
https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=11900
High-Level Library Changes
Medium Trust
Support for medium trust is still not here. The communication protocol with a mongodb server is over TCP, which is dissallowed in vanilla medium trust environments. However, a slightly altered, custom medium trust permission system allowing sockets enables the driver to run fully. This can be done by copying the existing medium trust policy file and:
-
adding the SocketPermission:
<SecurityClass Name="SocketPermission" Description="System.Net.SocketPermission, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> -
adding an IPermission for the new SocketPermission security class:
<IPermission class="SocketPermission" version="1" Unrestricted="true"/>
Support for Azure partial trust should work without changes. However, the default trust level for Azure is full, so this will only affect you if you have changed your Azure defaults.
Custom Collection Serialization
Classes that implement IDictionary or IDictionary<TKey, TValue> are now always serialized by a DictionarySerializer. Classes that implement IEnumerable ot IEnumerable< T > are now always serialized by a CollectionSerializer. We believe that a large majority of the time, classes implementing the collection interfaces intend for their items to be persisted rather than any properties (such as Count). This should enable the use of custom collection classes without any extra effort on your part.
Query Builder
We have rewritten the static Query class. The old Query class followed the odd query syntax of mongodb and was found to be somewhat unintuitive for those coming from traditional C# backgrounds and relational databases. In addition, as we completed the new typed Query< T > static class (discussed below) to aid the building of queries for classes that are using class maps underneath, we found that the difference in the old one and the new one was too stark.
In the older version, a complex query would be built as follows.
var query = Query.Or(
Query.Exists("fn", true).NE("Jack"),
Query.GTE("age", 20).LTE(40));
There are some implied "ands" for the two fields(name and age) that we wanted to remove so that the generated query was as predictable as possible. The new query syntax is a little more verbose, but we believe overall easier to understand.
var query = Query.And(
Query.And(
Query.Exists("fn"),
Query.NE("fn", "Jack"))
Query.And(
Query.GTE("age", 20),
Query.LET("age", 40)));
In many cases, you might find that you don't need to change anything, as the syntax is only different when a conjunction is chained. However, if you use this syntax a lot, then you can still use the old query builder by including a using statement in your files as follows:
using Query = MongoDB.Driver.Builders.DeprecatedQuery;
In version 2.0, we'll be removing the DeprecatedQuery class, so you'll need to update eventually.
Typed Builders
In conjunction with the new query builder, we have also included typed builders that mirror all the existing builders. So, Query has a corresponding Query< T > class, Update has a corresponding Update< T > class, etc... The huge benefit to this is that you can remove your "magic" strings from your code! In addition, anyone using custom serializers with class maps has support built-in for value based comparisons.
For instance, given that we have a Person class defined:
public class Person
{
[BsonRepresentation(BsonType.ObjectId)]
public string Id { get; set;}
[BsonElement("fn")]
public string FirstName { get; set;}
[BsonElement("ln")]
public string LastName { get; set;}
[BsonElement("age")]
public int Age { get; set;}
}
Without the typed builder, a typical query might look like this:
ObjectId idFromUserInput = ...;
var query = Query.And(
Query.NE("_id", idFromUserInput),
Query.EQ("fn", "Jack"));
In the above query for a person, we need special knowledge to construct a valid query. First, that "Id" is "_id" in mongodb. Second, that "_id" is an ObjectId, even though our class exposes it as a string. And third, that "FirstName" is "fn" in mongodb. With the typed builders, you can specify this configuration information in one place, either as attributes or through the fluent configuration api, and never need to think about it again, as is demonstrated below, where the exact same query is generated as above.
string idFromUserInput = ...;
var query = Query.And(
Query<Person>.NE(p => p.Id, idFromUserInput),
Query<Person>.EQ(p => p.FirstName, "Jack"));
In addition, the typed query builders are type-safe, so you can't put an integer value where you have declared your property as a string. However, the biggest benefit to our internal refactoring is that you can now express your queries as predicates, making the above query even easier and more readable.
string idFromUserInput = ...;
var query = Query<Person>.Where(p => p.Id != idFromUserInput && p.FirstName == "Jack");
LINQ Enhancements
We continue to make Linq improvements. Thanks to all who report missing features and problematic queries. Linq is difficult to implement because IQueryable provides a lot of flexibility and operators that simply aren't supported in MongoDB. Where implementation makes sense, we will continue to enhance our linq implementations. As such, we have implemented a number of new operators:
-
Added support for & and | operators when both sides evaluate to a boolean.
-
Added support for the Any operator when the target is an enumerable of documents. This will generate an $elemMatch query. We do NOT support targets that are enumerables of primitives because the mongodb server does not support those. As soon as the server supports this, we will add this in as well.
-
Using ToUpper or ToLower will generate a case-insentive query to mongodb using a regular expression.
-
There are a number of times when certain queries will always evaluate to false. These queries will generate a special query that will utilize an index when possible, but still always evaluate to false on the server. Don't be surprised to see this query in your query plans: { "_id" : { $type : -1 } }. In addition, there are some queries that always evaluate to true. These will generate an empty query document: { }.
// { "_id" : { $type : -1 } } var query = Query<Person>.Where(p => p.Name.ToUpper() == "Abc"); -
Nullable Enums are now supported.
-
ContainsKey on any typed impementing IDictionary or IDictionary<K,V> is now supported and will generate a query corresponding to it's serialization format.
-
Contains can now be used on any type implementing IEnumerable or IEnumerable< T > and will be serialized to it's corresponding form. In the case of a local collection containing a field, this would generate an $in clause.
var local = new List<int> { 1, 2, 3}; // {"Age" : { $in : [1,2,3] } } var query = from p in people.AsQueryable() where local.Contains(p.Age) select p; -
Type queries either via comparison
Query<A>.Where(a => a.GetType() == typeof(T))or in LINQ
collection.AsQueryable().OfType<T>()are supported for those of you using inheritance in your class maps. These will generate queries where the type discriminator is checked for the proper value.
GridFS Changes
In previous releases, download...
1.4.2
C# Driver Version 1.4.2 Release Notes
This minor release fixes a few issues found in the 1.4.1 release.
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4.2-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4.2-Driver.txt
These release notes describe the changes at a higher level, and omit describing
some of the minor changes.
Breaking changes
After 1.4.1 was released it was discovered that there were some minor breaking
changes. The breaking changes were in methods that we considered to be internal,
but that were not made private so that they leaked out into the public API.
Those methods have now been marked obsolete and will be made private in
a future release. The 1.4.2 release restores backward compatibility for these
methods (GetDocumentId and SetDocumentId in BsonDocument).
JIRA issues resolved
The full list of JIRA issues resolved in this release is available at:
https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=11409
BSON library changes
GetDocumentId/SetDocumentId marked obsolete
These methods were intended to be private. They have been marked as obsolete
and will be made private in a future release.
Driver changes
Query.All/In/NotIn
There was an issue with Query.All/In/NotIn that might have affected you. If you
cast a BsonArray to IEnumerable<BsonValue> before calling Query.All/In/NotIn
you would get an exception. This only happened when casting a BsonArray to
IEnumerable<BsonValue>. If you passed a BsonArray to the BsonArray overload or
passed an IEnumerable<BsonValue> that was not a BsonArray to the
IEnumerable<BsonValue> overload no exception was thrown.
RequestStart/RequestDone
Calling RequestStart when the connection pool was oversubscribed would often
result in a deadlock. This has been fixed in the 1.4.2 release.
Ping/VerifyState
These methods are usually called from a timer to monitor the state of the
server (or of multiple servers if connected to a replica set), but you can
also call them yourself. These methods now use a new connection instead
of one from the connection pool so that they are not delayed waiting for a
connection when the connection pool is oversubscribed.
1.4.1
C# Driver Version 1.4.1 Release Notes
This minor release fixes a few issues found by users of the LINQ support added
in v1.4 of the C# driver and also adds support for a few new LINQ query
operators and where clauses.
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4.1-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4.1-Driver.txt
These release notes describe the changes at a higher level, and omit describing
some of the minor changes.
Breaking changes
There are no breaking changes in this release.
JIRA issues resolved
The full list of JIRA issues resolved in this release is available at:
https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=11397
LINQ query support
The main purpose of this minor release is to fix some issues found by users of
the new LINQ support added in v1.4.
One bug that many have encountered is a NullReferenceException when writing a
query against an inherited property.
https://jira.mongodb.org/browse/CSHARP-418
You would hit this error if you had any queries that were similar to this:
public class B
{
public ObjectId Id;
}
public class C : B
{
public int X;
}
var query =
from c in collection.AsQueryable<C>()
where c.Id = id // class C inherits Id from class B
select c;
Another bug that a few users have encountered is an ArgumentOutOfRangeException
when writing a LINQ query that consists of a bare AsQueryable and nothing else:
https://jira.mongodb.org/browse/CSHARP-419
as in this sample:
var query = collection.AsQueryable<C>(); // no where clause
Normally a query would contain something else besides the call to AsQueryable
(like a where clause), but this is a legal query and is now supported.
BSON library changes
MaxSerializationDepth
The BSON serialization mechanism does not support circular references in your
object graph. In earlier versions of the C# driver if you attempted to
serialize an object with circular references you would get a
StackOverflowExpection. The 1.4.1 version now tracks the serialization depth
as it serializes an object and if it exceeds MaxSerializationDepth a
BsonSerializationException is thrown. The problem with StackOverflowException
was that it was fatal to your process, but the BsonSerializationException can
be caught and your process can continue executing if you choose.
The default MaxSerializationDepth is 100.
Interpretation of C# null vs BsonNull.Value
When working with the BsonDocument object model a C# null is usually ignored,
specially when creating BsonDocuments using functional construction. However,
when mapping between .NET types and the BsonDocument object model a C# null
will now be mapped to a BsonNull. For example:
var dictionary = new Dictionary<string, object> { { "x", null } };
var document = new BsonDocument(dictionary);
// document["x"] == BsonNull.Value
and when mapping in the reverse direction a BsonNull will map to a C# null:
var document = new BsonDocument { { "x", BsonNull.Value } };
var dictionary = document.ToDictionary();
// dictionary["x"] == null
Usually mapping between .NET types and the BsonDocument object model happens
automatically as needed, but if you want to invoke the mapping yourself you
can access the BsonTypeMapper directly:
var dictionary = new Dictionary<string, object> { { "x", null } };
var document = BsonTypeMapper.MapToBsonValue(dictionary);
// document["x"] == BsonNull.Value
or in the other direction:
var document = new BsonDocument { { "x", BsonNull.Value } };
var dictionary = (IDictionary<string, object>)BsonTypeMapper.MapToDotNetValue(document);
// dictionary["x"] == null
Serializing read-only properties
The class map based serialization support normally serializes only public
read-write properties (or fields). Sometimes it can be useful to serialize
read-only properties as well, specially if you want to query against them.
You can now opt-in your read-only properties so that they appear in the
serialized document. For example:
public class Book
{
public ObjectId Id;
public string Title;
[BsonElement] // opt-in the read-only LowercaseTitle property
public string LowercaseTitle { get { return Title.ToLower(); } }
}
Now when a Book is serialized the document will look like:
{
_id : ObjectId("4f8d771dae879111d289dbc0"),
Title : "For Whom the Bell Tolls",
LowercaseTitle : "for whom the bell tolls"
}
During deserialization any elements in the serialized document that
correspond to read-only properties are ignored.
Driver changes
MongoServer
There is a new method called IsDatabaseNameValid that you can call to test if
a database name is valid.
MongoDatabase
There is a new method called IsCollectionNameValid that you can call to test if a
collection name is valid.
MongoGridFS
You can now disable computing the MD5 at the server when uploading a GridFS
file. You can also disable the client side verification of the MD5 that is
normally done on Upload or Download. The reason you might choose to disable
MD5 verification is that it is computationally expensive to compute the MD5.
LINQ OfType query operator
You can now use the OfType query operator in LINQ queries. For example:
var query = collection.AsQueryable<B>().OfType<C>();
this generates a query against the "_t" discriminator value that is used to
identify the actual type of a serialized document.
Additional expressions supported in LINQ where clauses
The following expressions are now supported in LINQ where clauses:
// d is the document
// p is a property of the document
// c is a character constant
// ca is an array of character constants
// s is a string constant
// i, j, k, n are integer constants
where d.p.Equals(constant)
where string.IsNullOrEmpty(d.p)
where d.p.IndexOf(c) == i
where d.p.IndexOf(c, j) == i
where d.p.IndexOf(c, j, k) == i
where d.p.IndexOf(s) == i
where d.p.IndexOf(s, j) == i
where d.p.IndexOf(s, j, k) == i
where d.p.IndexOfAny(ca) == i
where d.p.IndexOfAny(ca, j) == i
where d.p.IndexOfAny(ca, j, k) == i
where d.p[i] == c
where d.p.Length == n
where d.p.ToLower().Contains("xyz")
where d.p.ToLower().StartsWith("xyz")
where d.p.ToLower().EndsWith("xyz")
where d.p.ToUpper().Contains("xyz")
where d.p.ToUpper().StartsWith("xyz")
where d.p.ToUpper().EndsWith("xyz")
where d.p.Trim().Contains("xyz")
where d.p.Trim().StartsWith("xyz")
where d.p.Trim().EndsWith("xyz")
where d.p.TrimStart().Contains("xyz")
where d.p.TrimStart().StartsWith("xyz")
where d.p.TrimStart().EndsWith("xyz")
where d.p.TrimEnd().Contains("xyz")
where d.p.TrimEnd().StartsWith("xyz")
where d.p.TrimEnd().EndsWith("xyz")
where d.GetType() == typeof(T)
where d is T
// you can use any combination of ToLower/ToUpper/Trim/TrimStart/TrimEnd
// before Contains/StartsWith/EndsWith
In the 1.4 version of the C# driver the constant always had to appear on the
right of a comparison operator. That restriction is lifted in 1.4.1 so now the
following are equivalent:
where d.Height < 60
where 60 > d.Height
Type of in AsQueryable can now be deduced
The type of in the call to AsQueryable can now be deduced from the collection argument:
var collection = database.GetCollection<MyDocument>("mydocuments")
var query = collection.AsQueryable(); // <T> is deduced to be MyDocument
v1.4
C# Driver Version 1.4 Release Notes
The major feature of this release is support for LINQ queries. Some of the other
changes (e.g. new IBsonSerializer methods) are also in support of the new LINQ
implementation.
File by file change logs are available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4-Bson.txt
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4-Driver.txt
These release notes describe the changes at a higher level, and omit describing
some of the minor changes.
Breaking changes
There are some breaking changes in this release. Some of them are only breaking
at the binary level and are easily taken care of by simply recompiling your
application. Others require minor changes to your source code. Many of the
breaking changes are in low level classes, and these won't affect most users,
unless for example you are doing things like writing custom serializers.
Please read these release notes carefully before adopting the new 1.4 release
of the C# driver to determine if any of the breaking changes affect you.
LINQ query support
As stated previously, the major feature of this release is support for LINQ
queries. These release notes don't describe the new LINQ support, for that
please refer to the online LINQ tutorial at:
http://www.mongodb.org/display/DOCS/CSharp+Driver+LINQ+Tutorial
(Please note that the LINQ tutorial won't be available until several weeks
after the 1.4 release has been shipped. Sorry.)
CLS compliance
Both the MongoDB.Bson.dll and MongoDB.Driver.dll libraries have been marked
as CLS compliant, which should make them more useful from other .NET languages.
Most of the changes required to make the libraries CLS compliant are not even
visible in the public interface.
Release builds
Starting with the 1.4 version we are shipping Release builds of the DLLs.
Code formatting changes
In response to popular demand the code base has been reformatted using the
default Visual Studio C# code formatting settings. We have also adopted
the convention of prefixing instance field names with a single "_" and static
fields names with a double "__" (while this convention for static fields is
not common it is very useful). One of the nice benefits of these conventions
is that the drop down menu in Visual Studio that displays class members ends
up grouping all static fields first, followed by instance fields, followed by
the rest of the properties and methods.
BSON library changes
ArraySerializationOptions
This new class allows you to specify serialization options for array-like
members. Initially the only option available is to specify serialization
options for the items of the array. When using attributes to specify
serialization options any attributes that don't apply to the collection as a
whole implictly apply to the items of the collection.
BsonDateTime is now a pure BSON DateTime value
In previous versions the BsonDateTime class stored its value twice in two
different private fields: _millisecondsSinceEpoch (a long) and _value (a .NET
DateTime). The idea was that you could store a .NET DateTime without losing any
precision. However, that turns out to be confusing because as soon as you save
the BsonDateTime value to the database and read it back you are going to lose
precision anyway, so you might as well lose it right up front and not make
false promises.
BsonDateTime also has two new helper methods: ToLocalTime and ToUniversalTime.
These methods convert the BSON DateTime to either local or UTC .NET DateTime
values. There are also new AsLocalTime and AsUniversalTime properties in
BsonValues that can be used to convert BsonValues to .NET DateTime values (like
all AsXyz properties in BsonValue they throw an InvalidCastException if the
BsonValue is not actually a BsonDateTime).
BsonIgnoreExtraElements attribute
The BsonIgnoreExtraElements attribute has a new property called Inherited. If
this property is set to true then all classes derived from this one will
automatically inherit this setting, which makes it easy to set it for an
entire class hierarchy at once.
BsonIgnoreIfDefault attribute
This new attribute allows you to specify that you want a field to be ignored
during serialization if it is equal to the default value. This replaces the
SerializeDefaultValue parameter of the BsonDefaultValue attribute. By making
this a separate attribute you can specify that you want the default value
ignored without having to specify the default value as well.
BsonReader: CurrentBsonType vs GetCurrentBsonType
In previous versions the CurrentBsonType property had side effects. In general
it is bad form for the get accessor of a property to have side effects, as even
something as simple as looking at the value of the property in a debugger can
have unintended consequences. Therefore, in the 1.4 release the CurrentBsonType
property has no side effects. The previous behavior is now implemented in the
GetCurrentBsonType method. While this is mostly an internal change, if you
have written a custom serializer that used the CurrentBsonType property and
were relying on its side effects you will have to change your custom serializer
to call GetCurrentBsonType instead.
ConventionProfile new conventions
The ConventionProfile class has two new conventions: IgnoreIfDefaultConvention
and SerializationOptionsConvention. Also, the SerializeDefaultValueConvention
has been obsoleted in favor of the new IgnoreIfDefaultConvention.
DictionarySerializationOptions
This class has a new property called ItemSerializationOptions that can be used
to specify the options to use when serializing the value of the items in the
dictionary. When using attributes to specify serialization options, any
attributes that don't apply to the dictionary as a whole implicitly apply to
the value of the items in the dictionary.
ExtraElements
Previous versions of the C# driver allowed you to specify a field of the class
to be used to store any extra elements encountered during deserialization.
However, this field had to be of type BsonDocument, which meant introducing
a dependency on the driver into your data model classes (which some developers
don't want to do). You now have the additional option of declaring your
ExtraElements field to be of type IDictionary<string, object> instead.
IBsonSerializationOptions
The IBsonSerializationOptions has several new methods. ApplyAttribute is used
during the AutoMap process to apply an attribute to some serialization options
that are being built incrementally (starting from the default serialization
options). This provides an extensible mechanism for applying new attributes to
new serialization options classes. The Clone and Freeze methods are introduced
to allow serialization options to be converted to read-only once initialization
is complete to provide thread safety.
IBsonSerializer
The IBsonSerializer has several new methods. GetDefaultSerializationOptions
provides an initial set of serialization options that any serialization
attributes found can be applied against. GetItemSerializationInfo provides
serialization info about the items and applies only to serializers for
collection-like classes. GetMemberSerializationInfo provides serialization
info about members of a class. The last two are used in the implementation
of LINQ queries.
Image/Bitmap serializers
New serializers have been provided for the Image abstract base class and the
Bitmap class derived from it.
ISupportInitialize
The ISupportInitialize interface defines two methods: BeginInit and EndInit.
The BsonClassMapSerializer now checks whether the class being deserialized
implements this interface, and if so, calls BeginInit just before it starts
to deserialize a class, and EndInit just after it has finished. You can
use this feature to do any pre- or post-processing.
ObjectId/BsonObjectId creation
ObjectId (and BsonObjectId) have a new constructor that allows you to supply
the timestamp as a .NET DateTime value and it will automatically be converted
to seconds since the Unix Epoch. These new constructors are useful if you want
to create artificial ObjectIds to use in range based ObjectId queries (in
which case you will usually set the machine, pid and increment fields to zero).
There are also two new overloads of GenerateNewId that allow you to provide
the desired timestamp as either an int or a .NET DateTime. These new overloads
are useful if you need to create backdated ObjectIds. When generating backdated
ObjectIds there is a slight risk that you might create an ObjectId that is
not unique (but that risk is very small).
TimeSpanSerializationOptions
You can now choose any of the following representations for a TimeSpan: string,
double, Int32 or Int64. In addition, when using any of the numeric
representations, you can use the Units property to choose the units that the
numeric value is in (choose from: Ticks, Days, Hours, Minutes, Seconds,
Milliseconds and Nanoseconds).
Driver changes
Authentication support improved
Operations that require admin credentials previously required you to set the
DefaultCredentials of MongoServerSetttings to admin credentials. But that is
undesirable because it provides the client code full access to all databases,
essentially negating the benefit of using authentication in the first place.
In the 1.4 release all operations that require admin credentials have a new
overload where you can provide the needed credentials; you no longer have to
set the DefaultCredentials. Another option is to store credentials for the
admin database in the new MongoCredentialsStore.
Connection pool defaults changed
The default value of WaitQueueMultiple has been changed from 1.0 to 5.0 and the
default value of WaitQueueTimeout has been changed from 0.5 seconds to 2
minutes. These new values are taken from the Java driver, ...