⭐Introduction

♥ Welcome to the MongoDB C# driver docs! ♥

ℹ️ About the docs

MongoDB has been evolved rapidly over the years 💪 attracting more and more developers from different languages and backgrounds. While there are official MongoDB drivers for different programming languages, many developers struggle to solve their problems based on each driver's reference or API.

These MongoDB C# driver docs have been created for one purpose only - to bridge the gap between MongoDB and C# developers 👏. You will find numerous samples solving problems all developers facing on a daily basis.

MongoDB for C# developers

These docs don't intend to replace the official MongoDB C# Driver reference, their purpose is to act as a complementary reference. Also, the C# samples in the MongoDB docs are written using BsonDocument which is not ideal for C# developers

❓ How to read the docs

It depends on what your are looking for. In case your are dealing for the first time with MongoDB using the C# driver, then you should definitely read the entire Getting Started section.

pageEnvironment setup

On the other hand, in case you already have some experience with the driver and you simply want to find a sample that may help you solve your problem, just search for it.

✨ Samples

All pages contain some introductory theory to get the reader on the right context. For all samples the solutions are presented in 3 different ways:

• Using the C# driver in typed manner

• Using the C# driver with BsonDocument which is a schema-less way to build MongoDB queries

• Using the pure MongoDB shell commands

This way you can always compare the shell commands with the .NET code used.

The main goal of the docs is to teach you how to use the C# driver in a typed way using your C# class models and avoiding the generic BsonDocument. While you can easily build any MongoDB query you want with the schema-less way, it's way too ugly plus you will face problems when changing/renaming your model properties, thus it's not recommended.

The code for solving a specific case looks like this:

C#

// get a collection reference
var collection = database
    .GetCollection<User>(collectionName);
    
// 1st filter definition (equality)
var maleFilter = Builders<User>.Filter
    .Eq(u => u.Gender, Gender.Male);

// 2nd filter definition (equality)    
var doctorFilter = Builders<User>.Filter
    .Eq(u => u.Profession, "Doctor");

// combine filters    
var maleDoctorsFilter = Builders<User>
    .Filter.And(maleFilter, doctorFilter);

// get results
var maleDoctors = await collection
    .Find(maleDoctorsFilter).ToListAsync();

Bson

var bsonCollection = database
    .GetCollection<BsonDocument>(collectionName);
    
var bsonMaleFilter = Builders<BsonDocument>
    .Filter.Eq("gender", Gender.Male);
    
var bsonDoctorFilter = Builders<BsonDocument>
    .Filter.Eq("profession", "Doctor");
    
var bsonMaleDoctorsFilter = Builders<BsonDocument>
    .Filter.And(bsonMaleFilter, bsonDoctorFilter);
    
var bsonMaleDoctors = await bsonCollection
    .Find(bsonMaleDoctorsFilter).ToListAsync();

Shell

db.users.find({
    $and: [{
        profession:
            { $eq: "Doctor" }
    },
    { gender: { $eq: 0 } }]
})

----------------------------

// sample result

/* 1 */
{
	"_id" : ObjectId("5e9d578781f29c3b1c22d756"),
	"gender" : 0,
	"firstName" : "John",
	"lastName" : "Pouros",
	"userName" : "John.Pouros",
	"avatar" : "https://s3.amazonaws.com/uifaces/faces/twitter/axel/128.jpg",
	"email" : "[e-mail]",
	"dateOfBirth" : ISODate("1999-12-26T02:49:38.625+02:00"),
	"address" : {
		"street" : "3493 Beer Unions",
		"suite" : "Apt. 435",
		"city" : "West Ewell",
		"state" : "Massachusetts",
		"zipCode" : "93115",
		"geo" : {
			"lat" : 21.9856,
			"lng" : 136.1137
		}
	},
	"phone" : "1-938-915-9412",
	"website" : "thad.biz",
	"company" : {
		"name" : "Carroll, Kutch and Harber",
		"catchPhrase" : "User-centric 4th generation core",
		"bs" : "innovate rich users"
	},
	"salary" : 4853,
	"monthlyExpenses" : 4742,
	"favoriteSports" : [
		"Ice Hockey"
	],
	"profession" : "Doctor"
}

Models

public class User
{
    [BsonId]
    [BsonIgnoreIfDefault] // required for replace documents 
    public ObjectId Id { get; set; }
    public Gender Gender { get; set; }
    public string FirstName {get; set; }
    public string LastName {get; set; }
    public string UserName {get; set; }
    public string Avatar {get; set; }
    public string Email {get; set; }
    public DateTime DateOfBirth {get; set; }
    public AddressCard Address {get; set; }
    public string Phone {get; set; }
    
    [BsonIgnoreIfDefault]
    public string Website {get; set; }
    public CompanyCard Company {get; set; }
    public decimal Salary { get; set; }
    public int MonthlyExpenses { get; set; }
    public List<string> FavoriteSports { get; set; }
    public string Profession { get; set; }
}

As you can see, the solution is presented in 3 different ways. If any other code snippet will be required, it will be added in a new tab.

• The C# tab contains the typed way of querying MongoDB

• The Bson tab contains the code using BsonDocument

• The Shell contains the code you would write directly in a MongoDB shell, followed by sample results. This tab may also include some documents directly from the database to get an idea of their schema

Other than these tabs, samples might also contain result documents or the C# class models used in the queries

Repository

All samples of the docs are part of the mongodb-csharp repository. Each sample is fully isolated and can be tested as long you have setup a local MongoDB server. Also, docs` structure matches the solution's file and folder structure so that you can easily spot and run the sample you are interested in. What sample runs when you fire the console app, depends on what sample is activated in the appsettings.json file.

part of appsetttings.json

{
  "Samples": {
    "QuickStart_AccessDatabases": false,
    "QuickStart_AccessCollections": false,
    "QuickStart_InsertDocuments": false,
    "QuickStart_ReadDocuments": false,
    "QuickStart_UpdateDocuments": false,
    "QuickStart_DeleteDocuments": false,
    "Crud_Insert_OrderedInsert": true, // this sample will fire
    "Crud_Insert_WriteConcern": false,
    "Crud_Read_Basics": false,
    "Crud_Read_Query_ComparisonOperators": false,
    "Crud_Read_Query_LogicalOperators": false,
    "Crud_Read_Query_ElementOperators": false,
    "Crud_Read_Query_EvaluationOperators": false,
    "Crud_Read_Query_ArrayOperators": false,
    "Crud_Update_BasicOperators": false,
    "Crud_Update_ReplaceDocuments": false,
    "Crud_Update_UpdatingArrays": false,
    "Aggregation_Stages_Match": false,
    "Aggregation_Stages_Group": false,
    "Aggregation_Stages_Projection": false,
    "Aggregation_Stages_Unwind": false,
    "Aggregation_Stages_Bucket": false,
    "Aggregation_Stages_Limit_Skip": false
  }
}

According to the above configuration when the app fires, the samples that will run are inside the OrderedInsert.cs file in the Crud/Insert folder.

Avoid running multiple samples simultaneously 🚫 . Each sample usually starts with dropping the database to be used and adding a banch of documents (sometimes 500 documents) to a collection.

👨‍💻 How to contribute

The docs are being updated 🔃 as soon as new samples are available or new MongoDB driver's features are released. Contribution is highly welcomed as long as it fulfills the following criteria:

• Request a new sample: You can open a new issue at the repository's issues page, as long as there isn't a related one already. Make sure you have done your search either in the docs or the source code before opening the issue. Last but not least, add some sample data to explain exactly what you are looking for.

Issue title

The issue's title for new samples should have the format Request sample - <short-description>, for example Request sample - add array element