The C# Driver Version 3.0 is Here! What Do You Need to Know?
Rate this article
We have exciting news! For the first time in eight years, the MongoDB C# Driver has had a major version update. So to celebrate the release of 3.0, let’s take a look at some of the things you need to know, and some examples of exciting features and changes.
You can view the upgrade guide in our documentation to see how to move from 2.X to 3.0. We also have a section in the documentation on what’s new in 3.0.
The C# Driver team has put a lot of love and time into this release and it addresses a lot of tech debt and technical features. Below is a list of a few things that are good to know about this release.
As a developer using the driver, you may not even realize this but as of an earlier minor release of the driver, it was split into two layers known as “high” and “core.” High is essentially a client of core and what is currently exposed to users. However, it has since become clear that core does not need to be public, so they have been merged into one assembly. This is all part of the tech debt the team wanted to address for 3.0.
LINQ has been on version 3 for a while now, so with the release of 3.0, the driver now supports V3 as standard and V2 has been removed. Previously, before V2.19, you would have to explicitly specify the use of V3 through a
MongoClientSettings object.Now, you do not need to use this and instead will get the benefits of V3 without having to specify it.
If you have scenarios where you are storing files that exceed the 16MB document limit, you may have found yourself using the GridFS package. This was previously a separate library but is now available out of the box with 3.0!
MongoDB supports GUID as a data type and in many MongoDB collections, GUID fields in a document use the same type under the hood,
BsonBinaryData. In the documentation , it explains the different GuidRepresentationMode property values that handle the different subtypes of GUID that can be found in older collections.In summary, V2 assumes that all GUIDs use the same BsonBinaryData subtype. This is the default in the C# driver 2.X. In V3, fields in the same document can use different GUID formats and representation is configured at the property level using the serializer.
As of the 3.0 driver release, V3 will become the default and support for V2 will be removed.
There are also changes to the default behavior of the GUID serializer which will now handle GUIDs by default as
GuidReprensentation.Unspecified. This is to encourage being explicit about the GuidRepresentation type being used.Currently, the best practice advice for the usage of
MongoClient is to give it a singleton lifetime scope. However, some issues were seen which require per-instance scope as lifetime scope was causing excessive memory usage and undisposed resources.Now, an experimental feature has been introduced where a new MongoClient implements
IDisposable which means that the class and any classes that implement the IMongoClient interface have access to a Dispose() method. Once disposed, any member connections will result in a ObjectDisposedExceptionHowever, calling Dispose will not dispose of the cluster and the underlying connections, for this you will still need to call
ClusterRegistry.UnregisterAndDisposeCluster().This new 3.0 release brings a lot of improvements to date- and time-related things. Don’t worry, we won’t be getting into a debate about time zones!
First up is things around including or excluding date or time. In .NET 6 (released back in 2021), two new types were introduced called DateOnly and TimeOnly, which remove the need for a time or a date, depending on the type. This means we don’t have to make up a time like we had to do previously—for example, when it was only the date that mattered.
3.0 now supports these types on your model classes!
Historically, the driver has serialized
DateTimeOffset as BSON arrays. This has now changed so that the default behavior is that under the hood, they are serialized as BSON documents.If you want to return to the previous behavior, you can add the
[BsonRepresentation(BsonType.Array)] attribute to the property in your model.Previously,
decimal and decimal128 were serialized as BSON string values. This meant having to do some manual extra code to treat it as a decimal in your code.
In 3.0, this has been changed so that by default, it is stored as Decimal128 values.There is an option to continue to use string if you prefer, though. Just add the attribute
[BsonRepresentation(BsonType.String)] to your property.There have also been changes to the BulkWrite API as part of the release of 3.0. These are aimed at improving developer experience by changing how it works and what it can be applied to.
Developers have been able to perform bulk write operations using
BulkWrite() or BulkWriteAsync() for a while now, but this was only able to perform these operations on one collection at a time. Plus, it could only be done for a single write type, such as a batch of inserts, deletions, etc. You could still provide a mix of types to the call, but under the hood the driver would separate them out, leading to multiple database calls which isn't the most efficient as this leads to multiple round-trip calls. This meant that BulkWrite calls took much longer.This has been changed as of 3.0. You can now perform multiple write operations, such as update or delete, with a single database call via the BulkWrite API.
You now use a
BulkWriteModelclass that comes in the form of:BulkWriteInsertOneModel<TDocument>BulkWriteUpdateOneModel<TDocument>BulkWriteUpdateManyModel<TDocument>BulkWriteReplaceOneModel<TDocument>BulkWriteDeleteOneModel<TDocument>BulkWriteDeleteManyModel<TDocument>
You can replace TDocument with your POCO model class too. Be sure to visit the BulkWrite documentation to see more information and sample code relating to this change.
For a while now, we have supported client-side field level encryption (CSFLE), which adds an extra layer of security by encrypting your data before it is sent over the network to MongoDB.
This was done using the MongoDB.LibMongocrypt library. However, in 3.0, this has been changed slightly. The base CSFLE functionality can now be found in MongoDB.Driver.Encryption.
There has also been a change with the AWS authentication package which now has its own package. This means if you don’t want the AWS authentication functionality, you no longer have that excess code hiding in your published app.
In fact, this refactoring and moving out into different packages has led to some interesting stats for those that enjoy data:
- In a simple CRUD application, the published folder size has gone from 38MB to 4MB!
- Removed about 32% of the public APIs
- Solution has six fewer projects, with 16 instead of 22
- Reduced from 663K lines of code to 555K—a whopping reduction of 16%!
- Removed about 200 .cs files
We have also deprecated the
MongoDB.Driver.Legacy package in 2.X. This was available in 2.X to ease people migrating from 1.X. However, the continued presence of the 1.X API is leading to more confusion than we would want. In 3.0, this has been removed altogether.How exciting! After eight years, we have a major release of the C# driver!
This article was just a teaser of some changes and things you should know. Of course, the best place to view all the latest and greatest is in our documentation.
Happy 3.0!
Top Comments in Forums
There are no comments on this article yet.