From fce0fe56303af1650fe139c9a7ab444856fd2b0f Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 28 Apr 2025 15:15:26 -0400 Subject: [PATCH 1/5] DOCSP-49053: Standardize MongoClient page --- source/connect/mongoclient.txt | 143 +++++++++++++-------------------- 1 file changed, 55 insertions(+), 88 deletions(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 99dbfde5..33b322e2 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -11,6 +11,7 @@ Create a MongoClient .. meta:: :keywords: connection string, URI, server, Atlas, settings + :description: Learn how to create a `MongoClient` to connect to a MongoDB deployment using a connection URI and customize connection behavior. .. contents:: On this page :local: @@ -21,20 +22,32 @@ Create a MongoClient This guide shows you how to connect to a MongoDB instance or replica set deployment by using the {+driver-short+}. -.. _csharp_connection_uri: +Overview +-------- + +To connect to a MongoDB deployment, you need two things: + +- A **connection URI**, also known as a *connection string*, which tells the {+driver-short+} + which MongoDB deployment to connect to. +- A **MongoClient** object, which creates the connection to the MongoDB deployment + and lets you perform operations on it. + +You can also use either of these components to customize the way {+driver-short+} behaves +while connected to MongoDB. + +This guide shows you how to create a connection URI and use a ``MongoClient`` object +to connect to MongoDB. 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: +A standard connection URI includes the following components: .. list-table:: :widths: 20 80 :header-rows: 1 - * - Piece + * - Component - Description * - ``mongodb://`` @@ -42,20 +55,24 @@ A standard connection string includes the following pieces: - Required. A prefix that identifies this as a string in the standard connection format. - * - ``username:password@`` + * - ``username:password`` - - Optional. Authentication credentials. If you include these, the client will authenticate the user against the database specified in ``authSource``. + - Optional. Authentication credentials. If you include these, the client + authenticates the user against the database specified in ``authSource``. + For more information about authentication settings, see + :ref:`csharp-authentication-mechanisms`. * - ``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``. + - Required. The host and optional port number where MongoDB is running. If you don't + include the port number, the driver uses 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. + this component, the client authenticates the user against the ``admin`` database. * - ``?`` @@ -64,94 +81,44 @@ A standard connection string includes the following pieces: :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 - `. - -See :manual:`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``: - -.. 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. +For more information about creating a connection string, see +:manual:`Connection Strings ` in the +MongoDB Server documentation. -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. +MongoClient +----------- -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 -`. +To create a connection to MongoDB, pass a connection URI to the +``MongoClient`` constructor. In the following example, the driver uses a sample +connection URI to connect to a MongoDB deployment running on port ``27017`` of ``localhost``:abbreviation: -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: +.. code-block:: csharp -.. literalinclude:: /includes/fundamentals/code-examples/connection/AtlasConnection.cs - :language: csharp - :start-after: // start atlas connection - :end-before: // end atlas connection + const string connectionUri = "mongodb://localhost:27017/"; + var client = new MongoClient(connectionUri); -.. tip:: +Configuring the MongoClient +--------------------------- - Follow the :atlas:`Atlas driver connection guide ` - to retrieve your connection string. +You can configure settings for the ``MongoClient`` object by passing a +``MongoClientSettings`` object to the constructor. The following example creates a +``MongoClient`` object and sets the ``UseTls`` property to ``true``: -Connect to a Replica Set -~~~~~~~~~~~~~~~~~~~~~~~~ +.. code-block:: csharp -To connect to a replica set deployment, specify the hostnames (or IP addresses) and -port numbers of the members of the replica set. + var mongoClientSettings = MongoClientSettings.FromConnectionString("mongodb://localhost:27017/"); + mongoClientSettings.UseTls = true; + var client = new MongoClient(mongoClientSettings); -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: +For a full list of the settings you can configure, see the +`MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`_ +API documentation. -- 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. +API Documentation +----------------- -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``: +To learn more about creating a ``MongoClient`` object with the {+driver-short+}, +see the following API documentation: -.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs - :language: csharp - :start-after: // start replica set connection - :end-before: // end replica set connection +- `MongoClient <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClient.html>`__ +- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__ From 9c18c99b38462d513ebedb57449a808215a96036 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 28 Apr 2025 15:22:10 -0400 Subject: [PATCH 2/5] Fix spacing --- source/connect/mongoclient.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 33b322e2..65ddfaf1 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -106,7 +106,8 @@ You can configure settings for the ``MongoClient`` object by passing a .. code-block:: csharp - var mongoClientSettings = MongoClientSettings.FromConnectionString("mongodb://localhost:27017/"); + var mongoClientSettings = MongoClientSettings + .FromConnectionString("mongodb://localhost:27017/"); mongoClientSettings.UseTls = true; var client = new MongoClient(mongoClientSettings); From 1503c83ed99e6a9922765c21a6c43ef30dbe0a91 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 28 Apr 2025 15:22:23 -0400 Subject: [PATCH 3/5] Fix --- source/connect/mongoclient.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 65ddfaf1..a718e194 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -107,7 +107,7 @@ You can configure settings for the ``MongoClient`` object by passing a .. code-block:: csharp var mongoClientSettings = MongoClientSettings - .FromConnectionString("mongodb://localhost:27017/"); + .FromConnectionString("mongodb://localhost:27017/"); mongoClientSettings.UseTls = true; var client = new MongoClient(mongoClientSettings); From 7942d08cdbfba9c19433394531e01f8f8ec0d57b Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 29 Apr 2025 10:27:58 -0400 Subject: [PATCH 4/5] RR feedback --- source/connect/mongoclient.txt | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index a718e194..5970975b 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -11,7 +11,7 @@ Create a MongoClient .. meta:: :keywords: connection string, URI, server, Atlas, settings - :description: Learn how to create a `MongoClient` to connect to a MongoDB deployment using a connection URI and customize connection behavior. + :description: Learn how to create a MongoClient to connect to a MongoDB deployment URI and customize connection behavior. .. contents:: On this page :local: @@ -25,15 +25,15 @@ deployment by using the {+driver-short+}. Overview -------- -To connect to a MongoDB deployment, you need two things: +Connecting to a MongoDB deployment requires the following components: -- A **connection URI**, also known as a *connection string*, which tells the {+driver-short+} +- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+} which MongoDB deployment to connect to. -- A **MongoClient** object, which creates the connection to the MongoDB deployment - and lets you perform operations on it. +- **MongoClient** object, which creates and sustains the connection to the MongoDB deployment + and lets you perform data operations. -You can also use either of these components to customize the way {+driver-short+} behaves -while connected to MongoDB. +You can also specify connection settings in either of these components to customize the way +the {+driver-short+} behaves while connected to MongoDB. This guide shows you how to create a connection URI and use a ``MongoClient`` object to connect to MongoDB. @@ -65,7 +65,7 @@ A standard connection URI includes the following components: * - ``host[:port]`` - Required. The host and optional port number where MongoDB is running. If you don't - include the port number, the driver uses the default port, ``27017``. + include the port number, the driver uses the default port ``27017``. * - ``/defaultauthdb`` @@ -90,15 +90,15 @@ MongoClient To create a connection to MongoDB, pass a connection URI to the ``MongoClient`` constructor. In the following example, the driver uses a sample -connection URI to connect to a MongoDB deployment running on port ``27017`` of ``localhost``:abbreviation: +connection URI to connect to a MongoDB deployment running on port ``27017`` of ``localhost``: .. code-block:: csharp - const string connectionUri = "mongodb://localhost:27017/"; - var client = new MongoClient(connectionUri); + const string uri = "mongodb://localhost:27017/"; + var client = new MongoClient(uri); -Configuring the MongoClient ---------------------------- +Configure the MongoClient +------------------------- You can configure settings for the ``MongoClient`` object by passing a ``MongoClientSettings`` object to the constructor. The following example creates a @@ -108,12 +108,11 @@ You can configure settings for the ``MongoClient`` object by passing a var mongoClientSettings = MongoClientSettings .FromConnectionString("mongodb://localhost:27017/"); - mongoClientSettings.UseTls = true; + .UseTls = true; var client = new MongoClient(mongoClientSettings); For a full list of the settings you can configure, see the -`MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`_ -API documentation. +:ref:`csharp-connection-options` guide. API Documentation ----------------- From b34ba7c00a8231b098b7f86437f83faeba1d39b0 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 30 Apr 2025 10:13:36 -0400 Subject: [PATCH 5/5] RR feedback 2 --- source/connect/mongoclient.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 5970975b..b2bdff0f 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -106,12 +106,11 @@ You can configure settings for the ``MongoClient`` object by passing a .. code-block:: csharp - var mongoClientSettings = MongoClientSettings - .FromConnectionString("mongodb://localhost:27017/"); - .UseTls = true; - var client = new MongoClient(mongoClientSettings); + var connectionString = "mongodb://localhost:27017/" + var settings = MongoClientSettings.FromConnectionString(connectionString); + settings.UseTls = true; -For a full list of the settings you can configure, see the +To view a full list of the settings you can configure, see the :ref:`csharp-connection-options` guide. API Documentation