{"id":81370,"date":"2018-10-24T20:02:08","date_gmt":"2018-10-24T20:02:08","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=81370"},"modified":"2026-03-06T13:14:21","modified_gmt":"2026-03-06T13:14:21","slug":"how-to-program-with-mongodb-using-the-net-driver","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/development\/dotnet-development\/how-to-program-with-mongodb-using-the-net-driver\/","title":{"rendered":"MongoDB .NET Driver Guide: CRUD, LINQ & Aggregation"},"content":{"rendered":"\n

The MongoDB .NET driver lets you connect to MongoDB from C# applications, map BSON documents to CLR types, and perform CRUD operations using both the native MongoDB API and LINQ syntax. If you\u2019re coming from SQL Server, the key mental shift is from tables and rows to collections and documents – but the .NET driver makes this transition easier by supporting familiar patterns like strongly-typed queries and LINQ expressions. This guide walks through environment setup, connection configuration, BSON type mapping, CRUD operations, aggregation pipelines, and authentication, with SQL-to-MongoDB comparisons throughout.<\/p>\n\n\n\n

Getting started<\/h2>\n\n\n\n

Many people that have a background in relational databases are confused with the terms NoSQL and the document database<\/em>. What kind of documents are in the database and how to get data without the query language, without SQL? In my opinion, the term NoSQL does not mean that there is no schema, rather than the schema is not strictly enforced. And, of course, there is a query language as well.<\/p>\n\n\n\n

During the past few years, JSON has become extremely popular. Getting data from various forms (i.e., WEB and WIN forms) became extremely easy using JSON. Furthermore, saving such data as users entered them dictates the shape of the data. The shape of the data is determined by the application itself, unlike a relational database in which the data are independent of the application. In NoSQL databases, the data are saved in the JSON document. The table record in the relational world is equivalent to the JSON document in the NoSQL world.<\/p>\n\n\n\n

I think that it is easier to learn something new by comparing with something that you already know. This article will try to be a gentle introduction to the NoSQL world and will explain how to transform part of a well-known database, AdventureWorks2016, to NoSQL as shown in the image below.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

<\/p>\n\n\n\n

For this article, I had to choose between MongoDB and Cosmos DB. Both databases provide challenges and opportunities, but, in my opinion, MongoDB has an advantage. It provides more free options than Cosmos DB. Furthermore, MongoDB is a multiplatform database with an on-premise edition that is much richer than the Cosmos DB Emulator.<\/p>\n\n\n\n

Let\u2019s get started. The first step is to set up the environment. This means installing the MongoDB database, installing the NET driver, and importing some data.<\/p>\n\n\n\n

Setting up the environment<\/h2>\n\n\n\n

At the time of this writing, October 2018, the current version of MongoDB in 4.0.2, and the current version of the .NET driver is 2.7. To install MongoDB, start with a Google search for \u2018Mongo DB download\u2019 or click on the link<\/a>. From the list of available platforms, choose Windows x64. Then fill in the form with your first and last name, e-mail address, and so on. After that, save the MSI installation file locally.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

<\/p>\n\n\n\n

The installation is straightforward. MongoDB will be installed as a Windows service by default. You have the option of choosing the service name, the service user, and startup folders for data and log files, as shown in the image below.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

<\/p>\n\n\n\n

If you choose the Custom<\/strong> installation option, you may specify an installation directory. The MongoDB installation will put the executables in C:\\Program Files\\MongoDB\\Server\\4.0\\bin<\/em> folder by default. Be sure to add this path to your PATH<\/em> environment variable to be able to run the MongoDB shell from any folder in the command prompt.<\/p>\n\n\n\n

Feel free to explore executables installed in the folder. The most important is mongod<\/code> the windows service itself, mongo<\/code> the shell and mongoimport<\/code>, a utility that helps import various data in the database. You should also install the MongoDB GUI explorer called Compass from the link<\/a>.<\/p>\n\n\n\n

The next step in setting the environment is to install the NET driver. To do that, start Visual Studio. I\u2019m using the VS 2017 Community Edition in this article.<\/p>\n\n\n\n

Create a new console project using C#, and name it as you wish. The purpose of creating a new project is to show you how to reference the MongoDB .NET driver. From the project context menu, choose Manage NuGet Packages<\/em>. After NuGet Package Manager<\/em> appears, enter MongoDB driver<\/em> in the Browse<\/em> tab as shown in the image below.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

<\/p>\n\n\n\n

Choose and install MongoDB.Driver<\/em>, and the three main components for programming MongoDB by using .NET are installed. All three are published together, as shown by version number, in the image below.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

<\/p>\n\n\n\n

MongoDB.Bson<\/strong> handles various types and-file formats as well as the mapping between CLR types to BSon. BSon is MongoDB representation of JSON. I will write much more about BSon later.<\/p>\n\n\n\n

MongoDB.Driver.Core<\/strong> handles connection pooling, communication between clients and database and so on. Usually, there is no need to work with this library directly.<\/p>\n\n\n\n

MongoDB.Driver<\/strong> is where the main API is located.<\/p>\n\n\n\n

Once you download the three main libraries, you can start any new project and copy references from this first project. At this point, you can save and close this first project.<\/p>\n\n\n\n

Read also:<\/strong> JSON handling in SQL Server<\/a><\/p>\n\n\n\n

In order to follow the article, please, download the article solution from the GitHub<\/a>. Open the solution by starting another instance of Visual Studio. In the solution notice the folder Data<\/em> as shown in the image below.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

<\/p>\n\n\n\n

The folder contains three JSON files that must be imported by using a MongoDB command line utility called mongoimport<\/code>. Determine where on your local disk those three files are located. Start the command prompt from that location. In the command prompt window, execute the following three commands.<\/p>\n\n\n\n

mongoimport --db simpleTalk --collection adventureWorks2016 --file sales.json --jsonArray\n \nmongoimport --db simpleTalk --collection spetialOffer --file SpetailOffer.json --jsonArray\n \nmongoimport --db simpleTalk --collection products --file Product.json --jsonArray<\/pre>\n\n\n\n
By executing these commands, you will create a MongoDB database named simpleTalk<\/em> (camel case naming) and three collections named: adventureWorks2016<\/em>, specialOffer<\/em>, and product<\/em> as shown in the image below from Compass. When starting Compass, it tries to establish a connection on localhost port 27017. Just press Connect<\/em> and, on the left side, select the database simpleTalk<\/em>.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
The collection in NoSQL is similar to the table in the SQL world and provides a namespace for the document. To prove that the import was successful, start the mongo shell from the command prompt. In the command prompt, type mongo<\/code> to enter into the shell.<\/p>\n\n\n\n
Once you enter the shell, type use simpleTalk<\/em> to switch in the context of the database. And then type show collections<\/em> and you will be able to see all three imported collections.<\/p>\n\n\n\n
To conclude this first section, notice the Authentication folder in the article’s solution. Inside the folder, there is a JavaScript file named AddUser.js<\/em>. If you are not in the mongo shell, start it again. In the context of the simpleTalk<\/em> database, execute the code of AddUser.js<\/em>, as shown in the snippet below, to create a user.<\/p>\n\n\n\n
db.createUser(\n{\n   user: \"usrSimpleTalk\",\n   pwd: \"pwdSimpleTalk\",\n   roles: [{ role: \"readWrite\", db: \"simpleTalk\" }]\n}\n)<\/pre>\n\n\n\n
All examples in the article will execute in the context of this newly created user usrSimpleTalk<\/em>. The user has been granted read and write permissions to the database.<\/p>\n\n\n\n
Now it\u2019s time to talk about how to connect to the MongoDB database, how CLR types are mapped to BSon types, and the root objects in the MongoDB .NET driver.<\/p>\n\n\n\n
How to connect to MongoDB<\/h2>\n\n\n\n
The purpose of this section is to provide information on how to connect to the MongoDB database and to examine the most important objects of MongoDB API for .NET. Those objects are the MongoDB client, the Mongo database, and the Mongo collection. Open the article solution and make sure that the startup object is Auth<\/em> as shown in the image below.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
The class named Auth<\/code> demonstrates how to connect to the MongoDB database. MongoClient<\/code> is the root object that provides that connectivity.<\/p>\n\n\n\n
There are several various methods to connect to the database. The first way is to pass the database name, the username, and the password, as shown in the snippet below.<\/p>\n\n\n\n
var credential =MongoCredential.CreateCredential(databaseName: Dbase, username: UserName, password: Password);\n \nvar settings = new MongoClientSettings\n{\n    Credential = credential\n};\n \nvar mongoClient = new MongoClient(settings);<\/pre>\n\n\n\n
As you may have noticed by browsing the code, there is no need for opening, closing and disposing of connections. The client object is cheap, and the connection is automatically disposed of, unlike ADO.NET in which the connection is a very expensive resource. This approach is shown in the solution. In the solution, there is one configuration object located in the Configuration<\/em> folder and named SampleConfig<\/em>.<\/p>\n\n\n\n
Read also:<\/strong> Dapper for SQL Server data access in .NET<\/a><\/p>\n\n\n\n
The MongoClient<\/code> has many overloads. The most common way to instantiate the client is to pass a connection string, as shown in the snippet below.<\/p>\n\n\n\n
\/\/Using connectionString\nvar connectionString = $\"mongodb:\/\/{UserName}:{Passwrod}@localhost:27017\/{Dbase}\";\n \nmongoClient = new MongoClient(connectionString);<\/pre>\n\n\n\n
By default, MongoDB API uses port 27017 to communicate with the database, but there are many more options. That includes connecting to multiple servers, the replica sets and so on.<\/p>\n\n\n\n
At this point, I have to make a digression. One common thing that I would like to know is the number of currently opened connection. By using the mongo shell, it is possible to see that number but without further information.<\/p>\n\n\n\n
If you execute in the mongo shell command db.serverStatus().connections<\/code>, you will see the response in the form of a document, as shown in the image below.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
The only way to get more information is to use netstat \u2013b<\/code> in the cmd window with elevated permissions and getting the result as displayed on the image below.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
Let\u2019s get back to the main topic. Down in the object hierarchy is the database object. To get a reference to the database, usually, you execute the following snippet.<\/p>\n\n\n\n
var db = mongoClient.GetDatabase($\"{Dbase}\");<\/pre>\n\n\n\n
The database is accessed in the context of the client. If you explore the exposed method in the client, you will notice that there are no options for creating a database. That is because the database is created automatically when it is needed and if it doesn\u2019t exist.<\/p>\n\n\n\n
In the context of the database, you can get a reference to the collection by executing snippet like shown below.<\/p>\n\n\n\n
var collection = db.GetCollection<SalesHeader>($\"{Collection}\");<\/pre>\n\n\n\n
or like this one<\/p>\n\n\n\n
 var collection = db.GetCollection<BsonDocument>($\"{Collection}\");<\/pre>\n\n\n\n
In the context of the database, you can create, drop, or rename a collection. There is a method to create a collection, but there is no need to use it because the collection will be created automatically if does not exist. The collection and the database object are both thread safe and could be instantiated once and used globally.<\/p>\n\n\n\n
As you noticed in the snippets above, the only difference in getting a reference to a collection object is by passing a type. This is the type needed in .NET to work with the collection. One is a BsonDocument<\/code> that represents a dynamic schema in which you can use any document shape, and one is a so-called strongly typed schema named SalesHeader<\/code>. As you will discover in the article, SalesHeader is the class that mimics the table in the AdventureWorks2016<\/em> database named Sales.SalesHeader<\/em>. The option that is strongly typed is the generally preferred way when working with MongoDB in .NET.<\/p>\n\n\n\n
The document object is found lower in the object hierarchy. The most general way to represent the document is to use the BSonDocument <\/code>class. The BsonDocument is basically a dictionary of keys (strings) and BsonValues<\/code>. BsonValues<\/code> will be examined in the next section. To conclude this section, F5 to start the article’s solution. The result will display on the console screen. It represents the number of documents in the adventureWorks2016<\/code> collection, and it is determined by calling the collections method CountDocumentsAsync<\/code>.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
How to map CLR types to BSON types<\/h2>\n\n\n\n
Change the startup object in order to follow this section. This time set Attribute Decoration<\/em> located in the Serialization<\/em> folder as the startup object. In the section, I will refer to a couple of simple classes which definitions can be found in the Pocos<\/em> folder POCO is an acronym for \u2018plain old CLR object\u2019 and represents a class that is unencumbered by inheritance.<\/p>\n\n\n\n
The first example uses two objects. The first one is of type TestSerializerWithOutAttributes<\/code>, the second one of type TestSerializer<\/code>. Both classes define the same properties of type bool, string, int, double<\/code> and datetime<\/code>. The classes\u2019 definitions can be found in TestSerializer.cs<\/em> located in the Pocos<\/em> folder. The only difference between these two classes is that the second class has been decorated with attributes. In the example, I instantiate two objects and perform the basic serialization by using ToJson<\/code>, as shown in the image below.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
By pressing F5, the result will be displayed as shown in the image below.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
As you will notice, there are a couple of differences. One of them is that decimal type, by default, is displayed as a string. It must be decorated decimal type by attribute [BsonRepresentation(BsonType.Decimal128)],<\/code> as is done in the definition of class TestSerializer<\/code>.<\/p>\n\n\n\n
Then, if you noticed, the property OnlyDate<\/code> is set by using the following snippet<\/p>\n\n\n\n
OnlyDate = new DateTime (DateTime.Now.Year, DateTime.Now.Month, DateTime.Now.Day),<\/pre>\n\n\n\n
Therefore, there is no time part. I am located in the UTC +1h time zone, and because it\u2019s currently daylight savings time, the default serializer reduces the date value by two hours. To avoid such behavior, I decorated, the property with the attribute [BsonDateTimeOptions(DateOnly =true)].<\/code><\/p>\n\n\n\n
In the example, I am using some other attributes, which I\u2019ll describe. If you would like to change the element name or specify a different order, try decorating the property with BsonElement<\/code> as shown in the snippet below.<\/p>\n\n\n\n
[BsonElement(\"description\", Order= 1)]\nPublic string Comment { get; set; }<\/pre>\n\n\n\n
As you\u2019ll see later, every BsonDocument<\/code> that is part of a collection should have an element named _id<\/code>. This is a kind of primary key in the NoSQL-Bson world. Also, by default, the collection is indexed by using this field. You are free to specify your own primary key by decorating a property or field in the class definition with the attribute BsonId<\/code>, as shown in the snippet below.<\/p>\n\n\n\n
[BsonId]\npublic int SalesOrderId { get; set; }<\/pre>\n\n\n\n
Finally, in order to specify that only a significant number of digits will be used when working with the double type, the following attribute is used:<\/p>\n\n\n\n
\/\/ Double decorated with AllowTruncation \n[BsonRepresentation(BsonType.Double, AllowTruncation = true), BsonElement(\"myduble\")]\npublic double MongoValueTypeDouble { get; set; }<\/pre>\n\n\n\n
You probably noticed that I use the word the default serializer, although in the code there is no call to any kind of serializer. This is because of the beautiful .ToJson<\/code> extension. As you can see by using the Visual Studio peek definition<\/em> or by pressing ALT + F12, ToJson<\/code> is an extension of the object type defined in the MongoDB.Bson<\/code> namespace. So, it should be safely used on any type.<\/p>\n\n\n\n
There is one thing about ToJson<\/code> I have to write about at this spot. As you probably noticed, the extension optionally receives a parameter of type JsonWriterSettings<\/code>. <\/strong><\/p>\n\n\n\n
If you examine this class by using the Visual Studio peek definition<\/em>, you will notice that the class has properties defined as shown in the image below.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
You can pay special attention to the property outputMode<\/code>, as shown surrounded by red on the image above. This is an enumerator with two possible values. The default one is JsonOutputMode.Shell<\/code> and the second one is JsonOutputMode.Strict<\/code>. So, what is the difference? According to the MongoDB documentation<\/a> :<\/p>\n\n\n
\n