connect.txt

.. _csharp-connect-to-mongodb:

================
Connection Guide
================

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: connection string, URI, server, Atlas, settings
   :description: Connect to a MongoDB instance or replica set using the .NET/C# Driver by configuring a connection URI or `MongoClientSettings` for various deployment types.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

This guide shows you how to connect to a MongoDB instance or replica set
deployment using the {+driver-short+}.

.. _csharp_connection_uri:

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:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - 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
       :ref:`csharp-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``: 

.. literalinclude:: /includes/fundamentals/code-examples/connection/LocalConnection.cs
   :language: csharp
   :start-after: // start local connection
   :end-before: // end local connection

.. 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 :ref:`FAQ page
   <csharp-faq-connection-pool>`.

See :manual:`the MongoDB Manual </reference/connection-string>` 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``:

.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettings.cs
   :language: csharp
   :dedent:
   :start-after: // start mongo client settings
   :end-before: // end mongo client 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 :ref:`{+stable-api+} page
<csharp-stable-api>`.

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:

.. literalinclude:: /includes/fundamentals/code-examples/connection/AtlasConnection.cs
   :language: csharp
   :start-after: // start atlas connection
   :end-before: // end atlas connection

.. tip::

   Follow the :atlas:`Atlas driver connection guide </driver-connection?tck=docs_driver_nodejs>`
   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``:

.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
   :language: csharp
   :start-after: // start replica set connection
   :end-before: // end replica set connection

.. note:: Replica Set in Docker

   .. sharedinclude:: dbx/docker-replica-set.rst