DOCSP-49054: Connection targets

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?

source/connect/connection-targets.txt

@@ -0,0 +1,167 @@
+.. _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 </driver-connection?tck=docs_driver_python>`
+   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:`<csharp-stable-api>` 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``:
+
+.. 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, 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:
+
+.. code-block:: csharp
+
+   var uri = "mongodb+srv://<hostname>"
+
+To learn more about the SRV connection format, see the :manual:`SRV Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`
+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>`__

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
-<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

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
+// 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
+