Skip to content

Commit 7f376fd

Browse files
jordan-smith721jordan-smith721
authored
Misc (#59)
1 parent a0a462f commit 7f376fd

File tree

3 files changed

+333
-0
lines changed

3 files changed

+333
-0
lines changed

‎source/faq.txt

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
.. _csharp-faq:
2+
3+
===
4+
FAQ
5+
===
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Why Does the Driver Throw a Timeout During Server Selection?
16+
------------------------------------------------------------
17+
18+
Each driver operation requires that you choose a healthy server
19+
satisfying the :manual:`server selection criteria
20+
</core/read-preference-mechanics>`. If you do not select an appropriate
21+
server within the `server selection timeout <{+api-root+}/P_MongoDB_Driver_MongoServerSettings_ServerSelectionTimeout.htm>`__, the driver throws a
22+
server selection timeout exception. The exception looks similar to the
23+
following:
24+
25+
.. code-block:: none
26+
27+
A timeout occurred after 30000ms selecting a server using CompositeServerSelector{ Selectors = MongoDB.Driver.MongoClient+AreSessionsSupportedServerSelector, LatencyLimitingServerSelector{ AllowedLatencyRange = 00:00:00.0150000 }, OperationsCountServerSelector }.
28+
Client view of cluster state is
29+
{
30+
ClusterId : "1",
31+
Type : "Unknown",
32+
State : "Disconnected",
33+
Servers :
34+
[{
35+
ServerId: "{ ClusterId : 1, EndPoint : "Unspecified/localhost:27017" }",
36+
EndPoint: "Unspecified/localhost:27017",
37+
ReasonChanged: "Heartbeat",
38+
State: "Disconnected",
39+
ServerVersion: ,
40+
TopologyVersion: ,
41+
Type: "Unknown",
42+
HeartbeatException: "<exception details>"
43+
}]
44+
}.
45+
46+
The error message consists of multiple parts:
47+
48+
1. The server selection timeout (30000 ms).
49+
#. The server selectors considered (``CompositeServerSelector``
50+
containing ``AreSessionsSupportedServerSelector``,
51+
``LatencyLimitingServerSelector``, and
52+
``OperationsCountServerSelector``).
53+
#. The driver’s current view of the cluster topology. The list of
54+
servers that the driver is aware of is a key part of this view. Each
55+
server description contains an exhaustive description of its current
56+
state including information about an endpoint, a server version, a
57+
server type, and its current health state. If the server is not
58+
heathy, ``HeartbeatException`` contains the exception from the
59+
last failed heartbeat. Analyzing the ``HeartbeatException`` on each
60+
cluster node can assist in diagnosing most server selection issues.
61+
The following heartbeat exceptions are common:
62+
63+
* ``No connection could be made because the target machine actively
64+
refused it``: The driver cannot see this cluster node. This can be
65+
because the cluster node has crashed, a firewall is preventing
66+
network traffic from reaching the cluster node or port, or some other
67+
network error is preventing traffic from being successfully routed to
68+
the cluster node.
69+
* ``Attempted to read past the end of the stream``: This error
70+
happens when the driver cannot connect to the cluster nodes due to a
71+
network error, misconfigured firewall, or other network issue. To
72+
address this exception, ensure that all cluster nodes are reachable.
73+
This error commonly occurs when the client machine’s IP address is
74+
not configured in the Atlas IPs Access List, which can be found under
75+
the :guilabel:`Network Access` tab for your Atlas Project.
76+
* ``The remote certificate is invalid according to the validation
77+
procedure``: This error typically indicates a TLS/SSL-related problem
78+
such as an expired/invalid certificate or an untrusted root CA. You
79+
can use tools like ``openssl s_client`` to debug TLS/SSL-related
80+
certificate problems.
81+
82+
Why is the Wait Queue for Acquiring a Connection to the Server Full?
83+
--------------------------------------------------------------------
84+
85+
This exception usually indicates a threading or concurrency problem in
86+
your application. The driver checks out a connection from the selected
87+
server’s connection pool for every read or write operation. If
88+
the connection pool is already at ``maxPoolSize`` - 100 by default - then the
89+
requesting thread blocks in a wait queue. The wait queue's default size
90+
is 5 times ``maxPoolSize``, or 500. If the wait queue is also full, the driver
91+
throws a ``MongoWaitQueueFullException``. The exception looks
92+
similar to the following:
93+
94+
.. code-block:: none
95+
96+
MongoDB.Driver.MongoWaitQueueFullException: The wait queue for
97+
acquiring a connection to server myServer is full.
98+
99+
To resolve this issue, try the following steps:
100+
101+
1. Tune your indexes. By improving the performance of your queries,
102+
you can reduce the time that operations take and reduce the number of
103+
concurrent connections needed for your workload.
104+
#. If you have long-running analytical queries, you may wish to isolate
105+
them to dedicated analytics nodes using :manual:`read preference tags
106+
</core/read-preference/>` or a hidden secondary.
107+
#. Increase ``maxPoolSize`` to allow more simultaneous operations to a
108+
given cluster node. If your MongoDB cluster does not have sufficient
109+
resources to handle the additional connections and simultaneous
110+
workload, performance can decrease due to resource contention
111+
on the cluster nodes. Adjust this setting only with careful
112+
consideration and testing.
113+
#. Increase ``waitQueueMultiple`` to allow more threads/tasks to block
114+
waiting for a connection. This is rarely the appropriate solution and
115+
can severely affect your application performance. Before
116+
considering changes to this setting, address the concurrency problems
117+
in your application.
118+
119+
.. _csharp-faq-unsupported-expressions:
120+
121+
Why are Certain LINQ or Builder Expressions Unsupported?
122+
--------------------------------------------------------
123+
124+
Each LINQ or Builder expression must be available in the Query API. This is not
125+
always possible for the following reasons:
126+
127+
1. You are attempting to use a {+lang-framework+} feature that does not have an
128+
equivalent MongoDB representation. For example, {+lang-framework+} and MongoDB have
129+
different semantics around collations.
130+
#. The driver does not support a particular transformation from LINQ or
131+
Builder expression into MQL (MongoDB Query Language). This may happen because the
132+
provided query has no MQL translation or because a feature has not been
133+
implemented yet in the driver.
134+
135+
If you receive an ``Unsupported filter ...`` or ``Expression not
136+
supported ...`` exception message, try the following
137+
steps:
138+
139+
1. Try configuring the new `LINQ3
140+
<https://mongodb.github.io/mongo-csharp-driver/2.17/reference/driver/crud/linq3/>`__
141+
provider. The LINQ3 provider contains many fixes and new features
142+
over the LINQ2 provider.
143+
#. Use the `MongoDB Analyzer
144+
<https://www.mongodb.com/docs/mongodb-analyzer/current/>`__ to analyze your
145+
expressions.
146+
#. Try to simplify your query where possible.
147+
#. Provide a query as a ``BsonDocument`` or JSON string. All driver
148+
definition classes such as ``FilterDefinition``,
149+
``ProjectionDefinition``, and ``PipelineDefinition`` support implicit
150+
conversion from ``BsonDocument`` or JSON string. For example, the
151+
following filters are equivalent when used in a query or
152+
aggregation:
153+
154+
.. code-block:: csharp
155+
156+
FilterDefinition<Entity> typedFilter = Builders<Entity>.Filter.Eq(e => e.A, 1);
157+
FilterDefinition<Entity> bsonFilter = new BsonDocument {{ "a", 1 }};
158+
FilterDefinition<Entity> jsonFilter = "{ a : 1 }";
159+
160+
.. note::
161+
162+
If you use ``BsonDocument`` or JSON string, then `BsonClassMap
163+
<https://mongodb.github.io/mongo-csharp-driver/2.17/reference/bson/mapping/>`__,
164+
BSON serialization attributes, and serialization conventions are not
165+
taken into account in the Query API. Field names must match the
166+
names and casing as stored by the server. For example, when referencing
167+
the ``_id`` field, you must refer to it using ``_id`` in
168+
``BsonDocument`` or JSON string definitions. Similarly, if a document
169+
has a field ``FirstName`` annotated with ``[BsonElement("first_name")]``, you
170+
must refer to it as ``first_name`` in ``BsonDocument`` or JSON string
171+
definitions.
172+
173+
You can combine the raw and typed forms in the same query, as the
174+
following code demonstrates:
175+
176+
.. code-block:: csharp
177+
178+
FilterDefinition<Entity> filter = Builders<Entity>.Filter
179+
.And(Builders<Entity>.Filter
180+
.Eq(e => e.A, 1), BsonDocument
181+
.Parse("{ b : 2 }"));

‎source/fundamentals/stable-api.txt

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
.. _csharp-stable-api:
2+
3+
==============
4+
{+stable-api+}
5+
==============
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
.. note::
16+
17+
The {+stable-api+} feature requires MongoDB Server 5.0 or later.
18+
19+
You should use the {+stable-api+} feature only if all of the MongoDB
20+
servers you're connecting to support this feature.
21+
22+
Overview
23+
--------
24+
25+
In this guide, you can learn how to specify **{+stable-api+}** compatibility when
26+
connecting to a MongoDB instance or replica set.
27+
28+
The {+stable-api+} feature forces the server to run operations with behaviors compatible
29+
with the API version you specify. When you update either your driver or server,
30+
the API version changes, which can change the way these operations behave.
31+
Using the {+stable-api+} ensures consistent responses from the server and
32+
provides long-term API stability for your application.
33+
34+
The following sections describe how you can enable and customize {+stable-api+} for
35+
your MongoDB client. For more information about the {+stable-api+}, including a list of
36+
the commands it covers, see the :manual:`MongoDB reference page. </reference/stable-api/>`
37+
38+
Enable the {+stable-api+} on a MongoDB Client
39+
---------------------------------------------
40+
41+
To enable the {+stable-api+}, you must specify an API version in the settings
42+
of your MongoDB client. Once you instantiate a ``MongoClient`` instance with
43+
a specified API version, all commands you run with the client use that
44+
version of the {+stable-api+}.
45+
46+
.. tip::
47+
48+
Once you've created a ``MongoClient``, you can't change its {+stable-api+} version.
49+
If you need to run commands using more than one version of the
50+
{+stable-api+}, instantiate a separate client with that version.
51+
52+
If you need to run commands not covered by the {+stable-api+}, make sure the
53+
"strict" option is disabled. See the section on
54+
:ref:`{+stable-api+} Options <stable-api-options>` for more information.
55+
56+
The following example shows how you can instantiate a ``MongoClient`` with a {+stable-api+} version and connect to a server through the following operations:
57+
58+
1. Construct a ``ServerApi`` instance and specify a {+stable-api+} version.
59+
#. Construct a ``MongoClientSettings`` object and set the ``ServerApi`` property.
60+
#. Create a ``MongoClient`` with the ``MongoClientSettings`` object.
61+
62+
.. literalinclude:: /includes/fundamentals/code-examples/StableApi.cs
63+
:start-after: start-stable-api
64+
:end-before: end-stable-api
65+
:language: csharp
66+
:dedent:
67+
68+
.. warning::
69+
70+
If you specify an API version and connect to a MongoDB server that does
71+
not support the {+stable-api+}, your code might raise an exception when
72+
executing a command on your MongoDB server. If you use a ``MongoClient``
73+
that specifies the API version to query a server that doesn't support that version,
74+
your query could fail with an exception message that includes the
75+
following text:
76+
77+
.. code-block:: none
78+
:copyable: false
79+
80+
'Unrecognized field 'apiVersion' on server...
81+
82+
.. _stable-api-options:
83+
84+
{+stable-api+} Options
85+
--------------------------
86+
87+
You can use the options in the following table to customize the behavior of the
88+
{+stable-api+}.
89+
90+
.. list-table::
91+
:header-rows: 1
92+
:stub-columns: 1
93+
:widths: 25,75
94+
95+
* - Option Name
96+
- Description
97+
98+
* - Strict
99+
- | **Optional**. When ``true``, if you call a command that is not part of
100+
the declared API version, the driver raises an exception.
101+
|
102+
| Default: **false**
103+
104+
* - DeprecationErrors
105+
- | **Optional**. When ``true``, if you call a command that is deprecated in the
106+
declared API version, the driver raises an exception.
107+
|
108+
| Default: **false**
109+
110+
The following example shows how you can set these options when constructing a
111+
``ServerApi`` object:
112+
113+
.. literalinclude:: /includes/fundamentals/code-examples/StableApi.cs
114+
:start-after: start-stable-api-options
115+
:end-before: end-stable-api-options
116+
:language: csharp
117+
:dedent:
118+
119+
API Documentation
120+
-----------------
121+
122+
For more information on using the {+stable-api+} with the {+driver-long+}, see the
123+
following API documentation:
124+
125+
- `MongoClient <{+api-root+}/T_MongoDB_Driver_MongoClient.htm>`__
126+
- `MongoClientSettings <{+api-root+}/T_MongoDB_Driver_MongoClientSettings.htm>`__
127+
- `ServerApiVersion <{+api-root+}/T_MongoDB_Driver_ServerApiVersion.htm>`__
128+
- `ServerApi <{+api-root+}/T_MongoDB_Driver_ServerApi.htm>`__
129+

‎source/includes/fundamentals/code-examples/StableApi.cs

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
using MongoDB.Driver;
2+
3+
namespace Fundamentals;
4+
5+
public class StableApi
6+
{
7+
public static void Main(string[] args)
8+
{
9+
// start-stable-api
10+
var serverApi = new ServerApi(ServerApiVersion.V1);
11+
var settings = new MongoClientSettings { ServerApi = serverApi };
12+
var client = new MongoClient(settings);
13+
// end-stable-api
14+
}
15+
16+
public static void UseApiOptions()
17+
{
18+
// start-stable-api-options
19+
var serverApi = new ServerApi(ServerApiVersion.V1, strict: true,
20+
deprecationErrors: true);
21+
// end-stable-api-options
22+
}
23+
}

0 commit comments

Comments
 (0)