Connection Guide
On this page
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; // Connection URI const string connectionUri = "mongodb://localhost:27017"; // Create a new client and connect 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; // Create a MongoClientSettings object var settings = new MongoClientSettings() { Scheme = ConnectionStringScheme.MongoDB, Server = new MongoServerAddress("localhost", 27017) }; // Create a new client and connect 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); // Set the ServerApi field of the settings object to Stable API version 1 settings.ServerApi = new ServerApi(ServerApiVersion.V1); // Create a new client and connect to the server var client = new MongoClient(settings); // Send 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 thedirectConnection
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; // Connection URI const string connectionUri = "mongodb://sample.host1:27017/?replicaSet=sampleRS"; // Create a new client and connect to the server var client = new MongoClient(connectionUri);