Connection Guide

On this page

Connection URI

MongoClientSettings
Other Connection Targets
Connect to Atlas
Connect to a Replica Set

This guide shows you how to connect to a MongoDB instance or replica set deployment using the .NET/C# Driver.

Connection URI

A connection URI, also known as a connection string, tells the driver how to connect to a MongoDB deployment and how to behave while connected.

A standard connection string includes the following pieces:

Piece	Description
`mongodb://`	Required. A prefix that identifies this as a string in the standard connection format.
`username:password@`	Optional. Authentication credentials. If you include these, the client will authenticate the user against the database specified in `authSource`.
`host[:port]`	Required. The host and optional port number where MongoDB is running. If you don't include the port number, the driver will use the default port, `27017`.
`/defaultauthdb`	Optional. The authentication database to use if the connection string includes `username:password@` authentication credentials but not the `authSource` option. If you don't include this piece, the client will authenticate the user against the `admin` database.
`?<options>`	Optional. A query string that specifies connection-specific options as `<name>=<value>` pairs. See Connection Options for a full description of these options.

To use a connection URI, pass it as a string to the MongoClient constructor. In the following example, the driver uses a sample connection URI to connect to a MongoDB instance on port 27017 of localhost:

using MongoDB.Driver;
// Sets the connection URI
const string connectionUri = "mongodb://localhost:27017";
// Creates a new client and connects to the server
var client = new MongoClient(connectionUri);

Tip

Reuse Your Client

Because each MongoClient represents a pool of connections to the database, most applications require only a single instance of MongoClient, even across multiple requests. To learn more about how connection pools work in the driver, see the FAQ page.

See the MongoDB Manual for more information about creating a connection string.

MongoClientSettings

You can use a MongoClientSettings object to configure the connection in code rather than in a connection URI. To use a MongoClientSettings object, create an instance of the class and pass it as an argument to the MongoClient constructor.

In the following example, the driver uses a MongoClientSettings object to connect to a MongoDB instance on port 27017 of localhost:

using MongoDB.Driver;
// Creates a MongoClientSettings object
var settings = new MongoClientSettings()
{
    Scheme = ConnectionStringScheme.MongoDB,
    Server = new MongoServerAddress("localhost", 27017)
};
// Creates a new client and connects to the server
var client = new MongoClient(settings);

Other Connection Targets

Connect to Atlas

To connect to a MongoDB deployment on Atlas, create a client. You can create a client that uses your connection string and other client options by passing a MongoClientSettings object to the MongoClient constructor.

To specify your connection URI, pass it to the FromConnectionString() method, which returns a new MongoClientSettings instance. To specify any other client options, set the relevant fields of the MongoClientSettings object.

You can set the Stable API version as a client option to avoid breaking changes when you upgrade to a new server version. To learn more about the Stable API feature, see the Stable API page.

The following code shows how you can specify the connection string and the Stable API client option when connecting to a MongoDB deployment and verify that the connection is successful:

using MongoDB.Driver;
using MongoDB.Bson;
// Replace the placeholder with your Atlas connection string
const string connectionUri = "<connection string>";
var settings = MongoClientSettings.FromConnectionString(connectionUri);
// Sets the ServerApi field of the settings object to Stable API version 1
settings.ServerApi = new ServerApi(ServerApiVersion.V1);
// Creates a new client and connects to the server
var client = new MongoClient(settings);
// Sends a ping to confirm a successful connection
try {
    var result = client.GetDatabase("admin").RunCommand<BsonDocument>(new BsonDocument("ping", 1));
    Console.WriteLine("Pinged your deployment. You successfully connected to MongoDB!");
} catch (Exception ex) { Console.WriteLine(ex);}

Tip

Follow the Atlas driver connection guide to retrieve your connection string.

Connect to a Replica Set

To connect to a replica set deployment, specify the hostnames (or IP addresses) and port numbers of the members of the replica set.

If you aren't able to provide a full list of hosts in the replica set, you can specify one or more of the hosts in the replica set and instruct the driver to perform automatic discovery in one of the following ways:

Specify the name of the replica set as the value of the replicaSet parameter.
Specify false as the value of the directConnection parameter.
Specify more than one host in the replica set.

In the following example, the driver uses a sample connection URI to connect to the MongoDB replica set sampleRS, which is running on port 27017 of three different hosts, including sample.host1:

using MongoDB.Driver;
// Sets the connection URI than includes the replica set name
const string connectionUri = "mongodb://sample.host1:27017/?replicaSet=sampleRS";
// Creates a new client and connects to the server
var client = new MongoClient(connectionUri);

Back

Connection

Connection Options