Skip to content

Commit 0f307ac

Browse files
mcmorisimcmorisi
committed
DOCSP-49054: Connection targets
1 parent 3f2c2ae commit 0f307ac

File tree

5 files changed

+203
-60
lines changed

5 files changed

+203
-60
lines changed

‎source/connect/connection-options/server-selection.txt

+6
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
.. _csharp-server-selection:
2+
3+
==========================
4+
Customize Server Selection
5+
==========================
6+
17
.. TODO: Server Selection page
28

39
Why Does the Driver Throw a Timeout During Server Selection?

‎source/connect/connection-targets.txt

+168
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
.. _csharp-connection-targets:
2+
3+
==========================
4+
Choose a Connection Target
5+
==========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings, client, load balancing, srv, dns
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use a connection string and ``MongoClient`` object
24+
to connect to different types of MongoDB deployments.
25+
26+
Atlas
27+
-----
28+
29+
To connect to a MongoDB deployment on Atlas, include the following elements
30+
in your connection string:
31+
32+
- URL of your Atlas cluster
33+
- MongoDB username
34+
- MongoDB password
35+
36+
Then, pass your connection string to the ``MongoClient`` constructor.
37+
38+
.. tip::
39+
40+
Follow the :atlas:`Atlas driver connection guide </driver-connection?tck=docs_driver_python>`
41+
to retrieve your connection string.
42+
43+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
44+
breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
45+
To learn more about the {+stable-api+} feature, see the :ref:`<csharp-stable-api>` guide.
46+
47+
The following code shows how to use {+driver-short+} to connect to an Atlas cluster. The
48+
code also uses the ``server_api`` option to specify a {+stable-api+} version.
49+
50+
.. literalinclude:: /includes/fundamentals/code-examples/connection/AtlasConnection.cs
51+
:language: csharp
52+
:start-after: // start atlas connection
53+
:end-before: // end atlas connection
54+
55+
Local Deployments
56+
-----------------
57+
58+
To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
59+
default, the ``mongod`` process runs on port 27017, though you can customize this for
60+
your deployment.
61+
62+
The following code shows how to use {+driver-short+} to connect to a local MongoDB
63+
deployment:
64+
65+
.. literalinclude:: /includes/fundamentals/code-examples/connection/LocalConnection.cs
66+
:language: csharp
67+
:start-after: // start local connection
68+
:end-before: // end local connection
69+
70+
Replica Sets
71+
------------
72+
73+
To connect to a replica set, specify the hostnames (or IP addresses) and
74+
port numbers of the replica-set members in your connection string.
75+
76+
The following code shows how to use {+driver-short+} to connect to a replica set
77+
that contains three hosts:
78+
79+
.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
80+
:language: csharp
81+
:start-after: // start-replica-set-connection-list
82+
:end-before: // end-replica-set-connection-list
83+
84+
If you aren't able to provide a full list of hosts in the replica set, you can
85+
specify one or more of the hosts in the replica set and instruct {+driver-short+} to
86+
perform automatic discovery to find the others. To instruct the driver to perform
87+
automatic discovery, perform one of the following actions:
88+
89+
- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
90+
- Specify ``false`` as the value of the ``directConnection`` parameter.
91+
- Specify more than one host in the replica set.
92+
93+
In the following example, the driver uses a sample connection URI to connect to the
94+
MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different
95+
hosts, including ``host1``. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous`
96+
tab to see the corresponding code:
97+
98+
.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
99+
:language: csharp
100+
:start-after: // start-replica-set-connection-rs-name
101+
:end-before: // end-replica-set-connection-rs-name
102+
103+
The {+driver-short+} evenly load balances operations across deployments that are reachable
104+
within the client's ``localThresholdMS`` value. To learn more about how the {+driver-short+} load
105+
balances operations across multiple MongoDB deployments, see the
106+
:ref:`csharp-server-selection` guide.
107+
108+
.. note::
109+
110+
The ``MongoClient`` constructor is *non-blocking*.
111+
When you connect to a replica set, the constructor returns immediately while the
112+
client uses background threads to connect to the replica set.
113+
114+
If you construct a ``MongoClient`` and immediately print the string representation
115+
of its ``nodes`` attribute, the list might be empty while the client connects to
116+
the replica-set members.
117+
118+
Initialization
119+
~~~~~~~~~~~~~~
120+
121+
To initialize a replica set, you must connect directly to a single member. To do so,
122+
set the ``directConnection`` connection
123+
option to ``True``. You can do this in two ways: by passing an argument to the
124+
``MongoClient`` constructor or through a parameter in your connection string. Select the
125+
:guilabel:`MongoClientSettings` or :guilabel:`Connection String` tab to see the corresponding code.
126+
127+
.. tabs::
128+
129+
.. tab:: MongoClientSettings
130+
:tabid: settings
131+
132+
.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
133+
:language: csharp
134+
:start-after: // start-replica-set-direct-connection-settings
135+
:end-before: // end-replica-set-direct-connection-settings
136+
137+
.. tab:: Connection String
138+
:tabid: connection-string
139+
140+
.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
141+
:language: csharp
142+
:start-after: // start-replica-set-direct-connection-string
143+
:end-before: // end-replica-set-direct-connection-string
144+
145+
DNS Service Discovery
146+
---------------------
147+
148+
To use DNS service discovery to look up the DNS SRV record of the service you're connecting to,
149+
specify the SRV connection format in your connection string. Additionally, if you enable
150+
the SRV connection format, {+driver-short+} automatically re-scans for new hosts without
151+
having to change the client configuration.
152+
153+
The following code shows a connection string that uses the SRV connection format:
154+
155+
.. code-block:: csharp
156+
157+
var uri = "mongodb+srv://<hostname>"
158+
159+
To learn more about the SRV connection format, see the :manual:`SRV Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`
160+
entry in the {+mdb-server+} manual.
161+
162+
API Documentation
163+
-----------------
164+
165+
To learn more about the types discussed in this guide, see the following API documentation:
166+
167+
- `MongoClient <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClient.html>`__
168+
- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__

‎source/connect/mongoclient.txt

-57
Original file line numberDiff line numberDiff line change
@@ -98,60 +98,3 @@ MongoDB instance on port ``27017`` of ``localhost``:
9898
:dedent:
9999
:start-after: // start mongo client settings
100100
:end-before: // end mongo client settings
101-
102-
Other Connection Targets
103-
------------------------
104-
105-
Connect to Atlas
106-
~~~~~~~~~~~~~~~~
107-
108-
To connect to a MongoDB deployment on Atlas, create a client. You can
109-
create a client that uses your connection string and other
110-
client options by passing a ``MongoClientSettings`` object to the ``MongoClient``
111-
constructor.
112-
113-
To specify your connection URI, pass it to the ``FromConnectionString()``
114-
method, which returns a new ``MongoClientSettings`` instance. To specify any other
115-
client options, set the relevant fields of the ``MongoClientSettings`` object.
116-
117-
You can set the {+stable-api+} version as a client option to avoid
118-
breaking changes when you upgrade to a new server version. To
119-
learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page
120-
<csharp-stable-api>`.
121-
122-
The following code shows how you can specify the connection string and
123-
the {+stable-api+} client option when connecting to a MongoDB
124-
deployment and verify that the connection is successful:
125-
126-
.. literalinclude:: /includes/fundamentals/code-examples/connection/AtlasConnection.cs
127-
:language: csharp
128-
:start-after: // start atlas connection
129-
:end-before: // end atlas connection
130-
131-
.. tip::
132-
133-
Follow the :atlas:`Atlas driver connection guide </driver-connection?tck=docs_driver_nodejs>`
134-
to retrieve your connection string.
135-
136-
Connect to a Replica Set
137-
~~~~~~~~~~~~~~~~~~~~~~~~
138-
139-
To connect to a replica set deployment, specify the hostnames (or IP addresses) and
140-
port numbers of the members of the replica set.
141-
142-
If you aren't able to provide a full list of hosts in the replica set, you can
143-
specify one or more of the hosts in the replica set and instruct the driver to
144-
perform automatic discovery in one of the following ways:
145-
146-
- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
147-
- Specify ``false`` as the value of the ``directConnection`` parameter.
148-
- Specify more than one host in the replica set.
149-
150-
In the following example, the driver uses a sample connection URI to connect to the
151-
MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different
152-
hosts, including ``sample.host1``:
153-
154-
.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
155-
:language: csharp
156-
:start-after: // start replica set connection
157-
:end-before: // end replica set connection

‎source/includes/fundamentals/code-examples/connection/ConnectionTargets.cs

Whitespace-only changes.

‎source/includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs

+29-3
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,37 @@
11
// Connects to a specific replica set by using a URI
22

3-
// start replica set connection
3+
// start-replica-set-connection-rs-name
44
using MongoDB.Driver;
55

66
// Sets the connection URI than includes the replica set name
7-
const string connectionUri = "mongodb://sample.host1:27017/?replicaSet=sampleRS";
7+
const string connectionUri = "mongodb://host1:27017/?replicaSet=sampleRS";
88

99
// Creates a new client and connects to the server
1010
var client = new MongoClient(connectionUri);
11-
// end replica set connection
11+
// end-replica-set-connection-rs-name
12+
13+
// start-replica-set-connection-list
14+
using MongoDB.Driver;
15+
16+
// Sets the connection URI than includes the replica set name
17+
const string connectionUri = "mongodb://host1:27017,host2:27017,host3:27017";
18+
19+
// Creates a new client and connects to the server
20+
var client = new MongoClient(connectionUri);
21+
// end-replica-set-connection-list
22+
23+
// start-replica-set-direct-connection-string
24+
using MongoDB.Driver;
25+
26+
const string connectionUri = "mongodb://host1:27017/?directConnection=true";
27+
var client = new MongoClient(connectionUri);
28+
// end-replica-set-direct-connection-string
29+
30+
// start-replica-set-direct-connection-settings
31+
using MongoDB.Driver;
32+
33+
var settings = MongoClientSettings.FromConnectionString("mongodb://host1:27017");
34+
settings.DirectConnection = true;
35+
var client = new MongoClient(settings);
36+
// end-replica-set-direct-connection-settings
37+

0 commit comments

Comments
 (0)