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.
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.
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.)
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.
Starting with the 1.4 version we are shipping Release builds of the DLLs.
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.
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.
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).
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.
This new attribute allows you to specify that you want a field to be ignored during serialization if it has 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.
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.
The ConventionProfile class has two new conventions: IgnoreIfDefaultConvention and SerializationOptionsConvention. Also, the SerializeDefaultValueConvention has been obsoleted in favor of the new IgnoreIfDefaultConvention.
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.
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.
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.
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.
New serializers have been provided for the Image abstract base class and the Bitmap class derived from it.
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 value, and EndInit just after it has finished. You can use this feature to do any pre- or post-processing.
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.
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).
Operations that require admin credentials previously required you to set the DefaultCredentials of MongoServerSettting 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.
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, where they have reportedly been working well for users running under heavy loads. These new values mean that many more threads can be waiting for a lot longer time before a timeout occurs and an exception is thrown.
Wherever possible exception handling code that used to use catch exceptions and rethrow them after processing them has been changed to roughly equivalent code that uses try/finally to accomplish the same objective. This is specially helpful if you are running the debugger set to stop whenever an exception is thrown.
The LINQ support relies heavily on the new methods added to IBsonSerializer. Because of this it is highly encouraged that in the future you always opt to write an IBsonSerializer for your class instead of having it implement IBsonSerializable (see the notes for MongoDBRef and SystemProfileInfo for examples of where the driver itself has switched from IBsonSerializable to using a IBsonSerializer). IBsonSerializable still has a modest role to play in classes that just need to be serialized quickly and simply and for which we won't be writing LINQ queries (for example, the driver's Builders and Wrappers still use IBsonSerializable).
As mentioned earlier in the release notes more information about the new support for LINQ queries can be found in the forthcoming LINQ tutorial:
http://www.mongodb.org/display/DOCS/CSharp+Driver+LINQ+Tutorial
A number of locking issues related to connection pooling have been resolved. These issues were particularly likely to occur if you had more threads than the maximum size of the connection pool and were using the connections heavily enough that the connection pool could be used up.
You can now create a credentials store which contains credentials for multiple databases (the name of the database is the key and the credentials are the value). The credentials store must be set up (in the MongoServerSettings) before you call MongoServer.Create, so it is only intended for scenarios where you have a fixed set of credentials that aren't going to change at runtime.
MongoDBRef used to handle its own serialization by virtue of implementing IBsonSerializable. But the IBsonSerializable interface is not helpful when we try to add support for writing LINQ queries against components of a MongoDBRef. Instead, there is now a MongoDBRefSerializer which handles serialization of MongoDBRefs, while at the same time implementing GetMemberSerializationInfo which enables the LINQ implementation to support LINQ queries against MongoDBRefs.
The constructors for MongoInsertOptions and MongoUpdateOptions used to require that the collection be passed in as a parameter. The purpose was to allow the constructor to inherit some of the options from the collection settings. To the developer however, this was awkward, as it required providing the collection where it seemed to be redundant. By handling default values in a different way we no longer require the collection to be supplied to the constructors. The old constructors (that require the collection parameter) are still temporarily supported but have been marked as deprecated with a warning.
The following Admin properties and methods have been removed from MongoServer: AdminDatabase, GetAdminDatabase, RunAdminCommand, and RunAdminCommandAs. The reason for removing them is that many developers would never use them anyway, and adding new overloads for providing admin credentials would have resulted in even more of these rarely used properties and methods. If you were using any of these methods or properties they can easily be replaced with calls to methods of an instance of MongoDatabase (use one of the overloads of GetDatabase with "admin" as the database to get a reference to the admin database).
Recall that the purpose of RequestStart is to tell the driver that a series of operations should all be done using the same connection (which in the case of a replica set also implies using the same member of the connection set). Which member of a replica set was chosen depended on the slaveOk parameter: a value of false meant that the primary had to be used, and a value of true meant that an arbitrary secondary would be used. A new overload of RequestStart now allows the caller to specify which member should be used, which can be very useful for implementing custom query routing algorithms or for querying specific members of a replica set. In general though, keep in mind that you should not be using RequestStart unless you have an unusual scenario which requires it.
The default value for SocketTimeout has been changed from 30 seconds to 0, which is a special value meaning to use the operating system default value, which in turn is infinity. If you actually wanted a SocketTimeout you now have to set it yourself. The SocketTimeout is currently a server setting, but most likely in a future release it will be possible to set it at the individual operation level.
See the notes for MongoDBRef. SystemProfileInfo no longer implements IBsonSerializable for the same reasons, and there is a new SystemProfileInfoSerializer instead.