Skip to content

Commit 473761b

Browse files
mcmorisimcmorisi
authored
DOCSP-49054: Connection targets (#589)
1 parent 785a11c commit 473761b

File tree

5 files changed

+204
-61
lines changed

5 files changed

+204
-61
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,4 +192,4 @@ documentation:
192192
- `ClusterConfigurator <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.ClusterConfigurator.html>`__
193193
- `ServerSelectors <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Clusters.ServerSelectors.html>`__
194194
- `IServerSelector <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Clusters.ServerSelectors.IServerSelector.html>`__
195-
- `SelectServer() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Clusters.ServerSelectors.IServerSelector.SelectServers.html>`__
195+
- `SelectServer() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Clusters.ServerSelectors.IServerSelector.SelectServers.html>`__

‎source/connect/connection-targets.txt‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
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. You can also omit
91+
this parameter, as it defaults to ``false``.
92+
- Specify more than one host in the replica set.
93+
94+
In the following example, the driver uses a sample connection URI to connect to the
95+
MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different
96+
hosts, including ``host1``:
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+
.. note:: Specifying the Replica Set Name
104+
105+
Although the driver can automatically discover replica set members without specifying
106+
the hostnames of all members or the replica set name, we recommend specifying the
107+
replica set name to avoid corner cases where the replica set will not initialize
108+
correctly.
109+
110+
The {+driver-short+} evenly load balances operations across deployments that are reachable
111+
within the client's ``localThresholdMS`` value. To learn more about how the {+driver-short+} load
112+
balances operations across multiple MongoDB deployments, see the
113+
:ref:`csharp-server-selection` guide.
114+
115+
.. note::
116+
117+
The ``MongoClient`` constructor is *non-blocking*.
118+
When you connect to a replica set, the constructor returns immediately while the
119+
client uses background threads to connect to the replica set.
120+
121+
If you construct a ``MongoClient`` and immediately print the string representation
122+
of its ``nodes`` attribute, the list might be empty while the client connects to
123+
the replica set members.
124+
125+
Connect to a Single Server
126+
~~~~~~~~~~~~~~~~~~~~~~~~~~
127+
128+
To connect to a single server in a replica set rather than the entire replica set, specify
129+
``false`` as the value of the ``directConnection`` connection option. You can do this in two ways: by passing
130+
an argument to the ``MongoClient`` constructor or through a parameter in your connection string. Select the
131+
:guilabel:`MongoClientSettings` or :guilabel:`Connection String` tab to see the corresponding code.
132+
133+
.. tabs::
134+
135+
.. tab:: MongoClientSettings
136+
:tabid: settings
137+
138+
.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
139+
:language: csharp
140+
:start-after: // start-replica-set-direct-connection-settings
141+
:end-before: // end-replica-set-direct-connection-settings
142+
143+
.. tab:: Connection String
144+
:tabid: connection-string
145+
146+
.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs
147+
:language: csharp
148+
:start-after: // start-replica-set-direct-connection-string
149+
:end-before: // end-replica-set-direct-connection-string
150+
151+
DNS Service Discovery
152+
---------------------
153+
154+
To use DNS service discovery to look up the DNS SRV record of the service you're connecting to,
155+
specify the SRV connection format in your connection string. Additionally, if you enable
156+
the SRV connection format, the {+driver-short+} automatically re-scans for new hosts without
157+
having to change the client configuration.
158+
159+
The following code shows a connection string that uses the SRV connection format:
160+
161+
.. code-block:: csharp
162+
163+
var uri = "mongodb+srv://<hostname>"
164+
165+
To learn more about the SRV connection format, see the :manual:`SRV Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`
166+
entry in the {+mdb-server+} manual.
167+
168+
API Documentation
169+
-----------------
170+
171+
To learn more about the types discussed in this guide, see the following API documentation:
172+
173+
- `MongoClient <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClient.html>`__
174+
- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__

‎source/connect/mongoclient.txt‎

Lines changed: 0 additions & 57 deletions
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‎

Lines changed: 29 additions & 3 deletions
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 list of hosts in the replica set
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)