Connection String

The connection string is the simplest way to connect to one or more MongoDB servers. A connection string mostly follows RFC 3986 with the exception of the domain name. For MongoDB, it is possible to list multiple domain names separated by a comma. Below are some example connection strings

• For a standalone mongod, mongos, or a direct connection to a member of a replica set:

  mongodb://host:27017
  

• To connect to multiple mongos or a replica set:

  mongodb://host1:27017,host2:27017
  

The authentication guide contains information on how to provide credentials.

The Database Component

The database component is optional and is used to indicate which database to authenticate against. When the database component is not provided, the “admin” database is used.

mongodb://host:27017/mydb

Above, the database by the name of “mydb” is where the credentials are stored for the application.

Options

Many options can be provided via the connection string. The ones that cannot may be provided in a MongoClientSettings object. To provide an option on the connection string, append a ? and separate multiple options by an &.

mongodb://host:27017/?replicaSet=rs0&uuidRepresentation=standard

The above connection string sets the replicaSet value to rs0 and the uuidRepresentation to standard.

For a comprehensive list of the available options, see the MongoDB connection string documentation.

Mongo Client

A MongoClient object will be the root object. It is thread-safe and is all that is needed to handle connecting to servers, monitoring servers, and performing operations against those servers. Without any arguments, constructing a MongoClient instance will connect to “localhost” port 27017.

var client = new MongoClient();

Alternatively, a connection string may be provided:

var client = new MongoClient("mongodb://host:27017,host2:27017/?replicaSet=rs0");

Finally, MongoClientSettings provides an in code way to set the same options.

var settings = new MongoClientSettings { ReplicaSetName = "rs0" };
var client = new MongoClient(settings);

Low-Level Customization

There are a number of settings that are not configurable directly from MongoClientSettings. These settings are able to be configured through the ClusterConfigurator property which provides a ClusterBuilder to manipulate. An example of these is adding a logger using the eventing infrastructure.

Re-use

It is recommended to store a MongoClient instance in a global place, either as a static variable or in an IoC container with a singleton lifetime.

However, multiple MongoClient instances created with the same settings will utilize the same connection pools underneath. Unfortunately, certain types of settings are not able to be compared for equality. For instance, the ClusterConfigurator property is a delegate and only its address is known for comparison. If you wish to construct multiple MongoClients, ensure that your delegates are all using the same address if the intent is to share connection pools.

Monitoring

MongoClient utilizes an ICluster from MongoDB.Driver.Core which handles monitoring the cluster.

Mongo Database

An IMongoDatabase represents a database in a MongoDB server. Databases are retrieved from an IMongoClient instance using the GetDatabase method:

var db = client.GetDatabase("hr");

Above, we have gotten the “hr” database. If the database does not exist on the server, it will be created automatically upon first use. If you want to use more than one database, call GetDatabase once for each database you’d like to work with.

Re-use

The implementation of IMongoDatabase provided by a MongoClient is thread-safe and is safe to be stored globally or in an IoC container.

Mongo Collection

An IMongoCollection<TDocument> represents a collection in a MongoDB database. Collections are retrieved from an IMongoDatabase with the GetCollection<TDocument> method:

var collection = db.GetCollection<BsonDocument>("people");

Above, we have gotten the “people” collection. If the collection does not exist on the server, it will be created automatically upon first use. If you want to use more than one database, call GetCollection<TDocument> once for each database you’d like to work with.

The generic parameter TDocument is the type of document that is stored in your collection. It can, effectively, be any type that can be mapped to and from BSON. The driver utilizes the BSON library to handle this mapping. The most common types you will use are:

1. Custom Class - useful for representing known schemas. See the mapping section for more information. The majority of applications will not work with dynamic schemas, but rather with something more rigid. In addition, if you work in a static language, it is nice to work with static types that provide compile time type checking.
2. BsonDocument - useful for representing dynamic schemas.

A majority of the methods and extension methods for an IMongoCollection<TDocument> utilize the TDocument generic parameter in some fashion.

Re-use

The implementation of IMongoCollection<TDocument> ultimately provided by a MongoClient is thread-safe and is safe to be stored globally or in an IoC container.

Server API

Starting from version 5.0 MongoDB servers support specifying API compatibility version. See Stable API.