Introducing the 2.0 .NET Driver

< View all blog posts
MongoDB & Robert Stam
April 02, 2015
Category: Company

The .NET driver team is pleased to announce the release of the 2.0 version of the .NET driver.

This is a major release that introduces two main features: async support and a new API. Async has been one of the most requested features for a long time, and given recent advances in the C# language and the .NET Framework to support async, this is a great time to be introducing async support. Other documentation will cover the new API in more detail, but we will give a few examples in this blog post.

The new API is part of a coordinated effort across all drivers to increase the consistency of the API across the drivers. Less publicly visible are many lower level changes to standardize how drivers discover and monitor cluster configuration and state.

Async support

The most important feature of the 2.0 version of the .NET driver is the introduction of an async API. Async programming is a key technique for implementing server applications that use resources more efficiently and user interfaces that don't block. There has been a trend recently for new APIs to be provided in async-only form and the new API of the 2.0 version of the .NET driver is an async-only API.

Not only is the API async on the surface, the driver is 100% async down to the lowest level.

New API

The introduction of async support has provided an opportunity to introduce a new streamlined API that is more consistent with other drivers. The new API is based on three top level interfaces: IMongoClient, IMongoDatabase and IMongoCollection.

The typical pattern is for an application to create a single MongoClient instance, call GetDatabase to get a IMongoDatabase instance, and finally call GetCollection on the database object to get a IMongoCollection instance. Most operations will be performed using an IMongoCollection instance but a few operations are provided at the IMongoClient or IMongoDatabase level.

The new IMongoCollection interface has far fewer methods than the legacy API MongoCollection class, making it much easier to use. One way this was accomplished was by using Options classes for optional parameters so that we don’t need multiple overloads of methods just to provide different combinations of parameters. Another way this was accomplished was by introducing a fluent API for the two most commonly used operations, Find and Aggregate.

While this blog post is not intended as a tutorial, sample code is the best way to give you a feel for what the new API looks like. Your initialization code will look something like this:

To insert a single document using the new async API you would write:

InsertOneAsync returns a Task with no result value. When the insert is completed the Task will be in either a completed or faulted state depending on whether the insert was successful.

To find a small number of documents that match some filter you would write:

If your query returns a large number of documents, you should process them in a stream instead of converting them to a giant list. For example:

Just as the driver is 100% async, your application should be 100% async also, so in the above example the documents are processed asynchronously.

.NET Framework versions

Earlier versions of the driver required .NET Framework 3.5 or above. The 2.0 version of the driver requires .NET Framework 4.5 or above. We have also released a 1.10 version of the driver that only requires .NET Framework 3.5 that can be used on an interim basis if for some reason you are unable to migrate to .NET Framework 4.5 at this time. However, only the 2.0 version of the driver contains the new async API.

Legacy API support

The 2.0 driver has a new async API. To facilitate migrating to the new API, the 2.0 driver continues to support almost all of the legacy API. You can mix using the legacy API with the new API in the same program.

To use the legacy API write this:

Instead of this:

One caveat is that the synchronous legacy API in 2.0 is implemented by calling the low level async API and blocking, waiting for the Task to complete. This is not considered a performant way to use async APIs, so for performance-sensitive code you may prefer to use the 1.10 version of the driver until you are ready to convert your application to use the new async API.

Closing Remarks

We are excited to be making version 2.0 of the .NET driver available, and we are looking for feedback from the community.

For more information consult our online documentation.


If you’re interested in learning more about the architecture of MongoDB, read our guide:

Read the Architecture Guide


About the Author - Robert Stem

Robert has been using .NET since its earliest days. At MongoDB Robert works on the .NET driver. Before joining MongoDB Robert worked in many different sectors of the industry, including communications, internet advertising and health care, using a variety of platforms and programming languages. Outside of work, Robert enjoys cycling and hiking.

comments powered by Disqus