From 0f307acefee4ab0fbd32124ae33be566a4d4e301 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 11 Apr 2025 12:39:54 -0400 Subject: [PATCH 1/5] DOCSP-49054: Connection targets --- .../connection-options/server-selection.txt | 6 + source/connect/connection-targets.txt | 168 ++++++++++++++++++ source/connect/mongoclient.txt | 57 ------ .../connection/ConnectionTargets.cs | 0 .../connection/ReplicaSetConnection.cs | 32 +++- 5 files changed, 203 insertions(+), 60 deletions(-) create mode 100644 source/includes/fundamentals/code-examples/connection/ConnectionTargets.cs diff --git a/source/connect/connection-options/server-selection.txt b/source/connect/connection-options/server-selection.txt index 57772394..31a077cf 100644 --- a/source/connect/connection-options/server-selection.txt +++ b/source/connect/connection-options/server-selection.txt @@ -1,3 +1,9 @@ +.. _csharp-server-selection: + +========================== +Customize Server Selection +========================== + .. TODO: Server Selection page Why Does the Driver Throw a Timeout During Server Selection? diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index e69de29b..746fc1be 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -0,0 +1,168 @@ +.. _csharp-connection-targets: + +========================== +Choose a Connection Target +========================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, server, settings, client, load balancing, srv, dns + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use a connection string and ``MongoClient`` object +to connect to different types of MongoDB deployments. + +Atlas +----- + +To connect to a MongoDB deployment on Atlas, include the following elements +in your connection string: + +- URL of your Atlas cluster +- MongoDB username +- MongoDB password + +Then, pass your connection string to the ``MongoClient`` constructor. + +.. tip:: + + Follow the :atlas:`Atlas driver connection guide ` + to retrieve your connection string. + +When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid +breaking changes when Atlas upgrades to a new version of {+mdb-server+}. +To learn more about the {+stable-api+} feature, see the :ref:`` guide. + +The following code shows how to use {+driver-short+} to connect to an Atlas cluster. The +code also uses the ``server_api`` option to specify a {+stable-api+} version. + +.. literalinclude:: /includes/fundamentals/code-examples/connection/AtlasConnection.cs + :language: csharp + :start-after: // start atlas connection + :end-before: // end atlas connection + +Local Deployments +----------------- + +To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By +default, the ``mongod`` process runs on port 27017, though you can customize this for +your deployment. + +The following code shows how to use {+driver-short+} to connect to a local MongoDB +deployment: + +.. literalinclude:: /includes/fundamentals/code-examples/connection/LocalConnection.cs + :language: csharp + :start-after: // start local connection + :end-before: // end local connection + +Replica Sets +------------ + +To connect to a replica set, specify the hostnames (or IP addresses) and +port numbers of the replica-set members in your connection string. + +The following code shows how to use {+driver-short+} to connect to a replica set +that contains three hosts: + +.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs + :language: csharp + :start-after: // start-replica-set-connection-list + :end-before: // end-replica-set-connection-list + +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 {+driver-short+} to +perform automatic discovery to find the others. To instruct the driver to perform +automatic discovery, perform one of the following actions: + +- 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 ``host1``. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` +tab to see the corresponding code: + +.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs + :language: csharp + :start-after: // start-replica-set-connection-rs-name + :end-before: // end-replica-set-connection-rs-name + +The {+driver-short+} evenly load balances operations across deployments that are reachable +within the client's ``localThresholdMS`` value. To learn more about how the {+driver-short+} load +balances operations across multiple MongoDB deployments, see the +:ref:`csharp-server-selection` guide. + +.. note:: + + The ``MongoClient`` constructor is *non-blocking*. + When you connect to a replica set, the constructor returns immediately while the + client uses background threads to connect to the replica set. + + If you construct a ``MongoClient`` and immediately print the string representation + of its ``nodes`` attribute, the list might be empty while the client connects to + the replica-set members. + +Initialization +~~~~~~~~~~~~~~ + +To initialize a replica set, you must connect directly to a single member. To do so, +set the ``directConnection`` connection +option to ``True``. You can do this in two ways: by passing an argument to the +``MongoClient`` constructor or through a parameter in your connection string. Select the +:guilabel:`MongoClientSettings` or :guilabel:`Connection String` tab to see the corresponding code. + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: settings + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs + :language: csharp + :start-after: // start-replica-set-direct-connection-settings + :end-before: // end-replica-set-direct-connection-settings + + .. tab:: Connection String + :tabid: connection-string + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs + :language: csharp + :start-after: // start-replica-set-direct-connection-string + :end-before: // end-replica-set-direct-connection-string + +DNS Service Discovery +--------------------- + +To use DNS service discovery to look up the DNS SRV record of the service you're connecting to, +specify the SRV connection format in your connection string. Additionally, if you enable +the SRV connection format, {+driver-short+} automatically re-scans for new hosts without +having to change the client configuration. + +The following code shows a connection string that uses the SRV connection format: + +.. code-block:: csharp + + var uri = "mongodb+srv://" + +To learn more about the SRV connection format, see the :manual:`SRV Connection Format ` +entry in the {+mdb-server+} manual. + +API Documentation +----------------- + +To learn more about the types discussed in this guide, see the following API documentation: + +- `MongoClient <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClient.html>`__ +- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__ diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 99dbfde5..f97f42d6 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -98,60 +98,3 @@ MongoDB instance on port ``27017`` of ``localhost``: :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 -`. - -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 ` - 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 diff --git a/source/includes/fundamentals/code-examples/connection/ConnectionTargets.cs b/source/includes/fundamentals/code-examples/connection/ConnectionTargets.cs new file mode 100644 index 00000000..e69de29b diff --git a/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs b/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs index 46c53384..73093be3 100644 --- a/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs +++ b/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs @@ -1,11 +1,37 @@ // Connects to a specific replica set by using a URI -// start replica set connection +// start-replica-set-connection-rs-name using MongoDB.Driver; // Sets the connection URI than includes the replica set name -const string connectionUri = "mongodb://sample.host1:27017/?replicaSet=sampleRS"; +const string connectionUri = "mongodb://host1:27017/?replicaSet=sampleRS"; // Creates a new client and connects to the server var client = new MongoClient(connectionUri); -// end replica set connection \ No newline at end of file +// end-replica-set-connection-rs-name + +// start-replica-set-connection-list +using MongoDB.Driver; + +// Sets the connection URI than includes the replica set name +const string connectionUri = "mongodb://host1:27017,host2:27017,host3:27017"; + +// Creates a new client and connects to the server +var client = new MongoClient(connectionUri); +// end-replica-set-connection-list + +// start-replica-set-direct-connection-string +using MongoDB.Driver; + +const string connectionUri = "mongodb://host1:27017/?directConnection=true"; +var client = new MongoClient(connectionUri); +// end-replica-set-direct-connection-string + +// start-replica-set-direct-connection-settings +using MongoDB.Driver; + +var settings = MongoClientSettings.FromConnectionString("mongodb://host1:27017"); +settings.DirectConnection = true; +var client = new MongoClient(settings); +// end-replica-set-direct-connection-settings + From d07de201228ec103c734c42798c49fd27541928e Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 14 Apr 2025 09:05:46 -0400 Subject: [PATCH 2/5] SA feedback --- source/connect/connection-targets.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 746fc1be..e5d37daf 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -71,7 +71,7 @@ Replica Sets ------------ To connect to a replica set, specify the hostnames (or IP addresses) and -port numbers of the replica-set members in your connection string. +port numbers of the replica set members in your connection string. The following code shows how to use {+driver-short+} to connect to a replica set that contains three hosts: @@ -92,8 +92,7 @@ automatic discovery, perform one of the following actions: 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 ``host1``. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` -tab to see the corresponding code: +hosts, including ``host1``: .. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs :language: csharp @@ -113,14 +112,14 @@ balances operations across multiple MongoDB deployments, see the If you construct a ``MongoClient`` and immediately print the string representation of its ``nodes`` attribute, the list might be empty while the client connects to - the replica-set members. + the replica set members. Initialization ~~~~~~~~~~~~~~ To initialize a replica set, you must connect directly to a single member. To do so, set the ``directConnection`` connection -option to ``True``. You can do this in two ways: by passing an argument to the +option to ``true``. You can do this in two ways: by passing an argument to the ``MongoClient`` constructor or through a parameter in your connection string. Select the :guilabel:`MongoClientSettings` or :guilabel:`Connection String` tab to see the corresponding code. @@ -147,7 +146,7 @@ DNS Service Discovery To use DNS service discovery to look up the DNS SRV record of the service you're connecting to, specify the SRV connection format in your connection string. Additionally, if you enable -the SRV connection format, {+driver-short+} automatically re-scans for new hosts without +the SRV connection format, the {+driver-short+} automatically re-scans for new hosts without having to change the client configuration. The following code shows a connection string that uses the SRV connection format: From a2c3aa27a76aa3805a80f4c632b005ccfa918234 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 16 Apr 2025 09:31:43 -0400 Subject: [PATCH 3/5] Tech feedback --- .../code-examples/connection/ReplicaSetConnection.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs b/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs index 73093be3..8f253a49 100644 --- a/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs +++ b/source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs @@ -13,7 +13,7 @@ // start-replica-set-connection-list using MongoDB.Driver; -// Sets the connection URI than includes the replica set name +// Sets the connection URI than includes the list of hosts in the replica set const string connectionUri = "mongodb://host1:27017,host2:27017,host3:27017"; // Creates a new client and connects to the server From ad9b8c280e244da249414a37e85d595f2e790ceb Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 28 Apr 2025 10:07:46 -0400 Subject: [PATCH 4/5] Technical Feedback --- source/connect/connection-targets.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index e5d37daf..b5d2deb8 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -87,7 +87,8 @@ perform automatic discovery to find the others. To instruct the driver to perfor automatic discovery, perform one of the following actions: - Specify the name of the replica set as the value of the ``replicaSet`` parameter. -- Specify ``false`` as the value of the ``directConnection`` parameter. +- Specify ``false`` as the value of the ``directConnection`` parameter. You can also omit + this parameter, as it defaults to ``false``. - Specify more than one host in the replica set. In the following example, the driver uses a sample connection URI to connect to the @@ -114,13 +115,12 @@ balances operations across multiple MongoDB deployments, see the of its ``nodes`` attribute, the list might be empty while the client connects to the replica set members. -Initialization -~~~~~~~~~~~~~~ +Connect to a Single Server +~~~~~~~~~~~~~~~~~~~~~~~~~~ -To initialize a replica set, you must connect directly to a single member. To do so, -set the ``directConnection`` connection -option to ``true``. You can do this in two ways: by passing an argument to the -``MongoClient`` constructor or through a parameter in your connection string. Select the +To connect to a single server in a replica set rather than the entire replica set, specify +``false`` as the value of the ``directConnection`` connection option. You can do this in two ways: by passing +an argument to the ``MongoClient`` constructor or through a parameter in your connection string. Select the :guilabel:`MongoClientSettings` or :guilabel:`Connection String` tab to see the corresponding code. .. tabs:: From 302565c6af19b7ba56a20d72356438abdd30cc33 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 30 Apr 2025 11:24:24 -0400 Subject: [PATCH 5/5] Tech feedback 2 --- source/connect/connection-targets.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index b5d2deb8..4014c6b7 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -100,6 +100,13 @@ hosts, including ``host1``: :start-after: // start-replica-set-connection-rs-name :end-before: // end-replica-set-connection-rs-name +.. note:: Specifying the Replica Set Name + + Although the driver can automatically discover replica set members without specifying + the hostnames of all members or the replica set name, we recommend specifying the + replica set name to avoid corner cases where the replica set will not initialize + correctly. + The {+driver-short+} evenly load balances operations across deployments that are reachable within the client's ``localThresholdMS`` value. To learn more about how the {+driver-short+} load balances operations across multiple MongoDB deployments, see the