From 6d1755c4ced9f05f90830410c5ff1d1e4f309589 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 8 May 2025 19:24:01 -0500 Subject: [PATCH 01/32] add mongoUrl to connection options --- source/connect/connection-options.txt | 162 +++++++++++++++++++------- 1 file changed, 118 insertions(+), 44 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 2d4198e0..708419dd 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -62,6 +62,26 @@ more configuration options than the connection URI. To use a ``MongoClientSettings`` object, create an instance of the class, set its properties, and pass it as an argument to the ``MongoClient`` constructor: +.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs + :language: csharp + :dedent: + :start-after: // start mongo client settings config + :end-before: // end mongo client settings config + +.. _csharp-mongo-url-builder: + +--------------------- +Using MongoUrlBuilder +------------------- + +You can use a ``MongoUrlBuilder`` object to configure connection settings in code +rather than in a connection URI. Configuring the connection this way makes it easier to +change settings at runtime, helps you catch errors during compilation, and provides +more configuration options than the connection URI. + +To use a ``MongoUrlBuilder`` object, create an instance of the class, set +its properties, and pass it as an argument to the ``MongoClient`` constructor: + .. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs :language: csharp :dedent: @@ -72,11 +92,15 @@ Connection Options ------------------ The following table lists each connection option available in the -``MongoClientSettings`` class and, if possible, how to achieve the same result in -the connection string. If a ``MongoClientSettings`` property maps to more than one +``MongoClientSettings`` class, and, if possible, how to achieve the same result in the +connection string. If a ``MongoClientSettings`` property maps to more than one option in the connection string, the **Connection URI Example** shows all relevant options. +If you use your connection URI to create a ``MongoUrl`` object, you can use the object's +read-only properties to access the values of the connection options. These properties are listed +in the ``MongoUrl`` column of the table. + .. note:: If you're using a query parameter for a time duration, the value must be in @@ -86,12 +110,15 @@ relevant options. .. list-table:: :header-rows: 1 - :widths: 30 70 + :widths: 30 60 10 - * - **MongoClientSettings** Property + * - ``MongoClientSettings`` Property - Description + - ``MongoUrlBuilder`` Property + - Connection String + - ``ConnectionString`` property - * - **AllowInsecureTls** + * - ``AllowInsecureTls`` - | Specifies whether to relax TLS constraints as much as possible. This can include | allowing invalid certificates or hostname mismatches. | @@ -101,8 +128,9 @@ relevant options. | **Data Type**: {+bool-data-type+} | **Default**: ``false`` | **Connection URI Example**: ``tlsInsecure=true`` + - ``AllowInsecureTls`` - * - **ApplicationName** + * - ``ApplicationName`` - | The app name the driver passes to the server in the client metadata as part of | the connection handshake. The server prints this value to the MongoDB logs once | the connection is established. The value is also recorded in the slow query logs @@ -111,22 +139,25 @@ relevant options. | **Data Type**: {+string-data-type+} | **Default**: ``null`` | **Connection URI Example**: ``appName=yourApp`` + - ``ApplicationName`` - * - **AutoEncryptionOptions** + * - ``AutoEncryptionOptions`` - | Settings for automatic client-side encryption. | | **Data Type**: `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Encryption.AutoEncryptionOptions.html>`__ | **Default**: ``null`` | **Connection URI Example**: {+not-available+} + - {+not-available+} - * - **ClusterConfigurator** + * - ``ClusterConfigurator`` - | Low-level configuration options for sockets, TLS, cluster, and others. | | **Data Type**: Action<`ClusterBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.html>`__> | **Default**: ``null`` | **Connection URI Example**: {+not-available+} + - {+not-available+} - * - **Compressors** + * - ``Compressors`` - | The preferred compression types, in order, for wire-protocol messages sent to | or received from the server. The driver uses the first of these compression types | that the server supports. @@ -134,16 +165,18 @@ relevant options. | **Data Type**: `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.CompressorConfiguration.html>`__ | **Default**: ``null`` | **Connection URI Example**: ``compressors=snappy,zstd`` + - ``Compressors`` - * - **ConnectTimeout** + * - ``ConnectTimeout`` - | The length of time the driver tries to establish a single TCP socket connection | to the server before timing out. | | **DataType**: ``TimeSpan`` | **Default**: 30 seconds | **Connection URI Example**: ``connectTimeoutMS=0`` + - ``ConnectTimeout`` - * - **Credential** + * - ``Credential`` - | Settings for how the driver authenticates to the server. This includes | authentication credentials, mechanism, source, and other settings. | @@ -162,8 +195,9 @@ relevant options. mongodb://user1:password1&authMechanism=GSSAPI &authMechanismProperties=SERVICE_NAME:other,REALM:otherrealm &authSource=$external + - ``GetCredential()`` - * - **DirectConnection** + * - ``DirectConnection`` - | Specifies whether to force dispatch **all** operations to the host. | | If you specify this option, the driver doesn't accept the @@ -177,38 +211,43 @@ relevant options. | **Data Type**: {+bool-data-type+} | **Default**: ``false`` | **Connection URI Example**: ``directConnection=true`` + - ``DirectConnection`` - * - **HeartbeatInterval** + * - ``HeartbeatInterval`` - | The interval between regular server-monitoring checks. Must be greater than or | equal to 500 milliseconds. | | **Data Type**: ``TimeSpan`` | **Default**: 10 seconds | **Connection URI Example**: ``heartbeatFrequencyMS=5000`` + - ``HeartbeatInterval`` - * - **HeartbeatTimeout** + * - ``HeartbeatTimeout`` - | The length of time a monitoring socket can be idle before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: Same value as ``ConnectTimeout`` | **Connection URI Example**: ``heartbeatTimeoutMS=5000`` + - ``HeartbeatTimeout`` - * - **IPv6** + * - ``IPv6`` - | Specifies whether the host address is in IPv6 format. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` | **Connection URI Example**: ``ipv6=true`` + - ``IPv6`` - * - **IsFrozen** + * - ``IsFrozen`` - | Indicates whether the settings have been frozen. Frozen settings can't be changed. | This option is read-only. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` | **Connection URI Example**: {+not-available+} + - {+not-available+} - * - **LoadBalanced** + * - ``LoadBalanced`` - | Specifies whether the driver is connecting to a load balancer. You can set this | property to ``true`` only if: @@ -220,8 +259,9 @@ relevant options. | **Data Type**: {+bool-data-type+} | **Default**: ``false`` | **Connection URI Example**: ``loadBalanced=true`` + - ``LoadBalanced`` - * - **LocalThreshold** + * - ``LocalThreshold`` - | The latency window for server eligibility. If a server's round trip takes longer | than the fastest server's round-trip time plus this value, the server isn't | eligible for selection. @@ -229,45 +269,51 @@ relevant options. | **Data Type**: ``TimeSpan`` | **Default**: 15 milliseconds | **Connection URI Example**: ``localThresholdMS=0`` + - ``LocalThreshold`` - * - **LoggingSettings** + * - ``LoggingSettings`` - | The settings used for :ref:`logging. ` | | **Data Type**: `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.LoggingSettings.html>`__ | **Default**: ``null`` | **Connection URI Example**: {+not-available+} + - {+not-available+} - * - **MaxConnecting** + * - ``MaxConnecting`` - | The greatest number of connections a driver's connection pool may be | establishing concurrently. | | **Data Type**: {+int-data-type+} | **Default**: ``2`` | **Connection URI Example**: ``maxConnecting=3`` + - ``MaxConnecting`` - * - **MaxConnectionIdleTime** + * - ``MaxConnectionIdleTime`` - | The length of time a connection can be idle before the driver closes it. | | **Data Type**: ``TimeSpan`` | **Default**: 10 minutes | **Connection URI Example**: ``maxIdleTimeMS=300000`` + - ``MaxConnectionIdleTime`` - * - **MaxConnectionLifeTime** + * - ``MaxConnectionLifeTime`` - | The length of time a connection can be pooled before expiring. | | **Data Type**: ``TimeSpan`` | **Default**: 30 minutes | **Connection URI Example**: ``maxLifetimeMS=50000`` + - ``MaxConnectionLifeTime`` - * - **MaxConnectionPoolSize** + * - ``MaxConnectionPoolSize`` - | The greatest number of clients or connections the driver can create in its | connection pool. This count includes connections in use. | | **Data Type**: {+int-data-type+} | **Default**: ``100`` | **Connection URI Example**: ``maxPoolSize=150`` + - ``MaxConnectionPoolSize`` - * - **MinConnectionPoolSize** + * - ``MinConnectionPoolSize`` - | The number of connections the driver should create and keep in the connection | pool even when no operations are occurring. This count includes connections | in use. @@ -275,16 +321,18 @@ relevant options. | **Data Type**: {+int-data-type+} | **Default**: ``0`` | **Connection URI Example**: ``minPoolSize=1`` + - ``MinConnectionPoolSize`` - * - **ReadConcern** + * - ``ReadConcern`` - | The client's default read concern. | See :ref:`read concern ` for more information. | | **Data Type**: `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ | **Default**: ``ReadConcern.Default`` | **Connection URI Example**: ``readConcernLevel=local`` + - {+not-available+} - * - **ReadEncoding** + * - ``ReadEncoding`` - | The UTF-8 encoding to use for string deserialization. | Strict encoding will throw an exception when an invalid UTF-8 byte sequence | is encountered. @@ -292,8 +340,9 @@ relevant options. | **Data Type**: ``UTF8Encoding`` | **Default**: Strict encoding | **Connection URI Example**: {+not-available+} + - {+not-available+} - * - **ReadPreference** + * - ``ReadPreference`` - | The client's default read-preference settings. ``MaxStaleness`` represents the | longest replication lag, in wall-clock time, that a secondary can experience and | still be eligible for server selection. Specifying ``-1`` means no maximum. @@ -314,29 +363,33 @@ relevant options. than once. If you do, the client treats each instance as a separate tag set. The order of the tags in the URI determines the order for read preference. You can use this parameter only if the read-preference mode is not ``primary``. + - ``ReadPreference`` - * - **ReplicaSetName** + * - ``ReplicaSetName`` - | The name of the replica set to connect to. | | **Data Type**: {+string-data-type+} | **Default**: ``null`` | **Connection URI Example**: ``replicaSet=yourReplicaSet`` + - ``ReplicaSetName`` - * - **RetryReads** + * - ``RetryReads`` - | Enables retryable reads. | | **Data Type**: {+bool-data-type+} | **Default**: ``true`` | **Connection URI Example**: ``retryReads=false`` + - ``RetryReads`` - * - **RetryWrites** + * - ``RetryWrites`` - | Enables retryable writes. | | **Data Type**: {+bool-data-type+} | **Default**: ``true`` | **Connection URI Example**: ``retryWrites=false`` + - ``RetryWrites`` - * - **Scheme** + * - ``Scheme`` - | Specifies whether to use the standard connection string format (``MongoDB``) | or the DNS seed list format (``MongoDBPlusSrv``). | See :manual:`the MongoDB Manual` for more @@ -349,15 +402,17 @@ relevant options. | **Data Type**: `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ConnectionStringScheme.html>`__ | **Default**: ``ConnectionStringScheme.MongoDB`` | **Connection URI Example**: ``mongodb+srv://`` + - ``Scheme`` - * - **Server** + * - ``Server`` - | The host and port number where MongoDB is running. | | **Data Type**: `MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__ | **Default**: ``localhost:27017`` | **Connection URI Example**: ``mongodb://sample.host:27017`` + - ``Server`` - * - **ServerApi** + * - ``ServerApi`` - | Allows opting into Stable API versioning. See | :manual:`the MongoDB Manual` for more information about | Stable API versioning. @@ -365,8 +420,9 @@ relevant options. | **Data Type**: `ServerApi <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerApi.html>`__ | **Default**: ``null`` | **Connection URI Example**: {+not-available+} + - {+not-available+} - * - **ServerMonitoringMode** + * - ``ServerMonitoringMode`` - | Specifies the server monitoring protocol to use. When | this option is set to ``Auto``, the monitoring mode is determined | by the environment in which the driver is running. The driver @@ -376,30 +432,34 @@ relevant options. | **Data Type**: `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Servers.ServerMonitoringMode.html>`__ | **Default**: ``Auto`` | **Connection URI Example**: ``serverMonitoringMode=poll`` + - ``ServerMonitoringMode`` - * - **Servers** + * - ``Servers`` - | The cluster members where MongoDB is running. | | **Data Type**: IEnumerable<`MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__> | **Default**: ``localhost:27017`` | **Connection URI Example**: ``mongodb://sample.host1:27017,sample.host2:27017`` + - ``Servers`` - * - **ServerSelectionTimeout** + * - ``ServerSelectionTimeout`` - | The length of time the driver tries to select a server before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: 30 seconds | **Connection URI Example**: ``serverSelectionTimeoutMS=15000`` + - ``ServerSelectionTimeout`` - * - **SocketTimeout** + * - ``SocketTimeout`` - | The length of time the driver tries to send or receive on a socket before | timing out. | | **Data Type**: ``TimeSpan`` | **Default**: OS default | **Connection URI Example**: ``socketTimeoutMS=0`` + - ``SocketTimeout`` - * - **SrvMaxHosts** + * - ``SrvMaxHosts`` - | The greatest number of SRV results to randomly select when initially populating | the seedlist or, during SRV polling, adding new hosts to the topology. | @@ -410,8 +470,9 @@ relevant options. | **Data Type**: {+int-data-type+} | **Default**: ``0`` | **Connection URI Example**: ``srvMaxHosts=3`` + - ``SrvMaxHosts`` - * - **SslSettings** + * - ``SslSettings`` - | TLS/SSL options, including client certificates, revocation handling, and | enabled and disabled TLS/SSL protocols. | @@ -422,16 +483,18 @@ relevant options. | **Data Type**: `SslSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SslSettings.html>`__ | **Default**: ``null`` | **Connection URI Example**: ``tlsDisableCertificateRevocationCheck=false`` + - {+not-available+} - * - **TranslationOptions** + * - ``TranslationOptions`` - | Specifies options, such as the {+mdb-server+} version, for translating LINQ | queries to the Query API. | | **Data Type**: `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ExpressionTranslationOptions.html>`__ | **Default**: ``null`` | **Connection URI Example**: {+not-available+} + - {+not-available+} - * - **UseTls** + * - ``UseTls`` - | Specifies whether to require TLS for connections to the server. If you use | a scheme of ``"mongodb+srv"`` or specify other TLS options, | this option defaults to ``true``. @@ -439,16 +502,18 @@ relevant options. | **Data Type**: {+bool-data-type+} | **Default**: ``false`` | **Connection URI Example**: ``tls=true`` + - ``UseTls`` - * - **WaitQueueTimeout** + * - ``WaitQueueTimeout`` - | The length of time the driver tries to check out a connection from a | server's connection pool before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: 2 minutes | **Connection URI Example**: ``waitQueueTimeoutMS=0`` + - ``WaitQueueTimeout`` - * - **WriteConcern** + * - ``WriteConcern`` - | The default write-concern settings, including write timeout and | journaling, for the client. | See :ref:`write concern ` for more information. @@ -456,8 +521,9 @@ relevant options. | **Data Type**: `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ | **Default**: ``WriteConcern.Acknowledged`` | **Connection URI Example**: ``w=majority&wTimeoutMS=0&journal=true`` + - ``GetWriteConcern(bool)`` - * - **WriteEncoding** + * - ``WriteEncoding`` - | Specifies whether UTF-8 string serialization is strict or lenient. With strict | encoding, the driver will throw an exception when it encounters an invalid | UTF-8 byte sequence. @@ -465,3 +531,11 @@ relevant options. | **Data Type**: ``UTF8Encoding`` | **Default**: Strict encoding | **Connection URI Example**: {+not-available+} + - {+not-available+} + +.. tip:: Other MongoUrl Members + + The ``MongoUrl`` class contains other methods and read-only properties that you can + use to retrieve information about your connection. For a full list, see + `MongoUrl <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrl.html>`__ in the + API documentation. \ No newline at end of file From 7ce7f4c20b10aa5c4162555d108d51a2badbffc7 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 11:40:11 -0500 Subject: [PATCH 02/32] preview --- source/connect/connection-options.txt | 128 +++++++++++++++++--------- 1 file changed, 82 insertions(+), 46 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 708419dd..8fad2fbb 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -68,6 +68,48 @@ its properties, and pass it as an argument to the ``MongoClient`` constructor: :start-after: // start mongo client settings config :end-before: // end mongo client settings config +.. _csharp-replica-set-options: + +Replica Set Options +------------------- + +ReplicaSetName +~~~~~~~~~~~~~~ + +The name of the replica set to connect to, as a {+string-data-type+}. The default value +is no replica set. + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + .. code-block:: csharp + :copyable: true + + settings.ReplicaSetName = "yourReplicaSet"; + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + .. code-block:: csharp + :copyable: true + + builder.ReplicaSetName = "yourReplicaSet"; + + .. tab:: ConnectionString + :tabid: connection-string-object + + .. code-block:: csharp + :copyable: true + + connString.ReplicaSetName = "yourReplicaSet"; + + .. tab:: Connection String + :tabid: connection-string + + ``replicaSet=yourReplicaSet`` + .. _csharp-mongo-url-builder: --------------------- @@ -127,8 +169,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - | **Connection URI Example**: ``tlsInsecure=true`` - ``AllowInsecureTls`` + | **Connection URI Example**: ``tlsInsecure=true`` * - ``ApplicationName`` - | The app name the driver passes to the server in the client metadata as part of @@ -138,24 +180,24 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+string-data-type+} | **Default**: ``null`` - | **Connection URI Example**: ``appName=yourApp`` - ``ApplicationName`` + | **Connection URI Example**: ``appName=yourApp`` * - ``AutoEncryptionOptions`` - | Settings for automatic client-side encryption. | | **Data Type**: `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Encryption.AutoEncryptionOptions.html>`__ | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} * - ``ClusterConfigurator`` - | Low-level configuration options for sockets, TLS, cluster, and others. | | **Data Type**: Action<`ClusterBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.html>`__> | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} * - ``Compressors`` - | The preferred compression types, in order, for wire-protocol messages sent to @@ -164,8 +206,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.CompressorConfiguration.html>`__ | **Default**: ``null`` - | **Connection URI Example**: ``compressors=snappy,zstd`` - ``Compressors`` + | **Connection URI Example**: ``compressors=snappy,zstd`` * - ``ConnectTimeout`` - | The length of time the driver tries to establish a single TCP socket connection @@ -173,8 +215,8 @@ in the ``MongoUrl`` column of the table. | | **DataType**: ``TimeSpan`` | **Default**: 30 seconds - | **Connection URI Example**: ``connectTimeoutMS=0`` - ``ConnectTimeout`` + | **Connection URI Example**: ``connectTimeoutMS=0`` * - ``Credential`` - | Settings for how the driver authenticates to the server. This includes @@ -187,6 +229,7 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ | **Default**: ``null`` + - ``GetCredential()`` | **Connection URI Example**: .. code-block:: none @@ -195,7 +238,6 @@ in the ``MongoUrl`` column of the table. mongodb://user1:password1&authMechanism=GSSAPI &authMechanismProperties=SERVICE_NAME:other,REALM:otherrealm &authSource=$external - - ``GetCredential()`` * - ``DirectConnection`` - | Specifies whether to force dispatch **all** operations to the host. @@ -210,8 +252,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - | **Connection URI Example**: ``directConnection=true`` - ``DirectConnection`` + | **Connection URI Example**: ``directConnection=true`` * - ``HeartbeatInterval`` - | The interval between regular server-monitoring checks. Must be greater than or @@ -219,24 +261,24 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: ``TimeSpan`` | **Default**: 10 seconds - | **Connection URI Example**: ``heartbeatFrequencyMS=5000`` - ``HeartbeatInterval`` + | **Connection URI Example**: ``heartbeatFrequencyMS=5000`` * - ``HeartbeatTimeout`` - | The length of time a monitoring socket can be idle before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: Same value as ``ConnectTimeout`` - | **Connection URI Example**: ``heartbeatTimeoutMS=5000`` - ``HeartbeatTimeout`` + | **Connection URI Example**: ``heartbeatTimeoutMS=5000`` * - ``IPv6`` - | Specifies whether the host address is in IPv6 format. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - | **Connection URI Example**: ``ipv6=true`` - ``IPv6`` + | **Connection URI Example**: ``ipv6=true`` * - ``IsFrozen`` - | Indicates whether the settings have been frozen. Frozen settings can't be changed. @@ -244,8 +286,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} * - ``LoadBalanced`` - | Specifies whether the driver is connecting to a load balancer. You can set this @@ -258,8 +300,8 @@ in the ``MongoUrl`` column of the table. | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - | **Connection URI Example**: ``loadBalanced=true`` - ``LoadBalanced`` + | **Connection URI Example**: ``loadBalanced=true`` * - ``LocalThreshold`` - | The latency window for server eligibility. If a server's round trip takes longer @@ -268,16 +310,16 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: ``TimeSpan`` | **Default**: 15 milliseconds - | **Connection URI Example**: ``localThresholdMS=0`` - ``LocalThreshold`` + | **Connection URI Example**: ``localThresholdMS=0`` * - ``LoggingSettings`` - | The settings used for :ref:`logging. ` | | **Data Type**: `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.LoggingSettings.html>`__ | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} * - ``MaxConnecting`` - | The greatest number of connections a driver's connection pool may be @@ -285,24 +327,24 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+int-data-type+} | **Default**: ``2`` - | **Connection URI Example**: ``maxConnecting=3`` - ``MaxConnecting`` + | **Connection URI Example**: ``maxConnecting=3`` * - ``MaxConnectionIdleTime`` - | The length of time a connection can be idle before the driver closes it. | | **Data Type**: ``TimeSpan`` | **Default**: 10 minutes - | **Connection URI Example**: ``maxIdleTimeMS=300000`` - ``MaxConnectionIdleTime`` + | **Connection URI Example**: ``maxIdleTimeMS=300000`` * - ``MaxConnectionLifeTime`` - | The length of time a connection can be pooled before expiring. | | **Data Type**: ``TimeSpan`` | **Default**: 30 minutes - | **Connection URI Example**: ``maxLifetimeMS=50000`` - ``MaxConnectionLifeTime`` + | **Connection URI Example**: ``maxLifetimeMS=50000`` * - ``MaxConnectionPoolSize`` - | The greatest number of clients or connections the driver can create in its @@ -310,8 +352,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+int-data-type+} | **Default**: ``100`` - | **Connection URI Example**: ``maxPoolSize=150`` - ``MaxConnectionPoolSize`` + | **Connection URI Example**: ``maxPoolSize=150`` * - ``MinConnectionPoolSize`` - | The number of connections the driver should create and keep in the connection @@ -320,8 +362,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+int-data-type+} | **Default**: ``0`` - | **Connection URI Example**: ``minPoolSize=1`` - ``MinConnectionPoolSize`` + | **Connection URI Example**: ``minPoolSize=1`` * - ``ReadConcern`` - | The client's default read concern. @@ -329,8 +371,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ | **Default**: ``ReadConcern.Default`` - | **Connection URI Example**: ``readConcernLevel=local`` - {+not-available+} + | **Connection URI Example**: ``readConcernLevel=local`` * - ``ReadEncoding`` - | The UTF-8 encoding to use for string deserialization. @@ -339,8 +381,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: ``UTF8Encoding`` | **Default**: Strict encoding - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} * - ``ReadPreference`` - | The client's default read-preference settings. ``MaxStaleness`` represents the @@ -350,6 +392,7 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ | **Default**: ``ReadPreference.Primary`` + - ``ReadPreference`` | **Connection URI Example**: .. code-block:: none @@ -363,31 +406,24 @@ in the ``MongoUrl`` column of the table. than once. If you do, the client treats each instance as a separate tag set. The order of the tags in the URI determines the order for read preference. You can use this parameter only if the read-preference mode is not ``primary``. - - ``ReadPreference`` - * - ``ReplicaSetName`` - - | The name of the replica set to connect to. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``null`` - | **Connection URI Example**: ``replicaSet=yourReplicaSet`` - - ``ReplicaSetName`` + * - ``RetryReads`` - | Enables retryable reads. | | **Data Type**: {+bool-data-type+} | **Default**: ``true`` - | **Connection URI Example**: ``retryReads=false`` - ``RetryReads`` + | **Connection URI Example**: ``retryReads=false`` * - ``RetryWrites`` - | Enables retryable writes. | | **Data Type**: {+bool-data-type+} | **Default**: ``true`` - | **Connection URI Example**: ``retryWrites=false`` - ``RetryWrites`` + | **Connection URI Example**: ``retryWrites=false`` * - ``Scheme`` - | Specifies whether to use the standard connection string format (``MongoDB``) @@ -401,16 +437,16 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ConnectionStringScheme.html>`__ | **Default**: ``ConnectionStringScheme.MongoDB`` - | **Connection URI Example**: ``mongodb+srv://`` - ``Scheme`` + | **Connection URI Example**: ``mongodb+srv://`` * - ``Server`` - | The host and port number where MongoDB is running. | | **Data Type**: `MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__ | **Default**: ``localhost:27017`` - | **Connection URI Example**: ``mongodb://sample.host:27017`` - ``Server`` + | **Connection URI Example**: ``mongodb://sample.host:27017`` * - ``ServerApi`` - | Allows opting into Stable API versioning. See @@ -419,8 +455,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `ServerApi <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerApi.html>`__ | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} * - ``ServerMonitoringMode`` - | Specifies the server monitoring protocol to use. When @@ -431,24 +467,24 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Servers.ServerMonitoringMode.html>`__ | **Default**: ``Auto`` - | **Connection URI Example**: ``serverMonitoringMode=poll`` - ``ServerMonitoringMode`` + | **Connection URI Example**: ``serverMonitoringMode=poll`` * - ``Servers`` - | The cluster members where MongoDB is running. | | **Data Type**: IEnumerable<`MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__> | **Default**: ``localhost:27017`` - | **Connection URI Example**: ``mongodb://sample.host1:27017,sample.host2:27017`` - ``Servers`` + | **Connection URI Example**: ``mongodb://sample.host1:27017,sample.host2:27017`` * - ``ServerSelectionTimeout`` - | The length of time the driver tries to select a server before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: 30 seconds - | **Connection URI Example**: ``serverSelectionTimeoutMS=15000`` - ``ServerSelectionTimeout`` + | **Connection URI Example**: ``serverSelectionTimeoutMS=15000`` * - ``SocketTimeout`` - | The length of time the driver tries to send or receive on a socket before @@ -456,8 +492,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: ``TimeSpan`` | **Default**: OS default - | **Connection URI Example**: ``socketTimeoutMS=0`` - ``SocketTimeout`` + | **Connection URI Example**: ``socketTimeoutMS=0`` * - ``SrvMaxHosts`` - | The greatest number of SRV results to randomly select when initially populating @@ -469,8 +505,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+int-data-type+} | **Default**: ``0`` - | **Connection URI Example**: ``srvMaxHosts=3`` - ``SrvMaxHosts`` + | **Connection URI Example**: ``srvMaxHosts=3`` * - ``SslSettings`` - | TLS/SSL options, including client certificates, revocation handling, and @@ -482,8 +518,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `SslSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SslSettings.html>`__ | **Default**: ``null`` - | **Connection URI Example**: ``tlsDisableCertificateRevocationCheck=false`` - {+not-available+} + | **Connection URI Example**: ``tlsDisableCertificateRevocationCheck=false`` * - ``TranslationOptions`` - | Specifies options, such as the {+mdb-server+} version, for translating LINQ @@ -491,8 +527,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ExpressionTranslationOptions.html>`__ | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} * - ``UseTls`` - | Specifies whether to require TLS for connections to the server. If you use @@ -501,8 +537,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - | **Connection URI Example**: ``tls=true`` - ``UseTls`` + | **Connection URI Example**: ``tls=true`` * - ``WaitQueueTimeout`` - | The length of time the driver tries to check out a connection from a @@ -510,8 +546,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: ``TimeSpan`` | **Default**: 2 minutes - | **Connection URI Example**: ``waitQueueTimeoutMS=0`` - ``WaitQueueTimeout`` + | **Connection URI Example**: ``waitQueueTimeoutMS=0`` * - ``WriteConcern`` - | The default write-concern settings, including write timeout and @@ -520,8 +556,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ | **Default**: ``WriteConcern.Acknowledged`` - | **Connection URI Example**: ``w=majority&wTimeoutMS=0&journal=true`` - ``GetWriteConcern(bool)`` + | **Connection URI Example**: ``w=majority&wTimeoutMS=0&journal=true`` * - ``WriteEncoding`` - | Specifies whether UTF-8 string serialization is strict or lenient. With strict @@ -530,8 +566,8 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: ``UTF8Encoding`` | **Default**: Strict encoding - | **Connection URI Example**: {+not-available+} - {+not-available+} + | **Connection URI Example**: {+not-available+} .. tip:: Other MongoUrl Members From 76842203a0434a528a94e37dd281cae38d650d03 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 11:56:41 -0500 Subject: [PATCH 03/32] preview --- source/connect/connection-options.txt | 68 ++++++++++++--------------- 1 file changed, 31 insertions(+), 37 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 8fad2fbb..2bc04509 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -62,6 +62,26 @@ more configuration options than the connection URI. To use a ``MongoClientSettings`` object, create an instance of the class, set its properties, and pass it as an argument to the ``MongoClient`` constructor: +.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs + :language: csharp + :dedent: + :start-after: // start mongo client settings config + :end-before: // end mongo client settings config + +.. _csharp-mongo-url-builder: + +--------------------- +Using MongoUrlBuilder +--------------------- + +You can use a ``MongoUrlBuilder`` object to configure connection settings in code +rather than in a connection URI. Configuring the connection this way makes it easier to +change settings at runtime, helps you catch errors during compilation, and provides +more configuration options than the connection URI. + +To use a ``MongoUrlBuilder`` object, create an instance of the class, set +its properties, and pass it as an argument to the ``MongoClient`` constructor: + .. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs :language: csharp :dedent: @@ -97,38 +117,13 @@ is no replica set. builder.ReplicaSetName = "yourReplicaSet"; - .. tab:: ConnectionString - :tabid: connection-string-object - - .. code-block:: csharp - :copyable: true - - connString.ReplicaSetName = "yourReplicaSet"; - .. tab:: Connection String :tabid: connection-string - ``replicaSet=yourReplicaSet`` - -.. _csharp-mongo-url-builder: - ---------------------- -Using MongoUrlBuilder -------------------- - -You can use a ``MongoUrlBuilder`` object to configure connection settings in code -rather than in a connection URI. Configuring the connection this way makes it easier to -change settings at runtime, helps you catch errors during compilation, and provides -more configuration options than the connection URI. - -To use a ``MongoUrlBuilder`` object, create an instance of the class, set -its properties, and pass it as an argument to the ``MongoClient`` constructor: - -.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs - :language: csharp - :dedent: - :start-after: // start mongo client settings config - :end-before: // end mongo client settings config + .. code-block:: csharp + :copyable: true + + replicaSet=yourReplicaSet Connection Options ------------------ @@ -139,9 +134,9 @@ connection string. If a ``MongoClientSettings`` property maps to more than one option in the connection string, the **Connection URI Example** shows all relevant options. -If you use your connection URI to create a ``MongoUrl`` object, you can use the object's -read-only properties to access the values of the connection options. These properties are listed -in the ``MongoUrl`` column of the table. +If you use your connection URI to create a ``MongoUrl`` or ``ConnectionString`` object, +you can use the object's read-only properties to access the values of the connection +options. These properties are listed in the ``MongoUrl`` column of the table. .. note:: @@ -152,15 +147,15 @@ in the ``MongoUrl`` column of the table. .. list-table:: :header-rows: 1 - :widths: 30 60 10 + :widths: 20 20 50 10 * - ``MongoClientSettings`` Property - - Description - ``MongoUrlBuilder`` Property + - Description - Connection String - - ``ConnectionString`` property * - ``AllowInsecureTls`` + - ``AllowInsecureTls`` - | Specifies whether to relax TLS constraints as much as possible. This can include | allowing invalid certificates or hostname mismatches. | @@ -169,8 +164,7 @@ in the ``MongoUrl`` column of the table. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``AllowInsecureTls`` - | **Connection URI Example**: ``tlsInsecure=true`` + - ``tlsInsecure=true`` * - ``ApplicationName`` - | The app name the driver passes to the server in the client metadata as part of From 46bfcb65b50678d0e485ba1c1ee2393bb4600bf8 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 12:22:42 -0500 Subject: [PATCH 04/32] preview --- source/connect/connection-options.txt | 143 ++++++++++---------------- 1 file changed, 57 insertions(+), 86 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 2bc04509..9f3908b4 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -88,42 +88,14 @@ its properties, and pass it as an argument to the ``MongoClient`` constructor: :start-after: // start mongo client settings config :end-before: // end mongo client settings config -.. _csharp-replica-set-options: - -Replica Set Options -------------------- - -ReplicaSetName -~~~~~~~~~~~~~~ - -The name of the replica set to connect to, as a {+string-data-type+}. The default value -is no replica set. - -.. tabs:: - - .. tab:: MongoClientSettings - :tabid: mongo-client-settings - - .. code-block:: csharp - :copyable: true - - settings.ReplicaSetName = "yourReplicaSet"; - - .. tab:: MongoUrlBuilder - :tabid: mongo-url-builder - - .. code-block:: csharp - :copyable: true - - builder.ReplicaSetName = "yourReplicaSet"; - - .. tab:: Connection String - :tabid: connection-string +.. tip:: Other MongoUrl Members + + The ``MongoUrl`` class contains other methods and read-only properties that you can + use to retrieve information about your connection. For a full list, see + `MongoUrl <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrl.html>`__ in the + API documentation. - .. code-block:: csharp - :copyable: true - - replicaSet=yourReplicaSet +.. _csharp-replica-set-options: Connection Options ------------------ @@ -147,12 +119,11 @@ options. These properties are listed in the ``MongoUrl`` column of the table. .. list-table:: :header-rows: 1 - :widths: 20 20 50 10 + :widths: 20 20 60 * - ``MongoClientSettings`` Property - ``MongoUrlBuilder`` Property - Description - - Connection String * - ``AllowInsecureTls`` - ``AllowInsecureTls`` @@ -164,9 +135,10 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``tlsInsecure=true`` + | **Connection URI Example**: ``tlsInsecure=true`` * - ``ApplicationName`` + - ``ApplicationName`` - | The app name the driver passes to the server in the client metadata as part of | the connection handshake. The server prints this value to the MongoDB logs once | the connection is established. The value is also recorded in the slow query logs @@ -174,45 +146,54 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: {+string-data-type+} | **Default**: ``null`` - - ``ApplicationName`` | **Connection URI Example**: ``appName=yourApp`` + + + + * - ``AutoEncryptionOptions`` + - {+not-available+} - | Settings for automatic client-side encryption. | | **Data Type**: `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Encryption.AutoEncryptionOptions.html>`__ | **Default**: ``null`` - - {+not-available+} | **Connection URI Example**: {+not-available+} * - ``ClusterConfigurator`` + - {+not-available+} - | Low-level configuration options for sockets, TLS, cluster, and others. | | **Data Type**: Action<`ClusterBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.html>`__> | **Default**: ``null`` - - {+not-available+} | **Connection URI Example**: {+not-available+} * - ``Compressors`` + - ``Compressors`` - | The preferred compression types, in order, for wire-protocol messages sent to | or received from the server. The driver uses the first of these compression types | that the server supports. | | **Data Type**: `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.CompressorConfiguration.html>`__ | **Default**: ``null`` - - ``Compressors`` | **Connection URI Example**: ``compressors=snappy,zstd`` * - ``ConnectTimeout`` + - ``ConnectTimeout`` - | The length of time the driver tries to establish a single TCP socket connection | to the server before timing out. | | **DataType**: ``TimeSpan`` | **Default**: 30 seconds - - ``ConnectTimeout`` | **Connection URI Example**: ``connectTimeoutMS=0`` - * - ``Credential`` + * - | ``Credential`` + | + | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ + - | - ``AuthenticationMechanism`` + | - - **Data Type**: {+string-data-type+} + | - ``AuthenticationMechanismProperties`` + | - - **Data Type**: ``IEnumerable>`` - | Settings for how the driver authenticates to the server. This includes | authentication credentials, mechanism, source, and other settings. | @@ -221,9 +202,7 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | :ref:`authentication mechanisms ` for available | authentication mechanisms. | - | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ | **Default**: ``null`` - - ``GetCredential()`` | **Connection URI Example**: .. code-block:: none @@ -234,6 +213,7 @@ options. These properties are listed in the ``MongoUrl`` column of the table. &authSource=$external * - ``DirectConnection`` + - ``DirectConnection`` - | Specifies whether to force dispatch **all** operations to the host. | | If you specify this option, the driver doesn't accept the @@ -246,44 +226,44 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``DirectConnection`` | **Connection URI Example**: ``directConnection=true`` * - ``HeartbeatInterval`` + - ``HeartbeatInterval`` - | The interval between regular server-monitoring checks. Must be greater than or | equal to 500 milliseconds. | | **Data Type**: ``TimeSpan`` | **Default**: 10 seconds - - ``HeartbeatInterval`` | **Connection URI Example**: ``heartbeatFrequencyMS=5000`` * - ``HeartbeatTimeout`` + - ``HeartbeatTimeout`` - | The length of time a monitoring socket can be idle before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: Same value as ``ConnectTimeout`` - - ``HeartbeatTimeout`` | **Connection URI Example**: ``heartbeatTimeoutMS=5000`` * - ``IPv6`` + - ``IPv6`` - | Specifies whether the host address is in IPv6 format. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``IPv6`` | **Connection URI Example**: ``ipv6=true`` * - ``IsFrozen`` + - {+not-available+} - | Indicates whether the settings have been frozen. Frozen settings can't be changed. | This option is read-only. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - {+not-available+} | **Connection URI Example**: {+not-available+} * - ``LoadBalanced`` + - ``LoadBalanced`` - | Specifies whether the driver is connecting to a load balancer. You can set this | property to ``true`` only if: @@ -294,91 +274,91 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``LoadBalanced`` | **Connection URI Example**: ``loadBalanced=true`` * - ``LocalThreshold`` + - ``LocalThreshold`` - | The latency window for server eligibility. If a server's round trip takes longer | than the fastest server's round-trip time plus this value, the server isn't | eligible for selection. | | **Data Type**: ``TimeSpan`` | **Default**: 15 milliseconds - - ``LocalThreshold`` | **Connection URI Example**: ``localThresholdMS=0`` * - ``LoggingSettings`` + - {+not-available+} - | The settings used for :ref:`logging. ` | | **Data Type**: `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.LoggingSettings.html>`__ | **Default**: ``null`` - - {+not-available+} | **Connection URI Example**: {+not-available+} * - ``MaxConnecting`` + - ``MaxConnecting`` - | The greatest number of connections a driver's connection pool may be | establishing concurrently. | | **Data Type**: {+int-data-type+} | **Default**: ``2`` - - ``MaxConnecting`` | **Connection URI Example**: ``maxConnecting=3`` * - ``MaxConnectionIdleTime`` + - ``MaxConnectionIdleTime`` - | The length of time a connection can be idle before the driver closes it. | | **Data Type**: ``TimeSpan`` | **Default**: 10 minutes - - ``MaxConnectionIdleTime`` | **Connection URI Example**: ``maxIdleTimeMS=300000`` * - ``MaxConnectionLifeTime`` + - ``MaxConnectionLifeTime`` - | The length of time a connection can be pooled before expiring. | | **Data Type**: ``TimeSpan`` | **Default**: 30 minutes - - ``MaxConnectionLifeTime`` | **Connection URI Example**: ``maxLifetimeMS=50000`` * - ``MaxConnectionPoolSize`` + - ``MaxConnectionPoolSize`` - | The greatest number of clients or connections the driver can create in its | connection pool. This count includes connections in use. | | **Data Type**: {+int-data-type+} | **Default**: ``100`` - - ``MaxConnectionPoolSize`` | **Connection URI Example**: ``maxPoolSize=150`` * - ``MinConnectionPoolSize`` + - ``MinConnectionPoolSize`` - | The number of connections the driver should create and keep in the connection | pool even when no operations are occurring. This count includes connections | in use. | | **Data Type**: {+int-data-type+} | **Default**: ``0`` - - ``MinConnectionPoolSize`` | **Connection URI Example**: ``minPoolSize=1`` * - ``ReadConcern`` + - {+not-available+} - | The client's default read concern. | See :ref:`read concern ` for more information. | | **Data Type**: `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ | **Default**: ``ReadConcern.Default`` - - {+not-available+} | **Connection URI Example**: ``readConcernLevel=local`` * - ``ReadEncoding`` + - {+not-available+} - | The UTF-8 encoding to use for string deserialization. | Strict encoding will throw an exception when an invalid UTF-8 byte sequence | is encountered. | | **Data Type**: ``UTF8Encoding`` | **Default**: Strict encoding - - {+not-available+} | **Connection URI Example**: {+not-available+} * - ``ReadPreference`` + - ``ReadPreference`` - | The client's default read-preference settings. ``MaxStaleness`` represents the | longest replication lag, in wall-clock time, that a secondary can experience and | still be eligible for server selection. Specifying ``-1`` means no maximum. @@ -386,7 +366,6 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ | **Default**: ``ReadPreference.Primary`` - - ``ReadPreference`` | **Connection URI Example**: .. code-block:: none @@ -401,25 +380,24 @@ options. These properties are listed in the ``MongoUrl`` column of the table. The order of the tags in the URI determines the order for read preference. You can use this parameter only if the read-preference mode is not ``primary``. - - * - ``RetryReads`` + - ``RetryReads`` - | Enables retryable reads. | | **Data Type**: {+bool-data-type+} | **Default**: ``true`` - - ``RetryReads`` | **Connection URI Example**: ``retryReads=false`` * - ``RetryWrites`` + - ``RetryWrites`` - | Enables retryable writes. | | **Data Type**: {+bool-data-type+} | **Default**: ``true`` - - ``RetryWrites`` | **Connection URI Example**: ``retryWrites=false`` * - ``Scheme`` + - ``Scheme`` - | Specifies whether to use the standard connection string format (``MongoDB``) | or the DNS seed list format (``MongoDBPlusSrv``). | See :manual:`the MongoDB Manual` for more @@ -431,28 +409,28 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ConnectionStringScheme.html>`__ | **Default**: ``ConnectionStringScheme.MongoDB`` - - ``Scheme`` | **Connection URI Example**: ``mongodb+srv://`` * - ``Server`` + - ``Server`` - | The host and port number where MongoDB is running. | | **Data Type**: `MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__ | **Default**: ``localhost:27017`` - - ``Server`` | **Connection URI Example**: ``mongodb://sample.host:27017`` * - ``ServerApi`` + - {+not-available+} - | Allows opting into Stable API versioning. See | :manual:`the MongoDB Manual` for more information about | Stable API versioning. | | **Data Type**: `ServerApi <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerApi.html>`__ | **Default**: ``null`` - - {+not-available+} | **Connection URI Example**: {+not-available+} * - ``ServerMonitoringMode`` + - ``ServerMonitoringMode`` - | Specifies the server monitoring protocol to use. When | this option is set to ``Auto``, the monitoring mode is determined | by the environment in which the driver is running. The driver @@ -461,35 +439,35 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Servers.ServerMonitoringMode.html>`__ | **Default**: ``Auto`` - - ``ServerMonitoringMode`` | **Connection URI Example**: ``serverMonitoringMode=poll`` * - ``Servers`` + - ``Servers`` - | The cluster members where MongoDB is running. | | **Data Type**: IEnumerable<`MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__> | **Default**: ``localhost:27017`` - - ``Servers`` | **Connection URI Example**: ``mongodb://sample.host1:27017,sample.host2:27017`` * - ``ServerSelectionTimeout`` + - ``ServerSelectionTimeout`` - | The length of time the driver tries to select a server before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: 30 seconds - - ``ServerSelectionTimeout`` | **Connection URI Example**: ``serverSelectionTimeoutMS=15000`` * - ``SocketTimeout`` + - ``SocketTimeout`` - | The length of time the driver tries to send or receive on a socket before | timing out. | | **Data Type**: ``TimeSpan`` | **Default**: OS default - - ``SocketTimeout`` | **Connection URI Example**: ``socketTimeoutMS=0`` * - ``SrvMaxHosts`` + - ``SrvMaxHosts`` - | The greatest number of SRV results to randomly select when initially populating | the seedlist or, during SRV polling, adding new hosts to the topology. | @@ -499,10 +477,10 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: {+int-data-type+} | **Default**: ``0`` - - ``SrvMaxHosts`` | **Connection URI Example**: ``srvMaxHosts=3`` * - ``SslSettings`` + - {+not-available+} - | TLS/SSL options, including client certificates, revocation handling, and | enabled and disabled TLS/SSL protocols. | @@ -512,60 +490,53 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | | **Data Type**: `SslSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SslSettings.html>`__ | **Default**: ``null`` - - {+not-available+} | **Connection URI Example**: ``tlsDisableCertificateRevocationCheck=false`` * - ``TranslationOptions`` + - {+not-available+} - | Specifies options, such as the {+mdb-server+} version, for translating LINQ | queries to the Query API. | | **Data Type**: `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ExpressionTranslationOptions.html>`__ | **Default**: ``null`` - - {+not-available+} | **Connection URI Example**: {+not-available+} * - ``UseTls`` + - ``UseTls`` - | Specifies whether to require TLS for connections to the server. If you use | a scheme of ``"mongodb+srv"`` or specify other TLS options, | this option defaults to ``true``. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``UseTls`` | **Connection URI Example**: ``tls=true`` * - ``WaitQueueTimeout`` + - ``WaitQueueTimeout`` - | The length of time the driver tries to check out a connection from a | server's connection pool before timing out. | | **Data Type**: ``TimeSpan`` | **Default**: 2 minutes - - ``WaitQueueTimeout`` | **Connection URI Example**: ``waitQueueTimeoutMS=0`` * - ``WriteConcern`` + - ``GetWriteConcern(bool)`` - | The default write-concern settings, including write timeout and | journaling, for the client. | See :ref:`write concern ` for more information. | | **Data Type**: `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ | **Default**: ``WriteConcern.Acknowledged`` - - ``GetWriteConcern(bool)`` | **Connection URI Example**: ``w=majority&wTimeoutMS=0&journal=true`` * - ``WriteEncoding`` + - {+not-available+} - | Specifies whether UTF-8 string serialization is strict or lenient. With strict | encoding, the driver will throw an exception when it encounters an invalid | UTF-8 byte sequence. | | **Data Type**: ``UTF8Encoding`` | **Default**: Strict encoding - - {+not-available+} | **Connection URI Example**: {+not-available+} -.. tip:: Other MongoUrl Members - - The ``MongoUrl`` class contains other methods and read-only properties that you can - use to retrieve information about your connection. For a full list, see - `MongoUrl <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrl.html>`__ in the - API documentation. \ No newline at end of file From 3840080a85f18a8bc7f0618ca3827f505913ef9a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 12:27:17 -0500 Subject: [PATCH 05/32] test --- source/connect/connection-options.txt | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 9f3908b4..e1b52dde 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -119,7 +119,7 @@ options. These properties are listed in the ``MongoUrl`` column of the table. .. list-table:: :header-rows: 1 - :widths: 20 20 60 + :widths: 25 20 55 * - ``MongoClientSettings`` Property - ``MongoUrlBuilder`` Property @@ -148,10 +148,6 @@ options. These properties are listed in the ``MongoUrl`` column of the table. | **Default**: ``null`` | **Connection URI Example**: ``appName=yourApp`` - - - - * - ``AutoEncryptionOptions`` - {+not-available+} - | Settings for automatic client-side encryption. @@ -190,10 +186,10 @@ options. These properties are listed in the ``MongoUrl`` column of the table. * - | ``Credential`` | | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ - - | - ``AuthenticationMechanism`` - | - - **Data Type**: {+string-data-type+} - | - ``AuthenticationMechanismProperties`` - | - - **Data Type**: ``IEnumerable>`` + - - ``AuthenticationMechanism`` + - - **Data Type**: {+string-data-type+} + - ``AuthenticationMechanismProperties`` + - - **Data Type**: ``IEnumerable>`` - | Settings for how the driver authenticates to the server. This includes | authentication credentials, mechanism, source, and other settings. | From 778b78bf2a3a7499e22d9ca79c03c6a080bc6ce1 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 13:17:42 -0500 Subject: [PATCH 06/32] test --- source/connect/connection-options.txt | 49 ++++++++++++++++----------- 1 file changed, 30 insertions(+), 19 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index e1b52dde..3412c1a4 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -117,13 +117,38 @@ options. These properties are listed in the ``MongoUrl`` column of the table. using a ``MongoClientSettings`` object for a time duration, use the appropriate ``TimeSpan`` value. +Replica Set Options +~~~~~~~~~~~~~~~~~~~ + +DirectConnection +```````````````` +Specifies whether to force dispatch **all** operations to the host. +If you specify this option, the driver doesn't accept the +:manual:`DNS seed list connection format. ` +You must use the :manual:`standard connection URI format ` +instead. The default value is ``false``. + +This property must be set to ``false`` if you specify more than one +host name. + .. list-table:: :header-rows: 1 - :widths: 25 20 55 + :widths: 40 40 20 + + * - ``MongoClientSettings`` + - ``MongoUrlBuilder`` + - Connection URI - * - ``MongoClientSettings`` Property - - ``MongoUrlBuilder`` Property - - Description + * - ``settings.DirectConnection = true;`` + - ``builder.DirectConnection = true;`` + - ``directConnection=true`` + + * - **ReplicaSetName** + - | The name of the replica set to connect to. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``null`` + | **Connection URI Example**: ``replicaSet=yourReplicaSet`` * - ``AllowInsecureTls`` - ``AllowInsecureTls`` @@ -208,21 +233,7 @@ options. These properties are listed in the ``MongoUrl`` column of the table. &authMechanismProperties=SERVICE_NAME:other,REALM:otherrealm &authSource=$external - * - ``DirectConnection`` - - ``DirectConnection`` - - | Specifies whether to force dispatch **all** operations to the host. - | - | If you specify this option, the driver doesn't accept the - | :manual:`DNS seed list connection format. ` - | You must use the :manual:`standard connection URI format ` - | instead. - | - | This property must be set to ``false`` if you specify more than one - | host name. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: ``directConnection=true`` + * - ``HeartbeatInterval`` - ``HeartbeatInterval`` From 499a44ded7738306e23be3211788fb0e0b0ca43a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 13:33:18 -0500 Subject: [PATCH 07/32] test tabs --- source/connect/connection-options.txt | 92 ++++++++++++++----- .../connection-options/directConnection.rst | 8 ++ .../connection-options/replicaSetName.rst | 1 + 3 files changed, 80 insertions(+), 21 deletions(-) create mode 100644 source/includes/fundamentals/connection-options/directConnection.rst create mode 100644 source/includes/fundamentals/connection-options/replicaSetName.rst diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 3412c1a4..edd8cc2b 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -120,35 +120,85 @@ options. These properties are listed in the ``MongoUrl`` column of the table. Replica Set Options ~~~~~~~~~~~~~~~~~~~ -DirectConnection -```````````````` -Specifies whether to force dispatch **all** operations to the host. -If you specify this option, the driver doesn't accept the -:manual:`DNS seed list connection format. ` -You must use the :manual:`standard connection URI format ` -instead. The default value is ``false``. +.. tabs:: -This property must be set to ``false`` if you specify more than one -host name. + .. tab:: MongoClientSettings + :tabid: mongo-client-settings -.. list-table:: - :header-rows: 1 - :widths: 40 40 20 + ReplicaSetName + `````````````` - * - ``MongoClientSettings`` - - ``MongoUrlBuilder`` - - Connection URI + .. include:: /includes/fundamentals/connection-options/replicaSetName.rst + + .. code-block:: none + :copyable: true - * - ``settings.DirectConnection = true;`` - - ``builder.DirectConnection = true;`` - - ``directConnection=true`` + var settings = new MongoClientSettings(); + settings.ReplicaSetName = "yourReplicaSet"; + + DirectConnection + ```````````````` + + .. include:: /includes/fundamentals/connection-options/directConnection.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.DirectConnection = true; + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + ReplicaSetName + `````````````` + + .. include:: /includes/fundamentals/connection-options/replicaSetName.rst + + .. code-block:: none + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.ReplicaSetName = "yourReplicaSet"; + + DirectConnection + ```````````````` + + .. include:: /includes/fundamentals/connection-options/directConnection.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.DirectConnection = true; + + .. tab:: Connection URI + :tabid: connection-uri + + replicaSet + `````````` + + .. include:: /includes/fundamentals/connection-options/replicaSetName.rst + + .. code-block:: none + :copyable: true + + mongodb://localhost:27017/?replicaSet=yourReplicaSet + + directConnection + ```````````````` + + .. include:: /includes/fundamentals/connection-options/directConnection.rst + + .. code-block:: none + :copyable: true + + mongodb://localhost:27017/?directConnection=true * - **ReplicaSetName** - - | The name of the replica set to connect to. + - | | | **Data Type**: {+string-data-type+} - | **Default**: ``null`` - | **Connection URI Example**: ``replicaSet=yourReplicaSet`` * - ``AllowInsecureTls`` - ``AllowInsecureTls`` diff --git a/source/includes/fundamentals/connection-options/directConnection.rst b/source/includes/fundamentals/connection-options/directConnection.rst new file mode 100644 index 00000000..bc69995d --- /dev/null +++ b/source/includes/fundamentals/connection-options/directConnection.rst @@ -0,0 +1,8 @@ +Specifies whether to force dispatch **all** operations to the host. +If you specify this option, the driver doesn't accept the +:manual:`DNS seed list connection format. ` +You must use the :manual:`standard connection URI format ` +instead. The default value is ``false``. + +This property must be set to ``false`` if you specify more than one +host name. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/replicaSetName.rst b/source/includes/fundamentals/connection-options/replicaSetName.rst new file mode 100644 index 00000000..8c085fc9 --- /dev/null +++ b/source/includes/fundamentals/connection-options/replicaSetName.rst @@ -0,0 +1 @@ +The name of the replica set to connect to. The default value is ``null``. \ No newline at end of file From f5e64601f4342fdaf46e456678e9b113c1985932 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 13:46:02 -0500 Subject: [PATCH 08/32] preview --- source/connect/connection-options.txt | 73 +++++++++++++------ .../connection-options/allowInsecureTls.rst | 7 ++ 2 files changed, 58 insertions(+), 22 deletions(-) create mode 100644 source/includes/fundamentals/connection-options/allowInsecureTls.rst diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index edd8cc2b..bb8e7e3f 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -118,7 +118,7 @@ options. These properties are listed in the ``MongoUrl`` column of the table. ``TimeSpan`` value. Replica Set Options -~~~~~~~~~~~~~~~~~~~ +------------------- .. tabs:: @@ -126,7 +126,7 @@ Replica Set Options :tabid: mongo-client-settings ReplicaSetName - `````````````` + ~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/replicaSetName.rst @@ -137,7 +137,7 @@ Replica Set Options settings.ReplicaSetName = "yourReplicaSet"; DirectConnection - ```````````````` + ~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/directConnection.rst @@ -151,7 +151,7 @@ Replica Set Options :tabid: mongo-url-builder ReplicaSetName - `````````````` + ~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/replicaSetName.rst @@ -162,7 +162,7 @@ Replica Set Options builder.ReplicaSetName = "yourReplicaSet"; DirectConnection - ```````````````` + ~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/directConnection.rst @@ -176,7 +176,7 @@ Replica Set Options :tabid: connection-uri replicaSet - `````````` + ~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/replicaSetName.rst @@ -186,7 +186,7 @@ Replica Set Options mongodb://localhost:27017/?replicaSet=yourReplicaSet directConnection - ```````````````` + ~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/directConnection.rst @@ -195,22 +195,51 @@ Replica Set Options mongodb://localhost:27017/?directConnection=true - * - **ReplicaSetName** - - | - | - | **Data Type**: {+string-data-type+} +TLS Options +----------- - * - ``AllowInsecureTls`` - - ``AllowInsecureTls`` - - | Specifies whether to relax TLS constraints as much as possible. This can include - | allowing invalid certificates or hostname mismatches. - | - | If this property is set to ``true`` and ``SslSettings.CheckCertificateRevocation`` - | is set to ``false``, the {+driver-short+} will throw an exception. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: ``tlsInsecure=true`` +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + AllowInsecureTls + ~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.AllowInsecureTls = true; + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + AllowInsecureTls + ~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.AllowInsecureTls = true; + + .. tab:: Connection URI + :tabid: connection-uri + + tlsInsecure + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst + + .. code-block:: none + :copyable: true + + mongodb://localhost:27017/?tlsInsecure=true * - ``ApplicationName`` - ``ApplicationName`` diff --git a/source/includes/fundamentals/connection-options/allowInsecureTls.rst b/source/includes/fundamentals/connection-options/allowInsecureTls.rst new file mode 100644 index 00000000..2c942bd2 --- /dev/null +++ b/source/includes/fundamentals/connection-options/allowInsecureTls.rst @@ -0,0 +1,7 @@ +Specifies whether to relax TLS constraints as much as possible. This can include +allowing invalid certificates or hostname mismatches. The default value is ``false``. + +If this property is set to ``true`` and ``SslSettings.CheckCertificateRevocation`` +is set to ``false``, the {+driver-short+} will throw an exception. + +The following code example shows how to set this option to ``true``: \ No newline at end of file From 648eaaaaf01394c8b70aeb1200bb8f7899afbd4d Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 13:58:49 -0500 Subject: [PATCH 09/32] test --- source/connect/connection-options.txt | 68 +++++++++------------------ 1 file changed, 23 insertions(+), 45 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index bb8e7e3f..c4eec825 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -48,6 +48,9 @@ and the ``tls`` option with a value of ``true``: :start-after: // start local connection config :end-before: // end local connection config +To learn more about the options that you can specify in a connection URI, see +:manual:`` in the {+mdb-server+} manual. + .. _csharp-mongo-client-settings: ----------------------------- @@ -120,15 +123,15 @@ options. These properties are listed in the ``MongoUrl`` column of the table. Replica Set Options ------------------- +ReplicaSetName +~~~~~~~~~~~~~~ + +.. include:: /includes/fundamentals/connection-options/replicaSetName.rst + .. tabs:: .. tab:: MongoClientSettings :tabid: mongo-client-settings - - ReplicaSetName - ~~~~~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/replicaSetName.rst .. code-block:: none :copyable: true @@ -136,65 +139,40 @@ Replica Set Options var settings = new MongoClientSettings(); settings.ReplicaSetName = "yourReplicaSet"; - DirectConnection - ~~~~~~~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/directConnection.rst - - .. code-block:: csharp - :copyable: true - - var settings = new MongoClientSettings(); - settings.DirectConnection = true; - .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - ReplicaSetName - ~~~~~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/replicaSetName.rst - .. code-block:: none :copyable: true var builder = new MongoUrlBuilder(); builder.ReplicaSetName = "yourReplicaSet"; - DirectConnection - ~~~~~~~~~~~~~~~~ +DirectConnection +~~~~~~~~~~~~~~~~ - .. include:: /includes/fundamentals/connection-options/directConnection.rst - - .. code-block:: csharp - :copyable: true +.. include:: /includes/fundamentals/connection-options/directConnection.rst - var builder = new MongoUrlBuilder(); - builder.DirectConnection = true; - - .. tab:: Connection URI - :tabid: connection-uri - - replicaSet - ~~~~~~~~~~ +.. tabs:: - .. include:: /includes/fundamentals/connection-options/replicaSetName.rst + .. tab:: MongoClientSettings + :tabid: mongo-client-settings - .. code-block:: none + .. code-block:: csharp :copyable: true - mongodb://localhost:27017/?replicaSet=yourReplicaSet + var settings = new MongoClientSettings(); + settings.DirectConnection = true; - directConnection - ~~~~~~~~~~~~~~~~ + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder - .. include:: /includes/fundamentals/connection-options/directConnection.rst - - .. code-block:: none + .. code-block:: csharp :copyable: true - mongodb://localhost:27017/?directConnection=true - + var builder = new MongoUrlBuilder(); + builder.DirectConnection = true; + TLS Options ----------- From e1ffb6ced10692c21089f812fdc590fce0aed830 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Mon, 5 Dec 2022 12:50:22 -0800 Subject: [PATCH 10/32] empty repo From c34f7bdb24616dc3f0234c3d42cf657c29190c1a Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Tue, 17 Jan 2023 14:30:29 -0800 Subject: [PATCH 11/32] autobuilder From ac3439c2e8775f348c430b1d8ae97702d23e1334 Mon Sep 17 00:00:00 2001 From: Mike Woofter Date: Mon, 5 Dec 2022 16:28:36 -0600 Subject: [PATCH 12/32] autobuilder From fad0d5bfa9040ed42adbab728f5b119dc6308b5c Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 9 May 2025 15:09:45 -0500 Subject: [PATCH 13/32] wip --- source/connect/connection-options.txt | 765 +++++++++++------- .../connection-options/compressors.rst | 3 + .../connection-options/connectTimeout.rst | 2 + .../connection-options/maxConnectin.rst | 2 + .../maxConnectionIdleTime.rst | 2 + .../maxConnectionLifetime.rst | 2 + .../maxConnectionPoolSize.rst | 2 + .../minConnectionPoolSize.rst | 3 + .../connection-options/socketTimeout.rst | 2 + .../connection-options/useTls.rst | 3 + .../connection-options/waitQueueTimeout.rst | 2 + 11 files changed, 515 insertions(+), 273 deletions(-) create mode 100644 source/includes/fundamentals/connection-options/compressors.rst create mode 100644 source/includes/fundamentals/connection-options/connectTimeout.rst create mode 100644 source/includes/fundamentals/connection-options/maxConnectin.rst create mode 100644 source/includes/fundamentals/connection-options/maxConnectionIdleTime.rst create mode 100644 source/includes/fundamentals/connection-options/maxConnectionLifetime.rst create mode 100644 source/includes/fundamentals/connection-options/maxConnectionPoolSize.rst create mode 100644 source/includes/fundamentals/connection-options/minConnectionPoolSize.rst create mode 100644 source/includes/fundamentals/connection-options/socketTimeout.rst create mode 100644 source/includes/fundamentals/connection-options/useTls.rst create mode 100644 source/includes/fundamentals/connection-options/waitQueueTimeout.rst diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index c4eec825..02beb3a2 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -123,41 +123,30 @@ options. These properties are listed in the ``MongoUrl`` column of the table. Replica Set Options ------------------- -ReplicaSetName -~~~~~~~~~~~~~~ - -.. include:: /includes/fundamentals/connection-options/replicaSetName.rst - .. tabs:: .. tab:: MongoClientSettings :tabid: mongo-client-settings - - .. code-block:: none - :copyable: true - - var settings = new MongoClientSettings(); - settings.ReplicaSetName = "yourReplicaSet"; - + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder + ReplicaSetName + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/replicaSetName.rst + .. code-block:: none :copyable: true - var builder = new MongoUrlBuilder(); - builder.ReplicaSetName = "yourReplicaSet"; + var settings = new MongoClientSettings(); + settings.ReplicaSetName = "yourReplicaSet"; -DirectConnection -~~~~~~~~~~~~~~~~ + DirectConnection + ~~~~~~~~~~~~~~~~ -.. include:: /includes/fundamentals/connection-options/directConnection.rst - -.. tabs:: + .. include:: /includes/fundamentals/connection-options/directConnection.rst - .. tab:: MongoClientSettings - :tabid: mongo-client-settings - .. code-block:: csharp :copyable: true @@ -167,6 +156,22 @@ DirectConnection .. tab:: MongoUrlBuilder :tabid: mongo-url-builder + ReplicaSetName + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/replicaSetName.rst + + .. code-block:: none + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.ReplicaSetName = "yourReplicaSet"; + + DirectConnection + ~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/directConnection.rst + .. code-block:: csharp :copyable: true @@ -192,6 +197,41 @@ TLS Options var settings = new MongoClientSettings(); settings.AllowInsecureTls = true; + SslSettings + ~~~~~~~~~~~ + + TLS/SSL options, including client certificates, revocation handling, and + enabled and disabled TLS/SSL protocols. The default value is ``null``. + + If ``SslSettings.CheckCertificateRevocation`` is set to ``false`` and + ``AllowInsecureTls`` is set to ``true``, the {+driver-short+} throws + an exception. + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.SslSettings = new SslSettings() + { + CheckCertificateRevocation = false, + ClientCertificateCollection = new X509CertificateCollection() { ... }, + ClientCertificateSelectionCallback = new LocalCertificateSelectionCallback() { ... }, + ClientCertificates = new List() { ... }, + EnabledSslProtocols = SslProtocols.Tls13, + ServerCertificateValidationCallback = new RemoteCertificateValidationCallback() { ... } + }; + + UseTls + ~~~~~~ + + .. include:: /includes/fundamentals/connection-options/useTls.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.UseTls = true; + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -206,66 +246,351 @@ TLS Options var builder = new MongoUrlBuilder(); builder.AllowInsecureTls = true; - .. tab:: Connection URI - :tabid: connection-uri + UseTls + ~~~~~~ + + .. include:: /includes/fundamentals/connection-options/useTls.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.UseTls = true; + +Timeout Options +--------------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + ConnectTimeout + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/connectTimeout.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.ConnectTimeout = TimeSpan.FromSeconds(60); + + SocketTimeout + ~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/socketTimeout.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.SocketTimeout = TimeSpan.FromSeconds(60); + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + ConnectTimeout + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/connectTimeout.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.ConnectTimeout = TimeSpan.FromSeconds(60); + + SocketTimeout + ~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/socketTimeout.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.SocketTimeout = TimeSpan.FromSeconds(60); - tlsInsecure +Compression Options +------------------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + Compressors ~~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst - .. code-block:: none + .. include:: /includes/fundamentals/connection-options/compressors.rst + + .. code-block:: csharp :copyable: true - mongodb://localhost:27017/?tlsInsecure=true + var settings = new MongoClientSettings(); + settings.Compressors = new List() + { + new CompressorConfiguration(CompressorType.Zlib), + new CompressorConfiguration(CompressorType.Snappy) + }; - * - ``ApplicationName`` - - ``ApplicationName`` - - | The app name the driver passes to the server in the client metadata as part of - | the connection handshake. The server prints this value to the MongoDB logs once - | the connection is established. The value is also recorded in the slow query logs - | and profile collections. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``null`` - | **Connection URI Example**: ``appName=yourApp`` + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + Compressors + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/compressors.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.Compressors = new List() + { + new CompressorConfiguration(CompressorType.Zlib), + new CompressorConfiguration(CompressorType.Snappy) + }; + +Connection Pool Options +----------------------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + MaxConnecting + ~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnecting.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.MaxConnecting = 3; + + MaxConnectionIdleTime + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnectionIdleTime.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(8); + + MaxConnectionLifeTime + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnectionLifeTime.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.MaxConnectionLifeTime = TimeSpan.FromMinutes(40); + + MaxConnectionPoolSize + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnectionPoolSize.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.MaxConnectionPoolSize = 150; + + MinConnectionPoolSize + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/minConnectionPoolSize.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.MinConnectionPoolSize = 3; + + WaitQueueTimeout + ~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/waitQueueTimeout.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.WaitQueueTimeout = TimeSpan.FromSeconds(30); + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + MaxConnecting + ~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnecting.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + settings.MongoUrlBuilder = 3; + + MaxConnectionIdleTime + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnectionIdleTime.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.MaxConnectionIdleTime = TimeSpan.FromMinutes(8); + + MaxConnectionLifeTime + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnectionLifeTime.rst + + .. code-block:: csharp + :copyable: true + + var builder = new MongoUrlBuilder(); + builder.MaxConnectionLifeTime = TimeSpan.FromMinutes(40); + + MaxConnectionPoolSize + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/maxConnectionPoolSize.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.MaxConnectionPoolSize = 150; + + MinConnectionPoolSize + ~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/minConnectionPoolSize.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.MinConnectionPoolSize = 3; + + WaitQueueTimeout + ~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/waitQueueTimeout.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.WaitQueueTimeout = TimeSpan.FromSeconds(30); + +Write Concern Options +--------------------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + WriteConcern + ~~~~~~~~~~~~ + + The default write-concern settings, including write timeout and + journaling, for the client. The default value is ``WriteConcern.Acknowledged``. + See :ref:`write concern ` for more information. + + .. code-block:: csharp + :copyable: true + + public void WriteConcern() + { + var settings = new MongoClientSettings(); + settings.WriteConcern = new WriteConcern( + w: 1, + wTimeout: new TimeSpan(0, 0, 0, 30, 0), + fsync: true, + journal: true + ); + } + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + - ``GetWriteConcern(bool)`` - * - ``AutoEncryptionOptions`` - - {+not-available+} - - | Settings for automatic client-side encryption. - | - | **Data Type**: `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Encryption.AutoEncryptionOptions.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} - * - ``ClusterConfigurator`` +Read Concern Options +-------------------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + ReadConcern - {+not-available+} - - | Low-level configuration options for sockets, TLS, cluster, and others. + - | The client's default read concern. + | See :ref:`read concern ` for more information. | - | **Data Type**: Action<`ClusterBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.html>`__> - | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} + | **Data Type**: `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ + | **Default**: ``ReadConcern.Default`` + | **Connection URI Example**: ``readConcernLevel=local`` - * - ``Compressors`` - - ``Compressors`` - - | The preferred compression types, in order, for wire-protocol messages sent to - | or received from the server. The driver uses the first of these compression types - | that the server supports. - | - | **Data Type**: `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.CompressorConfiguration.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: ``compressors=snappy,zstd`` +Read Preference Options +----------------------- +.. tabs:: - * - ``ConnectTimeout`` - - ``ConnectTimeout`` - - | The length of time the driver tries to establish a single TCP socket connection - | to the server before timing out. + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + ReadPreference + - ``ReadPreference`` + - | The client's default read-preference settings. ``MaxStaleness`` represents the + | longest replication lag, in wall-clock time, that a secondary can experience and + | still be eligible for server selection. Specifying ``-1`` means no maximum. + | See :ref:`read preference ` for more information. | - | **DataType**: ``TimeSpan`` - | **Default**: 30 seconds - | **Connection URI Example**: ``connectTimeoutMS=0`` + | **Data Type**: `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ + | **Default**: ``ReadPreference.Primary`` + | **Connection URI Example**: + + .. code-block:: none + :copyable: false - * - | ``Credential`` + readPreference=primaryPreferred + &maxStalenessSeconds=90 + &readPreferenceTags=dc:ny,rack:1 + + | You can include the ``readPreferenceTags`` parameter in the connection URI more + than once. If you do, the client treats each instance as a separate tag set. + The order of the tags in the URI determines the order for read preference. You can + use this parameter only if the read-preference mode is not ``primary``. + +Authentication Options +---------------------- +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + * - | ``Credential`` | | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ - - ``AuthenticationMechanism`` @@ -281,18 +606,35 @@ TLS Options | authentication mechanisms. | | **Default**: ``null`` - | **Connection URI Example**: - - .. code-block:: none - :copyable: false - mongodb://user1:password1&authMechanism=GSSAPI - &authMechanismProperties=SERVICE_NAME:other,REALM:otherrealm - &authSource=$external +Server Selection and Discovery Options +-------------------------------------- +.. tabs:: + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + LocalThreshold + - ``LocalThreshold`` + - | The latency window for server eligibility. If a server's round trip takes longer + | than the fastest server's round-trip time plus this value, the server isn't + | eligible for selection. + | + | **Data Type**: ``TimeSpan`` + | **Default**: 15 milliseconds + | **Connection URI Example**: ``localThresholdMS=0`` + ServerSelectionTimeout + - ``ServerSelectionTimeout`` + - | The length of time the driver tries to select a server before timing out. + | + | **Data Type**: ``TimeSpan`` + | **Default**: 30 seconds + | **Connection URI Example**: ``serverSelectionTimeoutMS=15000`` - * - ``HeartbeatInterval`` + HeartbeatInterval - ``HeartbeatInterval`` - | The interval between regular server-monitoring checks. Must be greater than or | equal to 500 milliseconds. @@ -301,7 +643,7 @@ TLS Options | **Default**: 10 seconds | **Connection URI Example**: ``heartbeatFrequencyMS=5000`` - * - ``HeartbeatTimeout`` + HeartbeatTimeout - ``HeartbeatTimeout`` - | The length of time a monitoring socket can be idle before timing out. | @@ -309,24 +651,40 @@ TLS Options | **Default**: Same value as ``ConnectTimeout`` | **Connection URI Example**: ``heartbeatTimeoutMS=5000`` - * - ``IPv6`` - - ``IPv6`` - - | Specifies whether the host address is in IPv6 format. +Miscellaneous Options +--------------------- +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + ApplicationName + - ``ApplicationName`` + - | The app name the driver passes to the server in the client metadata as part of + | the connection handshake. The server prints this value to the MongoDB logs once + | the connection is established. The value is also recorded in the slow query logs + | and profile collections. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``null`` + + RetryReads + - ``RetryReads`` + - | Enables retryable reads. | | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: ``ipv6=true`` + | **Default**: ``true`` - * - ``IsFrozen`` - - {+not-available+} - - | Indicates whether the settings have been frozen. Frozen settings can't be changed. - | This option is read-only. + RetryWrites + - ``RetryWrites`` + - | Enables retryable writes. | | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: {+not-available+} + | **Default**: ``true`` - * - ``LoadBalanced`` + LoadBalanced - ``LoadBalanced`` - | Specifies whether the driver is connecting to a load balancer. You can set this | property to ``true`` only if: @@ -338,80 +696,62 @@ TLS Options | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - | **Connection URI Example**: ``loadBalanced=true`` - * - ``LocalThreshold`` - - ``LocalThreshold`` - - | The latency window for server eligibility. If a server's round trip takes longer - | than the fastest server's round-trip time plus this value, the server isn't - | eligible for selection. + SrvMaxHosts + - ``SrvMaxHosts`` + - | The greatest number of SRV results to randomly select when initially populating + | the seedlist or, during SRV polling, adding new hosts to the topology. | - | **Data Type**: ``TimeSpan`` - | **Default**: 15 milliseconds - | **Connection URI Example**: ``localThresholdMS=0`` + | You can use this property only if the connection-string scheme is set + | to ``ConnectionStringScheme.MongoDBPlusSrv``. You cannot use it when connecting + | to a replica set. + | + | **Data Type**: {+int-data-type+} + | **Default**: ``0`` + | **Connection URI Example**: ``srvMaxHosts=3`` - * - ``LoggingSettings`` + AutoEncryptionOptions - {+not-available+} - - | The settings used for :ref:`logging. ` + - | Settings for automatic client-side encryption. | - | **Data Type**: `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.LoggingSettings.html>`__ + | **Data Type**: `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Encryption.AutoEncryptionOptions.html>`__ | **Default**: ``null`` | **Connection URI Example**: {+not-available+} - * - ``MaxConnecting`` - - ``MaxConnecting`` - - | The greatest number of connections a driver's connection pool may be - | establishing concurrently. - | - | **Data Type**: {+int-data-type+} - | **Default**: ``2`` - | **Connection URI Example**: ``maxConnecting=3`` - - * - ``MaxConnectionIdleTime`` - - ``MaxConnectionIdleTime`` - - | The length of time a connection can be idle before the driver closes it. + ClusterConfigurator + - {+not-available+} + - | Low-level configuration options for sockets, TLS, cluster, and others. | - | **Data Type**: ``TimeSpan`` - | **Default**: 10 minutes - | **Connection URI Example**: ``maxIdleTimeMS=300000`` + | **Data Type**: Action<`ClusterBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.html>`__> + | **Default**: ``null`` + | **Connection URI Example**: {+not-available+} - * - ``MaxConnectionLifeTime`` - - ``MaxConnectionLifeTime`` - - | The length of time a connection can be pooled before expiring. + IPv6 + - ``IPv6`` + - | Specifies whether the host address is in IPv6 format. | - | **Data Type**: ``TimeSpan`` - | **Default**: 30 minutes - | **Connection URI Example**: ``maxLifetimeMS=50000`` + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + | **Connection URI Example**: ``ipv6=true`` - * - ``MaxConnectionPoolSize`` - - ``MaxConnectionPoolSize`` - - | The greatest number of clients or connections the driver can create in its - | connection pool. This count includes connections in use. - | - | **Data Type**: {+int-data-type+} - | **Default**: ``100`` - | **Connection URI Example**: ``maxPoolSize=150`` - - * - ``MinConnectionPoolSize`` - - ``MinConnectionPoolSize`` - - | The number of connections the driver should create and keep in the connection - | pool even when no operations are occurring. This count includes connections - | in use. + IsFrozen + - {+not-available+} + - | Indicates whether the settings have been frozen. Frozen settings can't be changed. + | This option is read-only. | - | **Data Type**: {+int-data-type+} - | **Default**: ``0`` - | **Connection URI Example**: ``minPoolSize=1`` + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + | **Connection URI Example**: {+not-available+} - * - ``ReadConcern`` + LoggingSettings - {+not-available+} - - | The client's default read concern. - | See :ref:`read concern ` for more information. + - | The settings used for :ref:`logging. ` | - | **Data Type**: `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ - | **Default**: ``ReadConcern.Default`` - | **Connection URI Example**: ``readConcernLevel=local`` + | **Data Type**: `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.LoggingSettings.html>`__ + | **Default**: ``null`` + | **Connection URI Example**: {+not-available+} - * - ``ReadEncoding`` + ReadEncoding - {+not-available+} - | The UTF-8 encoding to use for string deserialization. | Strict encoding will throw an exception when an invalid UTF-8 byte sequence @@ -421,46 +761,7 @@ TLS Options | **Default**: Strict encoding | **Connection URI Example**: {+not-available+} - * - ``ReadPreference`` - - ``ReadPreference`` - - | The client's default read-preference settings. ``MaxStaleness`` represents the - | longest replication lag, in wall-clock time, that a secondary can experience and - | still be eligible for server selection. Specifying ``-1`` means no maximum. - | See :ref:`read preference ` for more information. - | - | **Data Type**: `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ - | **Default**: ``ReadPreference.Primary`` - | **Connection URI Example**: - - .. code-block:: none - :copyable: false - - readPreference=primaryPreferred - &maxStalenessSeconds=90 - &readPreferenceTags=dc:ny,rack:1 - - | You can include the ``readPreferenceTags`` parameter in the connection URI more - than once. If you do, the client treats each instance as a separate tag set. - The order of the tags in the URI determines the order for read preference. You can - use this parameter only if the read-preference mode is not ``primary``. - - * - ``RetryReads`` - - ``RetryReads`` - - | Enables retryable reads. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``true`` - | **Connection URI Example**: ``retryReads=false`` - - * - ``RetryWrites`` - - ``RetryWrites`` - - | Enables retryable writes. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``true`` - | **Connection URI Example**: ``retryWrites=false`` - - * - ``Scheme`` + Scheme - ``Scheme`` - | Specifies whether to use the standard connection string format (``MongoDB``) | or the DNS seed list format (``MongoDBPlusSrv``). @@ -475,7 +776,7 @@ TLS Options | **Default**: ``ConnectionStringScheme.MongoDB`` | **Connection URI Example**: ``mongodb+srv://`` - * - ``Server`` + Server - ``Server`` - | The host and port number where MongoDB is running. | @@ -483,7 +784,7 @@ TLS Options | **Default**: ``localhost:27017`` | **Connection URI Example**: ``mongodb://sample.host:27017`` - * - ``ServerApi`` + ServerApi - {+not-available+} - | Allows opting into Stable API versioning. See | :manual:`the MongoDB Manual` for more information about @@ -493,7 +794,7 @@ TLS Options | **Default**: ``null`` | **Connection URI Example**: {+not-available+} - * - ``ServerMonitoringMode`` + ServerMonitoringMode - ``ServerMonitoringMode`` - | Specifies the server monitoring protocol to use. When | this option is set to ``Auto``, the monitoring mode is determined @@ -505,7 +806,7 @@ TLS Options | **Default**: ``Auto`` | **Connection URI Example**: ``serverMonitoringMode=poll`` - * - ``Servers`` + Servers - ``Servers`` - | The cluster members where MongoDB is running. | @@ -513,50 +814,7 @@ TLS Options | **Default**: ``localhost:27017`` | **Connection URI Example**: ``mongodb://sample.host1:27017,sample.host2:27017`` - * - ``ServerSelectionTimeout`` - - ``ServerSelectionTimeout`` - - | The length of time the driver tries to select a server before timing out. - | - | **Data Type**: ``TimeSpan`` - | **Default**: 30 seconds - | **Connection URI Example**: ``serverSelectionTimeoutMS=15000`` - - * - ``SocketTimeout`` - - ``SocketTimeout`` - - | The length of time the driver tries to send or receive on a socket before - | timing out. - | - | **Data Type**: ``TimeSpan`` - | **Default**: OS default - | **Connection URI Example**: ``socketTimeoutMS=0`` - - * - ``SrvMaxHosts`` - - ``SrvMaxHosts`` - - | The greatest number of SRV results to randomly select when initially populating - | the seedlist or, during SRV polling, adding new hosts to the topology. - | - | You can use this property only if the connection-string scheme is set - | to ``ConnectionStringScheme.MongoDBPlusSrv``. You cannot use it when connecting - | to a replica set. - | - | **Data Type**: {+int-data-type+} - | **Default**: ``0`` - | **Connection URI Example**: ``srvMaxHosts=3`` - - * - ``SslSettings`` - - {+not-available+} - - | TLS/SSL options, including client certificates, revocation handling, and - | enabled and disabled TLS/SSL protocols. - | - | If ``SslSettings.CheckCertificateRevocation`` is set to ``false`` and - | ``AllowInsecureTls`` is set to ``true``, the {+driver-short+} will throw - | an exception. - | - | **Data Type**: `SslSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SslSettings.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: ``tlsDisableCertificateRevocationCheck=false`` - - * - ``TranslationOptions`` + TranslationOptions - {+not-available+} - | Specifies options, such as the {+mdb-server+} version, for translating LINQ | queries to the Query API. @@ -565,42 +823,3 @@ TLS Options | **Default**: ``null`` | **Connection URI Example**: {+not-available+} - * - ``UseTls`` - - ``UseTls`` - - | Specifies whether to require TLS for connections to the server. If you use - | a scheme of ``"mongodb+srv"`` or specify other TLS options, - | this option defaults to ``true``. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: ``tls=true`` - - * - ``WaitQueueTimeout`` - - ``WaitQueueTimeout`` - - | The length of time the driver tries to check out a connection from a - | server's connection pool before timing out. - | - | **Data Type**: ``TimeSpan`` - | **Default**: 2 minutes - | **Connection URI Example**: ``waitQueueTimeoutMS=0`` - - * - ``WriteConcern`` - - ``GetWriteConcern(bool)`` - - | The default write-concern settings, including write timeout and - | journaling, for the client. - | See :ref:`write concern ` for more information. - | - | **Data Type**: `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ - | **Default**: ``WriteConcern.Acknowledged`` - | **Connection URI Example**: ``w=majority&wTimeoutMS=0&journal=true`` - - * - ``WriteEncoding`` - - {+not-available+} - - | Specifies whether UTF-8 string serialization is strict or lenient. With strict - | encoding, the driver will throw an exception when it encounters an invalid - | UTF-8 byte sequence. - | - | **Data Type**: ``UTF8Encoding`` - | **Default**: Strict encoding - | **Connection URI Example**: {+not-available+} - diff --git a/source/includes/fundamentals/connection-options/compressors.rst b/source/includes/fundamentals/connection-options/compressors.rst new file mode 100644 index 00000000..c02bd7d3 --- /dev/null +++ b/source/includes/fundamentals/connection-options/compressors.rst @@ -0,0 +1,3 @@ +The preferred compression types, in order, for wire-protocol messages sent to +or received from the server. The driver uses the first of these compression types +that the server supports. The default value is ``null``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/connectTimeout.rst b/source/includes/fundamentals/connection-options/connectTimeout.rst new file mode 100644 index 00000000..6282d4fd --- /dev/null +++ b/source/includes/fundamentals/connection-options/connectTimeout.rst @@ -0,0 +1,2 @@ +The length of time the driver tries to establish a single TCP socket connection +to the server before timing out. The default value is 30 seconds. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/maxConnectin.rst b/source/includes/fundamentals/connection-options/maxConnectin.rst new file mode 100644 index 00000000..b6ac4280 --- /dev/null +++ b/source/includes/fundamentals/connection-options/maxConnectin.rst @@ -0,0 +1,2 @@ +The greatest number of connections a driver's connection pool may be +establishing concurrently. The default value is ``2``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/maxConnectionIdleTime.rst b/source/includes/fundamentals/connection-options/maxConnectionIdleTime.rst new file mode 100644 index 00000000..1bab20a5 --- /dev/null +++ b/source/includes/fundamentals/connection-options/maxConnectionIdleTime.rst @@ -0,0 +1,2 @@ +The length of time a connection can be idle before the driver closes it. The default +value is 10 minutes. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/maxConnectionLifetime.rst b/source/includes/fundamentals/connection-options/maxConnectionLifetime.rst new file mode 100644 index 00000000..6eeadfe7 --- /dev/null +++ b/source/includes/fundamentals/connection-options/maxConnectionLifetime.rst @@ -0,0 +1,2 @@ +The length of time a connection can be pooled before expiring. The default value is +30 minutes. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/maxConnectionPoolSize.rst b/source/includes/fundamentals/connection-options/maxConnectionPoolSize.rst new file mode 100644 index 00000000..1eeedced --- /dev/null +++ b/source/includes/fundamentals/connection-options/maxConnectionPoolSize.rst @@ -0,0 +1,2 @@ +The greatest number of clients or connections the driver can create in its +connection pool. This count includes connections in use. The default value is ``100``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst b/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst new file mode 100644 index 00000000..08782310 --- /dev/null +++ b/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst @@ -0,0 +1,3 @@ +The number of connections the driver should create and keep in the connection +pool even when no operations are occurring. This count includes connections +in use. The default value is ``0``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/socketTimeout.rst b/source/includes/fundamentals/connection-options/socketTimeout.rst new file mode 100644 index 00000000..56fde85e --- /dev/null +++ b/source/includes/fundamentals/connection-options/socketTimeout.rst @@ -0,0 +1,2 @@ +The length of time the driver tries to send or receive on a socket before +timing out. The default value is set by the operating system. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/useTls.rst b/source/includes/fundamentals/connection-options/useTls.rst new file mode 100644 index 00000000..fe8de021 --- /dev/null +++ b/source/includes/fundamentals/connection-options/useTls.rst @@ -0,0 +1,3 @@ +Specifies whether to require TLS for connections to the server. If you use +a scheme of ``"mongodb+srv"`` or specify other TLS options, +this option defaults to ``true``. Otherwise, it defaults to ``false``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/waitQueueTimeout.rst b/source/includes/fundamentals/connection-options/waitQueueTimeout.rst new file mode 100644 index 00000000..3f48220f --- /dev/null +++ b/source/includes/fundamentals/connection-options/waitQueueTimeout.rst @@ -0,0 +1,2 @@ +The length of time the driver tries to check out a connection from a +server's connection pool before timing out. The default value is two minutes. \ No newline at end of file From cd5a7434f9f8acada9cad5897b389030d8ba2ca8 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 12 May 2025 11:39:24 -0500 Subject: [PATCH 14/32] wip --- source/connect/connection-options.txt | 95 +++++++++++-------- source/connect/mongoclient.txt | 12 +++ .../connection-options/readPreference.rst | 5 + 3 files changed, 73 insertions(+), 39 deletions(-) create mode 100644 source/includes/fundamentals/connection-options/readPreference.rst diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 02beb3a2..309ce1e9 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -529,7 +529,6 @@ Write Concern Options - ``GetWriteConcern(bool)`` - Read Concern Options -------------------- @@ -538,77 +537,94 @@ Read Concern Options .. tab:: MongoClientSettings :tabid: mongo-client-settings + ReadConcern + ~~~~~~~~~~~ + + The client's default read concern. The default value is ``ReadConcern.Default``. + For more information, see :ref:`read concern `. + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.ReadConcern = new ReadConcern(ReadConcernLevel.Local); + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - ReadConcern - - {+not-available+} - - | The client's default read concern. - | See :ref:`read concern ` for more information. - | - | **Data Type**: `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ - | **Default**: ``ReadConcern.Default`` - | **Connection URI Example**: ``readConcernLevel=local`` Read Preference Options ----------------------- + .. tabs:: .. tab:: MongoClientSettings :tabid: mongo-client-settings + ReadPreference + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/readPreference.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.ReadPreference = ReadPreference.SecondaryPreferred; + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - ReadPreference - - ``ReadPreference`` - - | The client's default read-preference settings. ``MaxStaleness`` represents the - | longest replication lag, in wall-clock time, that a secondary can experience and - | still be eligible for server selection. Specifying ``-1`` means no maximum. - | See :ref:`read preference ` for more information. - | - | **Data Type**: `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ - | **Default**: ``ReadPreference.Primary`` - | **Connection URI Example**: - .. code-block:: none - :copyable: false + .. include:: /includes/fundamentals/connection-options/readPreference.rst - readPreference=primaryPreferred - &maxStalenessSeconds=90 - &readPreferenceTags=dc:ny,rack:1 - - | You can include the ``readPreferenceTags`` parameter in the connection URI more - than once. If you do, the client treats each instance as a separate tag set. - The order of the tags in the URI determines the order for read preference. You can - use this parameter only if the read-preference mode is not ``primary``. + .. code-block:: csharp + :copyable: true + var settings = new MongoClientSettings(); + settings.ReadPreference = ReadPreference.SecondaryPreferred; + Authentication Options ---------------------- + .. tabs:: .. tab:: MongoClientSettings :tabid: mongo-client-settings + Credential + ~~~~~~~~~~ + + Settings for how the driver authenticates to the server. This includes + authentication credentials, mechanism, source, and other settings. The default + value is ``null``. + + f you don't specify an authentication mechanism, the driver uses either + ``SCRAM-SHA-1`` or ``SCRAM-SHA-256``, depending on the server version. See + :ref:`authentication mechanisms ` for available + authentication mechanisms. + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.Credential = MongoCredential.CreateScramSha256Credential( + source: "admin", + username: "user", + password: "password" + ); + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - * - | ``Credential`` | | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ - - ``AuthenticationMechanism`` - - **Data Type**: {+string-data-type+} - ``AuthenticationMechanismProperties`` - - **Data Type**: ``IEnumerable>`` - - | Settings for how the driver authenticates to the server. This includes - | authentication credentials, mechanism, source, and other settings. - | - | If you don't specify an authentication mechanism, the driver uses either - | ``SCRAM-SHA-1`` or ``SCRAM-SHA-256``, depending on the server version. See - | :ref:`authentication mechanisms ` for available - | authentication mechanisms. - | - | **Default**: ``null`` + Server Selection and Discovery Options -------------------------------------- + .. tabs:: .. tab:: MongoClientSettings @@ -653,6 +669,7 @@ Server Selection and Discovery Options Miscellaneous Options --------------------- + .. tabs:: .. tab:: MongoClientSettings diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index b2bdff0f..91477847 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -85,6 +85,18 @@ For more information about creating a connection string, see :manual:`Connection Strings ` in the MongoDB Server documentation. +Formats +~~~~~~~ + +The {+driver-short+} provides the following classes for representing connection strings: + +A ``MongoURl`` object represents an immutable connection string. You can construct one +by calling the ``MongoUrl`` constructor and passing a connection string, or by +MongoUrlBuilder +- MongoUrl +- ConnectionString + +You can also just leave it as a string. MongoClient ----------- diff --git a/source/includes/fundamentals/connection-options/readPreference.rst b/source/includes/fundamentals/connection-options/readPreference.rst new file mode 100644 index 00000000..982ab7a9 --- /dev/null +++ b/source/includes/fundamentals/connection-options/readPreference.rst @@ -0,0 +1,5 @@ +The client's default read-preference settings. ``MaxStaleness`` represents the +longest replication lag, in wall-clock time, that a secondary can experience and +still be eligible for server selection. The default value is ``ReadPreference.Primary``. +Specifying ``-1`` means no maximum. +See :ref:`read preference ` for more information. \ No newline at end of file From a5b583f61bf44303220bcd992252237ec767c801 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 22 May 2025 09:48:17 -0500 Subject: [PATCH 15/32] wip --- source/connect/connection-options.txt | 625 ++++++++++-------- .../connection/ConnectionOptions.cs | 0 .../connection-options/applicationName.rst | 4 + .../connection-options/heartbeatInterval.rst | 2 + .../connection-options/heartbeatTimeout.rst | 2 + .../fundamentals/connection-options/ipv6.rst | 1 + .../connection-options/loadBalanced.rst | 9 + .../connection-options/localThreshold.rst | 3 + .../connection-options/retryReads.rst | 1 + .../connection-options/retryWrites.rst | 1 + .../connection-options/scheme.rst | 10 + .../connection-options/server.rst | 2 + .../serverMonitoringMode.rst | 8 + .../serverSelectionTimeout.rst | 2 + .../connection-options/servers.rst | 2 + .../connection-options/srvMaxHosts.rst | 7 + 16 files changed, 417 insertions(+), 262 deletions(-) create mode 100644 source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs create mode 100644 source/includes/fundamentals/connection-options/applicationName.rst create mode 100644 source/includes/fundamentals/connection-options/heartbeatInterval.rst create mode 100644 source/includes/fundamentals/connection-options/heartbeatTimeout.rst create mode 100644 source/includes/fundamentals/connection-options/ipv6.rst create mode 100644 source/includes/fundamentals/connection-options/loadBalanced.rst create mode 100644 source/includes/fundamentals/connection-options/localThreshold.rst create mode 100644 source/includes/fundamentals/connection-options/retryReads.rst create mode 100644 source/includes/fundamentals/connection-options/retryWrites.rst create mode 100644 source/includes/fundamentals/connection-options/scheme.rst create mode 100644 source/includes/fundamentals/connection-options/server.rst create mode 100644 source/includes/fundamentals/connection-options/serverMonitoringMode.rst create mode 100644 source/includes/fundamentals/connection-options/serverSelectionTimeout.rst create mode 100644 source/includes/fundamentals/connection-options/servers.rst create mode 100644 source/includes/fundamentals/connection-options/srvMaxHosts.rst diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 309ce1e9..68021ebe 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -128,9 +128,6 @@ Replica Set Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - .. tab:: MongoUrlBuilder - :tabid: mongo-url-builder - ReplicaSetName ~~~~~~~~~~~~~~ @@ -139,8 +136,7 @@ Replica Set Options .. code-block:: none :copyable: true - var settings = new MongoClientSettings(); - settings.ReplicaSetName = "yourReplicaSet"; + DirectConnection ~~~~~~~~~~~~~~~~ @@ -150,8 +146,7 @@ Replica Set Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.DirectConnection = true; + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -164,8 +159,7 @@ Replica Set Options .. code-block:: none :copyable: true - var builder = new MongoUrlBuilder(); - builder.ReplicaSetName = "yourReplicaSet"; + DirectConnection ~~~~~~~~~~~~~~~~ @@ -175,8 +169,7 @@ Replica Set Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.DirectConnection = true; + TLS Options ----------- @@ -194,8 +187,7 @@ TLS Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.AllowInsecureTls = true; + SslSettings ~~~~~~~~~~~ @@ -229,8 +221,7 @@ TLS Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.UseTls = true; + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -243,8 +234,7 @@ TLS Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.AllowInsecureTls = true; + UseTls ~~~~~~ @@ -254,8 +244,7 @@ TLS Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.UseTls = true; + Timeout Options --------------- @@ -273,8 +262,7 @@ Timeout Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.ConnectTimeout = TimeSpan.FromSeconds(60); + SocketTimeout ~~~~~~~~~~~~~ @@ -284,8 +272,7 @@ Timeout Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.SocketTimeout = TimeSpan.FromSeconds(60); + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -298,8 +285,7 @@ Timeout Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.ConnectTimeout = TimeSpan.FromSeconds(60); + SocketTimeout ~~~~~~~~~~~~~ @@ -309,8 +295,7 @@ Timeout Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.SocketTimeout = TimeSpan.FromSeconds(60); + Compression Options ------------------- @@ -328,12 +313,7 @@ Compression Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.Compressors = new List() - { - new CompressorConfiguration(CompressorType.Zlib), - new CompressorConfiguration(CompressorType.Snappy) - }; + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -346,12 +326,6 @@ Compression Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.Compressors = new List() - { - new CompressorConfiguration(CompressorType.Zlib), - new CompressorConfiguration(CompressorType.Snappy) - }; Connection Pool Options ----------------------- @@ -369,8 +343,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.MaxConnecting = 3; MaxConnectionIdleTime ~~~~~~~~~~~~~~~~~~~~~ @@ -380,8 +352,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(8); MaxConnectionLifeTime ~~~~~~~~~~~~~~~~~~~~~ @@ -391,8 +361,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.MaxConnectionLifeTime = TimeSpan.FromMinutes(40); MaxConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ @@ -402,8 +370,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.MaxConnectionPoolSize = 150; MinConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ @@ -413,8 +379,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.MinConnectionPoolSize = 3; WaitQueueTimeout ~~~~~~~~~~~~~~~~ @@ -424,8 +388,8 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.WaitQueueTimeout = TimeSpan.FromSeconds(30); + + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -437,8 +401,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - settings.MongoUrlBuilder = 3; MaxConnectionIdleTime ~~~~~~~~~~~~~~~~~~~~~ @@ -448,8 +410,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.MaxConnectionIdleTime = TimeSpan.FromMinutes(8); MaxConnectionLifeTime ~~~~~~~~~~~~~~~~~~~~~ @@ -459,8 +419,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var builder = new MongoUrlBuilder(); - builder.MaxConnectionLifeTime = TimeSpan.FromMinutes(40); MaxConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ @@ -470,8 +428,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.MaxConnectionPoolSize = 150; MinConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ @@ -481,8 +437,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.MinConnectionPoolSize = 3; WaitQueueTimeout ~~~~~~~~~~~~~~~~ @@ -492,8 +446,6 @@ Connection Pool Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.WaitQueueTimeout = TimeSpan.FromSeconds(30); Write Concern Options --------------------- @@ -524,11 +476,6 @@ Write Concern Options ); } - .. tab:: MongoUrlBuilder - :tabid: mongo-url-builder - - - ``GetWriteConcern(bool)`` - Read Concern Options -------------------- @@ -546,12 +493,22 @@ Read Concern Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.ReadConcern = new ReadConcern(ReadConcernLevel.Local); + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder + ReadConcernLevel + ~~~~~~~~~~~~~~~~ + + TODO: + The client's default read concern. The default value is ``ReadConcern.Default``. + For more information, see :ref:`read concern `. + + .. code-block:: csharp + :copyable: true + + Read Preference Options ----------------------- @@ -560,27 +517,23 @@ Read Preference Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - ReadPreference - ~~~~~~~~~~~~~~ + ReadPreference + ~~~~~~~~~~~~~~ - .. include:: /includes/fundamentals/connection-options/readPreference.rst + .. include:: /includes/fundamentals/connection-options/readPreference.rst + + .. code-block:: csharp + :copyable: true - .. code-block:: csharp - :copyable: true - var settings = new MongoClientSettings(); - settings.ReadPreference = ReadPreference.SecondaryPreferred; .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - .. include:: /includes/fundamentals/connection-options/readPreference.rst - - .. code-block:: csharp - :copyable: true + .. include:: /includes/fundamentals/connection-options/readPreference.rst - var settings = new MongoClientSettings(); - settings.ReadPreference = ReadPreference.SecondaryPreferred; + .. code-block:: csharp + :copyable: true Authentication Options ---------------------- @@ -605,22 +558,39 @@ Authentication Options .. code-block:: csharp :copyable: true - var settings = new MongoClientSettings(); - settings.Credential = MongoCredential.CreateScramSha256Credential( - source: "admin", - username: "user", - password: "password" - ); .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - | - | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ - - - ``AuthenticationMechanism`` - - - **Data Type**: {+string-data-type+} - - ``AuthenticationMechanismProperties`` - - - **Data Type**: ``IEnumerable>`` - + + AuthenticationMechanism + ~~~~~~~~~~~~~~~~~~~~~~~ + + The mechanism that the driver uses to authenticate to {+mdb-server+}. + If you don't specify an authentication mechanism, the driver uses either + ``SCRAM-SHA-1`` or ``SCRAM-SHA-256``, depending on the server version. See + :ref:`authentication mechanisms ` for available + authentication mechanisms. + + .. code-block:: csharp + + + + AuthenticationMechanismProperties + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Configuration settings for the authentication mechanism specified in the + ``AuthenticationMechanism`` property. + + .. code-block:: csharp + + + AuthenticationSource + ~~~~~~~~~~~~~~~~~~~~ + + The source to authenticate the client against. + + .. code-block:: csharp + Server Selection and Discovery Options -------------------------------------- @@ -629,43 +599,83 @@ Server Selection and Discovery Options .. tab:: MongoClientSettings :tabid: mongo-client-settings + + HeartbeatInterval + ~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst + + .. code-block:: csharp + :copyable: true + + + HeartbeatTimeout + ~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/heartbeatTimeout.rst + + .. code-block:: csharp + :copyable: true + + + + LocalThreshold + ~~~~~~~~~~~~~~ + .. include:: /includes/fundamentals/connection-options/localThreshold.rst + + .. code-block:: csharp + :copyable: true + + + + ServerSelectionTimeout + ~~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/localThreshold.rst + + .. code-block:: csharp + :copyable: true + + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder + + HeartbeatInterval + ~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst + + .. code-block:: csharp + :copyable: true + + + HeartbeatTimeout + ~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/heartbeatTimeout.rst + + .. code-block:: csharp + :copyable: true + + LocalThreshold - - ``LocalThreshold`` - - | The latency window for server eligibility. If a server's round trip takes longer - | than the fastest server's round-trip time plus this value, the server isn't - | eligible for selection. - | - | **Data Type**: ``TimeSpan`` - | **Default**: 15 milliseconds - | **Connection URI Example**: ``localThresholdMS=0`` + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/localThreshold.rst + + .. code-block:: csharp + :copyable: true + ServerSelectionTimeout - - ``ServerSelectionTimeout`` - - | The length of time the driver tries to select a server before timing out. - | - | **Data Type**: ``TimeSpan`` - | **Default**: 30 seconds - | **Connection URI Example**: ``serverSelectionTimeoutMS=15000`` + ~~~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/localThreshold.rst - HeartbeatInterval - - ``HeartbeatInterval`` - - | The interval between regular server-monitoring checks. Must be greater than or - | equal to 500 milliseconds. - | - | **Data Type**: ``TimeSpan`` - | **Default**: 10 seconds - | **Connection URI Example**: ``heartbeatFrequencyMS=5000`` + .. code-block:: csharp + :copyable: true - HeartbeatTimeout - - ``HeartbeatTimeout`` - - | The length of time a monitoring socket can be idle before timing out. - | - | **Data Type**: ``TimeSpan`` - | **Default**: Same value as ``ConnectTimeout`` - | **Connection URI Example**: ``heartbeatTimeoutMS=5000`` Miscellaneous Options --------------------- @@ -675,168 +685,259 @@ Miscellaneous Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - .. tab:: MongoUrlBuilder - :tabid: mongo-url-builder ApplicationName - - ``ApplicationName`` - - | The app name the driver passes to the server in the client metadata as part of - | the connection handshake. The server prints this value to the MongoDB logs once - | the connection is established. The value is also recorded in the slow query logs - | and profile collections. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``null`` + ~~~~~~~~~~~~~~~ - RetryReads - - ``RetryReads`` - - | Enables retryable reads. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``true`` - - RetryWrites - - ``RetryWrites`` - - | Enables retryable writes. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``true`` + .. include:: /includes/fundamentals/connection-options/applicationName.rst - LoadBalanced - - ``LoadBalanced`` - - | Specifies whether the driver is connecting to a load balancer. You can set this - | property to ``true`` only if: - - - You specify just one host name. - - You're not connecting to a replica set. - - You're not using the ``SrvMaxHosts`` property. - - You're not using the ``DirectConnection`` property. - - | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - - SrvMaxHosts - - ``SrvMaxHosts`` - - | The greatest number of SRV results to randomly select when initially populating - | the seedlist or, during SRV polling, adding new hosts to the topology. - | - | You can use this property only if the connection-string scheme is set - | to ``ConnectionStringScheme.MongoDBPlusSrv``. You cannot use it when connecting - | to a replica set. - | - | **Data Type**: {+int-data-type+} - | **Default**: ``0`` - | **Connection URI Example**: ``srvMaxHosts=3`` + .. code-block:: csharp + :copyable: true AutoEncryptionOptions - - {+not-available+} - - | Settings for automatic client-side encryption. - | - | **Data Type**: `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Encryption.AutoEncryptionOptions.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} + ~~~~~~~~~~~~~~~~~~~~~ + + Settings for automatic client-side encryption. The default value is ``null``. + + .. code-block:: csharp + :copyable: true + + ClusterConfigurator - - {+not-available+} - - | Low-level configuration options for sockets, TLS, cluster, and others. - | - | **Data Type**: Action<`ClusterBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.html>`__> - | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} + ~~~~~~~~~~~~~~~~~~~ + + Low-level configuration options for sockets, TLS, cluster, and others. The default + value is ``null``. + .. code-block:: csharp + :copyable: true + + IPv6 - - ``IPv6`` - - | Specifies whether the host address is in IPv6 format. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: ``ipv6=true`` + ~~~~ + + .. include:: /includes/fundamentals/connection-options/ipv6.rst + + .. code-block:: csharp + :copyable: true + IsFrozen - - {+not-available+} - - | Indicates whether the settings have been frozen. Frozen settings can't be changed. - | This option is read-only. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: {+not-available+} + ~~~~~~~~ + + Indicates whether the settings have been frozen. Frozen settings can't be changed. + This option is read-only. The default value is ``false``. + + .. code-block:: csharp + :copyable: true + + + LoadBalanced + ~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/loadBalanced.rst + + .. code-block:: csharp + :copyable: true + + var settings = new MongoClientSettings(); + settings.LoadBalanced = true; LoggingSettings - - {+not-available+} - - | The settings used for :ref:`logging. ` - | - | **Data Type**: `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.LoggingSettings.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} + ~~~~~~~~~~~~~~~ + + The settings used for :ref:`logging. ` The default value is ``null``. + .. code-block:: csharp + :copyable: true + + + ReadEncoding - - {+not-available+} - - | The UTF-8 encoding to use for string deserialization. - | Strict encoding will throw an exception when an invalid UTF-8 byte sequence - | is encountered. - | - | **Data Type**: ``UTF8Encoding`` - | **Default**: Strict encoding - | **Connection URI Example**: {+not-available+} + ~~~~~~~~~~~~ + + The UTF-8 encoding to use for string deserialization. The default value is + strict encoding, where the driver throws an exception when it encounters an invalid + UTF-8 byte sequence. + + .. code-block:: csharp + :copyable: true + + + RetryReads + ~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryReads.rst + + .. code-block:: csharp + :copyable: true + + + RetryWrites + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryWrites.rst + + .. code-block:: csharp + :copyable: true + Scheme - - ``Scheme`` - - | Specifies whether to use the standard connection string format (``MongoDB``) - | or the DNS seed list format (``MongoDBPlusSrv``). - | See :manual:`the MongoDB Manual` for more - | information about connection string formats. - | - | If the ``DirectConnection`` property is set to ``true`` and you - | try to use the DNS seed list format, the {+driver-short+} will throw an - | exception. - | - | **Data Type**: `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ConnectionStringScheme.html>`__ - | **Default**: ``ConnectionStringScheme.MongoDB`` - | **Connection URI Example**: ``mongodb+srv://`` + ~~~~~~ + + .. include:: /includes/fundamentals/connection-options/scheme.rst + + .. code-block:: csharp + :copyable: true + Server - - ``Server`` - - | The host and port number where MongoDB is running. - | - | **Data Type**: `MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__ - | **Default**: ``localhost:27017`` - | **Connection URI Example**: ``mongodb://sample.host:27017`` + ~~~~~~ + + .. include:: /includes/fundamentals/connection-options/server.rst + + .. code-block:: csharp + :copyable: true + + ServerApi - - {+not-available+} - - | Allows opting into Stable API versioning. See - | :manual:`the MongoDB Manual` for more information about - | Stable API versioning. - | - | **Data Type**: `ServerApi <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerApi.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} + ~~~~~~~~~ + + Allows opting into Stable API versioning. The default value is ``null``. See + :manual:`the MongoDB Manual` for more information about + Stable API versioning. + + .. code-block:: csharp + :copyable: true + ServerMonitoringMode - - ``ServerMonitoringMode`` - - | Specifies the server monitoring protocol to use. When - | this option is set to ``Auto``, the monitoring mode is determined - | by the environment in which the driver is running. The driver - | uses polling mode in function-as-a-service (FaaS) environments, - | such as AWS Lambda, and the streaming mode in other environments. - | - | **Data Type**: `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Servers.ServerMonitoringMode.html>`__ - | **Default**: ``Auto`` - | **Connection URI Example**: ``serverMonitoringMode=poll`` + ~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/serverMonitoringMode.rst + + .. code-block:: csharp + :copyable: true + Servers - - ``Servers`` - - | The cluster members where MongoDB is running. - | - | **Data Type**: IEnumerable<`MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__> - | **Default**: ``localhost:27017`` - | **Connection URI Example**: ``mongodb://sample.host1:27017,sample.host2:27017`` + ~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/servers.rst + + .. code-block:: csharp + :copyable: true + + + SrvMaxHosts + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/srvMaxHosts.rst + + .. code-block:: csharp + :copyable: true + TranslationOptions - - {+not-available+} - - | Specifies options, such as the {+mdb-server+} version, for translating LINQ - | queries to the Query API. - | - | **Data Type**: `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ExpressionTranslationOptions.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: {+not-available+} + ~~~~~~~~~~~~~~~~~~ + Specifies options, such as the {+mdb-server+} version, for translating LINQ + queries to the Query API. The default value is ``null``. + + .. code-block:: csharp + :copyable: true + + + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + ApplicationName + ~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/applicationName.rst + + .. code-block:: csharp + :copyable: true + + + IPv6 + ~~~~ + + .. include:: /includes/fundamentals/connection-options/ipv6.rst + + .. code-block:: csharp + :copyable: true + + + LoadBalanced + ~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/loadBalanced.rst + + .. code-block:: csharp + :copyable: true + + + RetryReads + ~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryReads.rst + + .. code-block:: csharp + :copyable: true + + + RetryWrites + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryWrites.rst + + .. code-block:: csharp + :copyable: true + + + Scheme + ~~~~~~ + + .. include:: /includes/fundamentals/connection-options/scheme.rst + + .. code-block:: csharp + :copyable: true + + + Server + ~~~~~~ + + .. include:: /includes/fundamentals/connection-options/server.rst + + .. code-block:: csharp + :copyable: true + + + ServerMonitoringMode + ~~~~~~~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/serverMonitoringMode.rst + + .. code-block:: csharp + :copyable: true + + + Servers + ~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/servers.rst + + .. code-block:: csharp + :copyable: true + + + SrvMaxHosts + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/srvMaxHosts.rst + + .. code-block:: csharp + :copyable: true diff --git a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs new file mode 100644 index 00000000..e69de29b diff --git a/source/includes/fundamentals/connection-options/applicationName.rst b/source/includes/fundamentals/connection-options/applicationName.rst new file mode 100644 index 00000000..e2267756 --- /dev/null +++ b/source/includes/fundamentals/connection-options/applicationName.rst @@ -0,0 +1,4 @@ +The app name the driver passes to the server in the client metadata as part of +the connection handshake. The server prints this value to the MongoDB logs once +the connection is established. The value is also recorded in the slow query logs +and profile collections. The default value is ``null``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/heartbeatInterval.rst b/source/includes/fundamentals/connection-options/heartbeatInterval.rst new file mode 100644 index 00000000..be42ae49 --- /dev/null +++ b/source/includes/fundamentals/connection-options/heartbeatInterval.rst @@ -0,0 +1,2 @@ +The interval between regular server-monitoring checks. Must be greater than or +equal to 500 milliseconds. The default value is ``10000`` milliseconds (10 seconds). \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/heartbeatTimeout.rst b/source/includes/fundamentals/connection-options/heartbeatTimeout.rst new file mode 100644 index 00000000..85424bb0 --- /dev/null +++ b/source/includes/fundamentals/connection-options/heartbeatTimeout.rst @@ -0,0 +1,2 @@ +The length of time a monitoring socket can be idle before timing out. The default value +is the value of the ``ConnectTimeout`` property. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/ipv6.rst b/source/includes/fundamentals/connection-options/ipv6.rst new file mode 100644 index 00000000..a23191ed --- /dev/null +++ b/source/includes/fundamentals/connection-options/ipv6.rst @@ -0,0 +1 @@ +Specifies whether the host address is in IPv6 format. The default value is ``false``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/loadBalanced.rst b/source/includes/fundamentals/connection-options/loadBalanced.rst new file mode 100644 index 00000000..0d327850 --- /dev/null +++ b/source/includes/fundamentals/connection-options/loadBalanced.rst @@ -0,0 +1,9 @@ +Specifies whether the driver is connecting to a load balancer. You can set this +property to ``true`` only if: + +- You specify just one host name. +- You're not connecting to a replica set. +- You're not using the ``SrvMaxHosts`` property. +- You're not using the ``DirectConnection`` property. + +The default value is ``false``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/localThreshold.rst b/source/includes/fundamentals/connection-options/localThreshold.rst new file mode 100644 index 00000000..811db444 --- /dev/null +++ b/source/includes/fundamentals/connection-options/localThreshold.rst @@ -0,0 +1,3 @@ +The latency window for server eligibility. If a server's round trip takes longer +than the fastest server's round-trip time plus this value, the server isn't +eligible for selection. The default value is 15 milliseconds. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/retryReads.rst b/source/includes/fundamentals/connection-options/retryReads.rst new file mode 100644 index 00000000..2d37750b --- /dev/null +++ b/source/includes/fundamentals/connection-options/retryReads.rst @@ -0,0 +1 @@ +Enables retryable reads. The default value is ``true``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/retryWrites.rst b/source/includes/fundamentals/connection-options/retryWrites.rst new file mode 100644 index 00000000..24c430b7 --- /dev/null +++ b/source/includes/fundamentals/connection-options/retryWrites.rst @@ -0,0 +1 @@ +Enables retryable writes. The default value is ``true``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/scheme.rst b/source/includes/fundamentals/connection-options/scheme.rst new file mode 100644 index 00000000..44d49247 --- /dev/null +++ b/source/includes/fundamentals/connection-options/scheme.rst @@ -0,0 +1,10 @@ +Specifies whether to use the standard connection string format (``MongoDB``) +or the DNS seed list format (``MongoDBPlusSrv``). The available values for this +property are defined in the `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ConnectionStringScheme.html>`__ +enum. The default value is ``ConnectionStringScheme.MongoDB``. +See :manual:`the MongoDB Manual` for more +information about connection string formats. + +If the ``DirectConnection`` property is set to ``true`` and you +try to use the DNS seed list format, the {+driver-short+} will throw an +exception. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/server.rst b/source/includes/fundamentals/connection-options/server.rst new file mode 100644 index 00000000..c6d294e6 --- /dev/null +++ b/source/includes/fundamentals/connection-options/server.rst @@ -0,0 +1,2 @@ +The host and port number where MongoDB is running. The default value is +``localhost:27017``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/serverMonitoringMode.rst b/source/includes/fundamentals/connection-options/serverMonitoringMode.rst new file mode 100644 index 00000000..cf9f0f7a --- /dev/null +++ b/source/includes/fundamentals/connection-options/serverMonitoringMode.rst @@ -0,0 +1,8 @@ +Specifies the server monitoring protocol to use. The available values for this +property are defined in the `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Servers.ServerMonitoringMode.html>`__ +enum. The default value is ``Auto``. + +When this option is set to ``Auto`` the monitoring mode is determined +by the environment in which the driver is running. The driver +uses polling mode in function-as-a-service (FaaS) environments, +such as AWS Lambda, and the streaming mode in other environments. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/serverSelectionTimeout.rst b/source/includes/fundamentals/connection-options/serverSelectionTimeout.rst new file mode 100644 index 00000000..7dd4c9ff --- /dev/null +++ b/source/includes/fundamentals/connection-options/serverSelectionTimeout.rst @@ -0,0 +1,2 @@ +The length of time the driver tries to select a server before timing out. The default +value is 30 seconds. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/servers.rst b/source/includes/fundamentals/connection-options/servers.rst new file mode 100644 index 00000000..61c3a4d0 --- /dev/null +++ b/source/includes/fundamentals/connection-options/servers.rst @@ -0,0 +1,2 @@ +The cluster members where MongoDB is running. The default value is +``localhost:27017``. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/srvMaxHosts.rst b/source/includes/fundamentals/connection-options/srvMaxHosts.rst new file mode 100644 index 00000000..10cde05f --- /dev/null +++ b/source/includes/fundamentals/connection-options/srvMaxHosts.rst @@ -0,0 +1,7 @@ +The greatest number of SRV results to randomly select when initially populating +the seedlist or, during SRV polling, adding new hosts to the topology. The default +value is ``0``. + +You can use this property only if the connection-string scheme is set +to ``ConnectionStringScheme.MongoDBPlusSrv``. You cannot use it when connecting +to a replica set. \ No newline at end of file From 66748263478810c01c329c19784b57cfbfc40a5a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 27 May 2025 11:43:17 -0500 Subject: [PATCH 16/32] first draft --- source/connect/connection-options.txt | 620 ++++++++++------ .../connection/ConnectionOptions.cs | 686 ++++++++++++++++++ .../{maxConnectin.rst => maxConnecting.rst} | 0 3 files changed, 1084 insertions(+), 222 deletions(-) rename source/includes/fundamentals/connection-options/{maxConnectin.rst => maxConnecting.rst} (100%) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 68021ebe..59a5865d 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -18,7 +18,7 @@ Connection Options :class: singlecol .. toctree:: - :caption: Specify Connection Options + :caption: Specify Connection Options Compress Network Traffic Customize Server Selection @@ -92,7 +92,7 @@ its properties, and pass it as an argument to the ``MongoClient`` constructor: :end-before: // end mongo client settings config .. tip:: Other MongoUrl Members - + The ``MongoUrl`` class contains other methods and read-only properties that you can use to retrieve information about your connection. For a full list, see `MongoUrl <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrl.html>`__ in the @@ -127,26 +127,30 @@ Replica Set Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + ReplicaSetName ~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/replicaSetName.rst - - .. code-block:: none - :copyable: true - + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-replica-set-name + :end-before: // end-settings-replica-set-name DirectConnection ~~~~~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/directConnection.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-direct-connection + :end-before: // end-settings-direct-connection .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -155,22 +159,26 @@ Replica Set Options ~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/replicaSetName.rst - - .. code-block:: none - :copyable: true - + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-replica-set-name + :end-before: // end-builder-replica-set-name DirectConnection ~~~~~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/directConnection.rst - - .. code-block:: csharp - :copyable: true + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-direct-connection + :end-before: // end-builder-direct-connection - TLS Options ----------- @@ -184,67 +192,68 @@ TLS Options .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-allow-insecure-tls + :end-before: // end-settings-allow-insecure-tls SslSettings ~~~~~~~~~~~ TLS/SSL options, including client certificates, revocation handling, and enabled and disabled TLS/SSL protocols. The default value is ``null``. - + If ``SslSettings.CheckCertificateRevocation`` is set to ``false`` and ``AllowInsecureTls`` is set to ``true``, the {+driver-short+} throws an exception. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-ssl-settings + :end-before: // end-settings-ssl-settings - var settings = new MongoClientSettings(); - settings.SslSettings = new SslSettings() - { - CheckCertificateRevocation = false, - ClientCertificateCollection = new X509CertificateCollection() { ... }, - ClientCertificateSelectionCallback = new LocalCertificateSelectionCallback() { ... }, - ClientCertificates = new List() { ... }, - EnabledSslProtocols = SslProtocols.Tls13, - ServerCertificateValidationCallback = new RemoteCertificateValidationCallback() { ... } - }; - UseTls ~~~~~~ .. include:: /includes/fundamentals/connection-options/useTls.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-use-tls + :end-before: // end-settings-use-tls .. tab:: MongoUrlBuilder :tabid: mongo-url-builder AllowInsecureTls ~~~~~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-builder-allow-insecure-tls + :end-before: // end-builder-allow-insecure-tls UseTls ~~~~~~ .. include:: /includes/fundamentals/connection-options/useTls.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-builder-use-tls + :end-before: // end-builder-use-tls Timeout Options --------------- @@ -253,26 +262,30 @@ Timeout Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + ConnectTimeout ~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/connectTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-connect-timeout + :end-before: // end-settings-connect-timeout SocketTimeout ~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/socketTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-connect-timeout + :end-before: // end-settings-connect-timeout .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -282,20 +295,24 @@ Timeout Options .. include:: /includes/fundamentals/connection-options/connectTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-builder-connect-timeout + :end-before: // end-builder-connect-timeout SocketTimeout ~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/socketTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-builder-socket-timeout + :end-before: // end-builder-socket-timeout Compression Options ------------------- @@ -304,16 +321,18 @@ Compression Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + Compressors ~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/compressors.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-compressors + :end-before: // end-settings-compressors .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -323,9 +342,12 @@ Compression Options .. include:: /includes/fundamentals/connection-options/compressors.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-compressors + :end-before: // end-builder-compressors Connection Pool Options ----------------------- @@ -334,62 +356,79 @@ Connection Pool Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + MaxConnecting ~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/maxConnecting.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-max-connecting + :end-before: // end-settings-max-connecting MaxConnectionIdleTime ~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/maxConnectionIdleTime.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-max-connection-idle-time + :end-before: // end-settings-max-connection-idle-time MaxConnectionLifeTime ~~~~~~~~~~~~~~~~~~~~~ - .. include:: /includes/fundamentals/connection-options/maxConnectionLifeTime.rst + .. include:: /includes/fundamentals/connection-options/maxConnectionLifetime.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-max-connection-life-time + :end-before: // end-settings-max-connection-life-time MaxConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/maxConnectionPoolSize.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-max-connection-pool-size + :end-before: // end-settings-max-connection-pool-size MinConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/minConnectionPoolSize.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-min-connection-pool-size + :end-before: // end-settings-min-connection-pool-size WaitQueueTimeout ~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/waitQueueTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-wait-queue-timeout + :end-before: // end-settings-wait-queue-timeout - - .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -398,54 +437,72 @@ Connection Pool Options .. include:: /includes/fundamentals/connection-options/maxConnecting.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-max-connecting + :end-before: // end-builder-max-connecting MaxConnectionIdleTime ~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/maxConnectionIdleTime.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-max-connection-idle-time + :end-before: // end-builder-max-connection-idle-time MaxConnectionLifeTime ~~~~~~~~~~~~~~~~~~~~~ - .. include:: /includes/fundamentals/connection-options/maxConnectionLifeTime.rst + .. include:: /includes/fundamentals/connection-options/maxConnectionLifetime.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-max-connection-life-time + :end-before: // end-builder-max-connection-life-time MaxConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/maxConnectionPoolSize.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-max-connection-pool-size + :end-before: // end-builder-max-connection-pool-size MinConnectionPoolSize ~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/minConnectionPoolSize.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-min-connection-pool-size + :end-before: // end-builder-min-connection-pool-size WaitQueueTimeout ~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/waitQueueTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-wait-queue-timeout + :end-before: // end-builder-wait-queue-timeout Write Concern Options --------------------- @@ -462,20 +519,13 @@ Write Concern Options journaling, for the client. The default value is ``WriteConcern.Acknowledged``. See :ref:`write concern ` for more information. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-write-concern + :end-before: // end-settings-write-concern - public void WriteConcern() - { - var settings = new MongoClientSettings(); - settings.WriteConcern = new WriteConcern( - w: 1, - wTimeout: new TimeSpan(0, 0, 0, 30, 0), - fsync: true, - journal: true - ); - } - Read Concern Options -------------------- @@ -483,31 +533,35 @@ Read Concern Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + ReadConcern ~~~~~~~~~~~ - The client's default read concern. The default value is ``ReadConcern.Default``. + The client's read concern. The default value is ``ReadConcern.Default``. For more information, see :ref:`read concern `. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-read-concern + :end-before: // end-settings-read-concern - - .. tab:: MongoUrlBuilder :tabid: mongo-url-builder ReadConcernLevel ~~~~~~~~~~~~~~~~ - TODO: - The client's default read concern. The default value is ``ReadConcern.Default``. + The client's read concern level. The default value is ``ReadConcern.Local``. For more information, see :ref:`read concern `. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-read-concern-level + :end-before: // end-builder-read-concern-level Read Preference Options ----------------------- @@ -516,25 +570,31 @@ Read Preference Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + ReadPreference ~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/readPreference.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-read-preference + :end-before: // end-settings-read-preference .. tab:: MongoUrlBuilder :tabid: mongo-url-builder .. include:: /includes/fundamentals/connection-options/readPreference.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-read-preference + :end-before: // end-builder-read-preference + Authentication Options ---------------------- @@ -542,23 +602,26 @@ Authentication Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + Credential ~~~~~~~~~~ Settings for how the driver authenticates to the server. This includes authentication credentials, mechanism, source, and other settings. The default value is ``null``. - + f you don't specify an authentication mechanism, the driver uses either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256``, depending on the server version. See :ref:`authentication mechanisms ` for available authentication mechanisms. - - .. code-block:: csharp + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-credential + :end-before: // end-settings-credential - .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -571,9 +634,13 @@ Authentication Options :ref:`authentication mechanisms ` for available authentication mechanisms. - .. code-block:: csharp - - + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-authentication + :end-before: // end-builder-authentication + :emphasize-lines: 3 AuthenticationMechanismProperties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -581,16 +648,26 @@ Authentication Options Configuration settings for the authentication mechanism specified in the ``AuthenticationMechanism`` property. - .. code-block:: csharp - + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-authentication + :end-before: // end-builder-authentication + :emphasize-lines: 4-8 AuthenticationSource ~~~~~~~~~~~~~~~~~~~~ The source to authenticate the client against. - .. code-block:: csharp - + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-authentication + :end-before: // end-builder-authentication + :emphasize-lines: 9 Server Selection and Discovery Options -------------------------------------- @@ -605,38 +682,48 @@ Server Selection and Discovery Options .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-heartbeat-interval + :end-before: // end-settings-heartbeat-interval HeartbeatTimeout ~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/heartbeatTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-heartbeat-timeout + :end-before: // end-settings-heartbeat-timeout LocalThreshold ~~~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/localThreshold.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-local-threshold + :end-before: // end-settings-local-threshold ServerSelectionTimeout ~~~~~~~~~~~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/localThreshold.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-server-selection-timeout + :end-before: // end-settings-server-selection-timeout .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -646,36 +733,48 @@ Server Selection and Discovery Options .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-heartbeat-interval + :end-before: // end-builder-heartbeat-interval HeartbeatTimeout ~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/heartbeatTimeout.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-heartbeat-timeout + :end-before: // end-builder-heartbeat-timeout LocalThreshold ~~~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/localThreshold.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-local-threshold + :end-before: // end-builder-local-threshold ServerSelectionTimeout ~~~~~~~~~~~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/localThreshold.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-server-selection-timeout + :end-before: // end-builder-server-selection-timeout Miscellaneous Options --------------------- @@ -684,24 +783,30 @@ Miscellaneous Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - + ApplicationName ~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/applicationName.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-application-name + :end-before: // end-settings-application-name AutoEncryptionOptions ~~~~~~~~~~~~~~~~~~~~~ Settings for automatic client-side encryption. The default value is ``null``. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-auto-encryption-options + :end-before: // end-settings-auto-encryption-options ClusterConfigurator ~~~~~~~~~~~~~~~~~~~ @@ -709,18 +814,24 @@ Miscellaneous Options Low-level configuration options for sockets, TLS, cluster, and others. The default value is ``null``. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-cluster-configurator + :end-before: // end-settings-cluster-configurator + IPv6 ~~~~ .. include:: /includes/fundamentals/connection-options/ipv6.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-ipv6 + :end-before: // end-settings-ipv6 IsFrozen ~~~~~~~~ @@ -728,31 +839,37 @@ Miscellaneous Options Indicates whether the settings have been frozen. Frozen settings can't be changed. This option is read-only. The default value is ``false``. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-is-frozen + :end-before: // end-settings-is-frozen LoadBalanced ~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/loadBalanced.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - var settings = new MongoClientSettings(); - settings.LoadBalanced = true; + :dedent: 8 + :start-after: // start-settings-load-balanced + :end-before: // end-settings-load-balanced LoggingSettings ~~~~~~~~~~~~~~~ The settings used for :ref:`logging. ` The default value is ``null``. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-logging-settings + :end-before: // end-settings-logging-settings - - ReadEncoding ~~~~~~~~~~~~ @@ -760,46 +877,60 @@ Miscellaneous Options strict encoding, where the driver throws an exception when it encounters an invalid UTF-8 byte sequence. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-read-encoding + :end-before: // end-settings-read-encoding RetryReads ~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/retryReads.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-retry-reads + :end-before: // end-settings-retry-reads RetryWrites ~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/retryWrites.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-retry-writes + :end-before: // end-settings-retry-writes Scheme ~~~~~~ .. include:: /includes/fundamentals/connection-options/scheme.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-scheme + :end-before: // end-settings-scheme Server ~~~~~~ - + .. include:: /includes/fundamentals/connection-options/server.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - - + :dedent: 8 + :start-after: // start-settings-server + :end-before: // end-settings-server ServerApi ~~~~~~~~~ @@ -808,36 +939,48 @@ Miscellaneous Options :manual:`the MongoDB Manual` for more information about Stable API versioning. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-server-api + :end-before: // end-settings-server-api ServerMonitoringMode ~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/serverMonitoringMode.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-server-monitoring-mode + :end-before: // end-settings-server-monitoring-mode Servers ~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/servers.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-servers + :end-before: // end-settings-servers - SrvMaxHosts ~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/srvMaxHosts.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-settings-srv-max-hosts + :end-before: // end-settings-srv-max-hosts TranslationOptions ~~~~~~~~~~~~~~~~~~ @@ -845,99 +988,132 @@ Miscellaneous Options Specifies options, such as the {+mdb-server+} version, for translating LINQ queries to the Query API. The default value is ``null``. - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-settings-translation-options + :end-before: // end-settings-translation-options - - .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - + ApplicationName ~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/applicationName.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-application-name + :end-before: // end-builder-application-name IPv6 ~~~~ .. include:: /includes/fundamentals/connection-options/ipv6.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-ipv6 + :end-before: // end-builder-ipv6 LoadBalanced ~~~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/loadBalanced.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-builder-load-balanced + :end-before: // end-builder-load-balanced - RetryReads ~~~~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/retryReads.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-retry-reads + :end-before: // end-builder-retry-reads RetryWrites ~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/retryWrites.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-retry-writes + :end-before: // end-builder-retry-writes Scheme ~~~~~~ .. include:: /includes/fundamentals/connection-options/scheme.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-scheme + :end-before: // end-builder-scheme Server ~~~~~~ .. include:: /includes/fundamentals/connection-options/server.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-server + :end-before: // end-builder-server ServerMonitoringMode ~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/serverMonitoringMode.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true - + :dedent: 8 + :start-after: // start-builder-server-monitoring-mode + :end-before: // end-builder-server-monitoring-mode Servers ~~~~~~~ - + .. include:: /includes/fundamentals/connection-options/servers.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-builder-servers + :end-before: // end-builder-servers - SrvMaxHosts ~~~~~~~~~~~ .. include:: /includes/fundamentals/connection-options/srvMaxHosts.rst - .. code-block:: csharp + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp :copyable: true + :dedent: 8 + :start-after: // start-builder-srv-max-hosts + :end-before: // end-builder-srv-max-hosts diff --git a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs index e69de29b..3a0b91b8 100644 --- a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs +++ b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -0,0 +1,686 @@ +using System.Net.Security; +using System.Security.Authentication; +using System.Security.Cryptography.X509Certificates; +using System.Text; +using Microsoft.Extensions.Logging; +using MongoDB.Driver; +using MongoDB.Driver.Core.Compression; +using MongoDB.Driver.Core.Configuration; +using MongoDB.Driver.Core.Events; + +namespace Connection; + +public class ConnectionOptions +{ + public void ReplicaSetName() + { + // start-settings-replica-set-name + var settings = new MongoClientSettings + { + ReplicaSetName = "yourReplicaSet", + }; + // end-settings-replica-set-name + + // start-builder-replica-set-name + var builder = new MongoUrlBuilder + { + ReplicaSetName = "yourReplicaSet", + }; + // end-builder-replica-set-name + } + + public void DirectConnection() + { + // start-settings-direct-connection + var settings = new MongoClientSettings + { + DirectConnection = true, + }; + // end-settings-direct-connection + + // start-builder-direct-connection + var builder = new MongoUrlBuilder + { + DirectConnection = true, + }; + // end-builder-direct-connection + } + + public void AllowInsecureTls() + { + // start-settings-allow-insecure-tls + var settings = new MongoClientSettings + { + AllowInsecureTls = true, + }; + // end-settings-allow-insecure-tls + + // start-builder-allow-insecure-tls + var builder = new MongoUrlBuilder + { + AllowInsecureTls = true, + }; + // end-builder-allow-insecure-tls + } + + public void UseTls() + { + // start-settings-use-tls + var settings = new MongoClientSettings + { + UseTls = true, + }; + // end-settings-use-tls + + // start-builder-use-tls + var builder = new MongoUrlBuilder + { + UseTls = true, + }; + // end-builder-use-tls + } + + public void ConnectTimeout() + { + // start-settings-connect-timeout + var settings = new MongoClientSettings + { + ConnectTimeout = TimeSpan.FromSeconds(60), + }; + // end-settings-connect-timeout + + // start-builder-connect-timeout + var builder = new MongoUrlBuilder + { + ConnectTimeout = TimeSpan.FromSeconds(60), + }; + // end-builder-connect-timeout + } + + public void SocketTimeout() + { + // start-settings-socket-timeout + var settings = new MongoClientSettings + { + SocketTimeout = TimeSpan.FromSeconds(60), + }; + // end-settings-socket-timeout + + // start-builder-socket-timeout + var builder = new MongoUrlBuilder + { + SocketTimeout = TimeSpan.FromSeconds(60), + }; + // end-builder-socket-timeout + } + + public void Compressors() + { + // start-settings-compressors + var settings = new MongoClientSettings + { + Compressors = new List() + { + new(CompressorType.Zlib), + new(CompressorType.Snappy) + } + }; + // end-settings-compressors + + // start-builder-compressors + var builder = new MongoUrlBuilder + { + Compressors = new List() + { + new(CompressorType.Zlib), + new(CompressorType.Snappy) + } + }; + // end-builder-compressors + } + + public void MaxConnecting() + { + // start-settings-max-connecting + var settings = new MongoClientSettings + { + MaxConnecting = 3, + }; + // end-settings-max-connecting + + // start-builder-max-connecting + var builder = new MongoUrlBuilder + { + MaxConnecting = 3, + }; + // end-builder-max-connecting + } + + public void MaxConnectionIdleTime() + { + // start-settings-max-connection-idle-time + var settings = new MongoClientSettings + { + MaxConnectionIdleTime = TimeSpan.FromMinutes(8), + }; + // end-settings-max-connection-idle-time + + // start-builder-max-connection-idle-time + var builder = new MongoUrlBuilder + { + MaxConnectionIdleTime = TimeSpan.FromMinutes(8), + }; + // end-builder-max-connection-idle-time + } + + public void MaxConnectionLifeTime() + { + // start-settings-max-connection-life-time + var settings = new MongoClientSettings + { + MaxConnectionLifeTime = TimeSpan.FromMinutes(40), + }; + // end-settings-max-connection-life-time + + // start-builder-max-connection-life-time + var builder = new MongoUrlBuilder + { + MaxConnectionLifeTime = TimeSpan.FromMinutes(40), + }; + // end-builder-max-connection-life-time + } + + public void MaxConnectionPoolSize() + { + // start-settings-max-connection-pool-size + var settings = new MongoClientSettings + { + MaxConnectionPoolSize = 150, + }; + // end-settings-max-connection-pool-size + + // start-builder-max-connection-pool-size + var builder = new MongoUrlBuilder + { + MaxConnectionPoolSize = 150, + }; + // end-builder-max-connection-pool-size + } + + public void MinConnectionPoolSize() + { + // start-settings-min-connection-pool-size + var settings = new MongoClientSettings + { + MinConnectionPoolSize = 3, + }; + // end-settings-min-connection-pool-size + + // start-builder-min-connection-pool-size + var builder = new MongoUrlBuilder + { + MinConnectionPoolSize = 3, + }; + // end-builder-min-connection-pool-size + } + + public void WaitQueueTimeout() + { + // start-settings-wait-queue-timeout + var settings = new MongoClientSettings + { + WaitQueueTimeout = TimeSpan.FromSeconds(30), + }; + // end-settings-wait-queue-timeout + + // start-builder-wait-queue-timeout + var builder = new MongoUrlBuilder + { + WaitQueueTimeout = TimeSpan.FromSeconds(30), + }; + // end-builder-wait-queue-timeout + } + + public void ReadConcern() + { + // start-settings-read-concern + var settings = new MongoClientSettings + { + ReadConcern = MongoDB.Driver.ReadConcern.Local, + }; + // end-settings-read-concern + } + + public void ReadConcernLevel() + { + // start-builder-read-concern-level + var builder = new MongoUrlBuilder + { + ReadConcernLevel = MongoDB.Driver.ReadConcernLevel.Local, + }; + // end-builder-read-concern-level + } + + public void ReadPreference() + { + // start-settings-read-preference + var settings = new MongoClientSettings + { + ReadPreference = MongoDB.Driver.ReadPreference.PrimaryPreferred, + }; + // end-settings-read-preference + + // start-builder-read-preference + var builder = new MongoUrlBuilder + { + ReadPreference = MongoDB.Driver.ReadPreference.PrimaryPreferred, + }; + // end-builder-read-preference + } + + public void Credential() + { + // start-settings-credential + var settings = new MongoClientSettings + { + Credential = MongoCredential.CreatePlainCredential( + databaseName: "admin", + username: "user", + password: "password" + ) + }; + // end-settings-credential + } + + public void BuilderAuthentication() + { + // start-builder-authentication + var builder = new MongoUrlBuilder + { + AuthenticationMechanism = "GSSAPI", + AuthenticationMechanismProperties = new Dictionary + { + { "SERVICE_NAME", "other" }, + { "CANONICALIZE_HOST_NAME", "true" } + }, + AuthenticationSource = "db" + }; + // end-builder-authentication + } + + public void HeartbeatInterval() + { + // start-settings-heartbeat-interval + var settings = new MongoClientSettings + { + HeartbeatInterval = TimeSpan.FromSeconds(5) + }; + // end-settings-heartbeat-interval + + // start-builder-heartbeat-interval + var builder = new MongoUrlBuilder + { + HeartbeatInterval = TimeSpan.FromSeconds(5) + }; + // end-builder-heartbeat-interval + } + + public void HeartbeatTimeout() + { + // start-settings-heartbeat-timeout + var settings = new MongoClientSettings + { + HeartbeatTimeout = TimeSpan.FromSeconds(5) + }; + // end-settings-heartbeat-timeout + + // start-builder-heartbeat-timeout + var builder = new MongoUrlBuilder + { + HeartbeatTimeout = TimeSpan.FromSeconds(5) + }; + // end-builder-heartbeat-timeout + } + + public void LocalThreshold() + { + // start-settings-local-threshold + var settings = new MongoClientSettings + { + LocalThreshold = TimeSpan.FromSeconds(15) + }; + // end-settings-local-threshold + + // start-builder-local-threshold + var builder = new MongoUrlBuilder + { + LocalThreshold = TimeSpan.FromSeconds(15) + }; + // end-builder-local-threshold + } + + public void ServerSelectionTimeout() + { + // start-settings-server-selection-timeout + var settings = new MongoClientSettings + { + ServerSelectionTimeout = TimeSpan.FromSeconds(30) + }; + // end-settings-server-selection-timeout + + // start-builder-server-selection-timeout + var builder = new MongoUrlBuilder + { + ServerSelectionTimeout = TimeSpan.FromSeconds(30) + }; + // end-builder-server-selection-timeout + } + + public void ApplicationName() + { + // start-settings-application-name + var settings = new MongoClientSettings + { + ApplicationName = "yourAppName", + }; + // end-settings-application-name + + // start-builder-application-name + var builder = new MongoUrlBuilder + { + ApplicationName = "yourAppName", + }; + // end-builder-application-name + } + + public void Ipv6() + { + // start-settings-ipv6 + var settings = new MongoClientSettings + { + IPv6 = true, + }; + // end-settings-ipv6 + + // start-builder-ipv6 + var builder = new MongoUrlBuilder + { + IPv6 = true, + }; + // end-builder-ipv6 + } + + public void LoadBalanced() + { + // start-settings-load-balanced + var settings = new MongoClientSettings + { + LoadBalanced = true, + }; + // end-settings-load-balanced + + // start-builder-load-balanced + var builder = new MongoUrlBuilder + { + LoadBalanced = true, + }; + // end-builder-load-balanced + } + + public void RetryReads() + { + // start-settings-retry-reads + var settings = new MongoClientSettings + { + RetryReads = false, + }; + // end-settings-retry-reads + + // start-builder-retry-reads + var builder = new MongoUrlBuilder + { + RetryReads = false, + }; + // end-builder-retry-reads + } + + public void RetryWrites() + { + // start-settings-retry-writes + var settings = new MongoClientSettings + { + RetryWrites = false, + }; + // end-settings-retry-writes + + // start-builder-retry-writes + var builder = new MongoUrlBuilder + { + RetryWrites = false, + }; + // end-builder-retry-writes + } + + public void Scheme() + { + // start-settings-scheme + var settings = new MongoClientSettings + { + Scheme = ConnectionStringScheme.MongoDBPlusSrv, + }; + // end-settings-scheme + + // start-builder-scheme + var builder = new MongoUrlBuilder + { + Scheme = ConnectionStringScheme.MongoDBPlusSrv, + }; + // end-builder-scheme + } + + public void Server() + { + // start-settings-server + var settings = new MongoClientSettings + { + Server = new MongoServerAddress("localhost", 27017) + }; + // end-settings-server + + // start-builder-server + var builder = new MongoUrlBuilder + { + Server = new MongoServerAddress("localhost", 27017) + }; + // end-builder-server + } + + public void ServerMonitoringMode() + { + // start-settings-server-monitoring-mode + var settings = new MongoClientSettings + { + ServerMonitoringMode = MongoDB.Driver.Core.Servers.ServerMonitoringMode.Stream + }; + // end-settings-server-monitoring-mode + + // start-builder-server-monitoring-mode + var builder = new MongoUrlBuilder + { + ServerMonitoringMode = MongoDB.Driver.Core.Servers.ServerMonitoringMode.Stream + }; + // end-builder-server-monitoring-mode + } + + public void Servers() + { + // start-settings-servers + var settings = new MongoClientSettings + { + Servers = new List() + { + new ("localhost", 27017), + new ("localhost", 27018) + } + }; + // end-settings-servers + + // start-builder-servers + var builder = new MongoUrlBuilder + { + Servers = new List() + { + new ("localhost", 27017), + new ("localhost", 27018) + } + }; + // end-builder-servers + } + + public void SrvMaxHosts() + { + // start-settings-srv-max-hosts + var settings = new MongoClientSettings + { + SrvMaxHosts = 5 + }; + // end-settings-srv-max-hosts + + // start-builder-srv-max-hosts + var builder = new MongoUrlBuilder + { + SrvMaxHosts = 5 + }; + // end-builder-srv-max-hosts + } + + public void TranslationOptions() + { + // start-settings-translation-options + var settings = new MongoClientSettings + { + TranslationOptions = new ExpressionTranslationOptions() + { + CompatibilityLevel = ServerVersion.Server80, + EnableClientSideProjections = true + } + }; + // end-settings-translation-options + } + + public void LoggingSettings() + { + // start-settings-logging-settings + var settings = new MongoClientSettings + { + LoggingSettings = new LoggingSettings( + LoggerFactory.Create(l => + l.SetMinimumLevel(LogLevel.Debug))) + }; + // end-settings-logging-settings + } + + public void ServerApi() + { + // start-settings-server-api + var settings = new MongoClientSettings + { + ServerApi = new ServerApi( + ServerApiVersion.V1, + strict: true, + deprecationErrors: true), + }; + // end-settings-server-api + } + + public void ReadEncoding() + { + // start-settings-read-encoding + var settings = new MongoClientSettings + { + ReadEncoding = new UTF8Encoding( + encoderShouldEmitUTF8Identifier: false, + throwOnInvalidBytes: true) + }; + // end-settings-read-encoding + } + + public void AutoEncryptionOptions() + { + // start-settings-auto-encryption-options + var settings = new MongoClientSettings + { + AutoEncryptionOptions = new AutoEncryptionOptions( + keyVaultNamespace: new CollectionNamespace( + databaseName: "keyvault", + collectionName: "datakeys"), + kmsProviders: new Dictionary> () + { + { "local", new Dictionary () { { "key", "" } } } + } + ), + }; + // end-settings-auto-encryption-options + } + + public void ClusterConfigurator() + { + // start-settings-cluster-configurator + var settings = new MongoClientSettings + { + ClusterConfigurator = builder => + { + builder + .Subscribe(e => + { + Console.WriteLine($"Cluster opened: Cluster ID = {e.ClusterId}"); + }) + .Subscribe(e => + { + Console.WriteLine($"Cluster description changed: {e.NewDescription}"); + }); + } + }; + // end-settings-cluster-configurator + } + + public void SslSettings() + { + // start-settings-ssl-settings + var settings = new MongoClientSettings(); + settings.SslSettings = new SslSettings() + { + CheckCertificateRevocation = false, + ClientCertificateSelectionCallback = new LocalCertificateSelectionCallback() { ... }, + ClientCertificates = new List() { ... }, + EnabledSslProtocols = SslProtocols.Tls13, + ServerCertificateValidationCallback = new RemoteCertificateValidationCallback() { ... } + }; + // end-settings-ssl-settings + } + + public void IsFrozen() + { + // start-settings-is-frozen + var settings = new MongoClientSettings(); + if (!settings.IsFrozen) + { + settings.RetryReads = false; + } + // end-settings-is-frozen + } + + public void WriteConcern() + { + // start-settings-write-concern + var settings = new MongoClientSettings(); + settings.WriteConcern = MongoDB.Driver.WriteConcern.Acknowledged; + settings.WriteConcern = new WriteConcern( + w: 1, + wTimeout: new TimeSpan(0, 0, 0, 30, 0), + fsync: true, + journal: true + ); + // end-settings-write-concern + } +} \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/maxConnectin.rst b/source/includes/fundamentals/connection-options/maxConnecting.rst similarity index 100% rename from source/includes/fundamentals/connection-options/maxConnectin.rst rename to source/includes/fundamentals/connection-options/maxConnecting.rst From bdf6dd6b307032033a82a9c781084e77db1ef1c1 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 28 May 2025 18:29:38 -0500 Subject: [PATCH 17/32] first draft --- source/connect/connection-options.txt | 322 ++++++++++++++---- .../connection/ConnectionOptions.cs | 158 +++++++++ .../connection/LocalConnectionConfig.cs | 11 - .../connection/MongoClientSettings.cs | 15 - .../connection/MongoClientSettingsConfig.cs | 17 - .../connection-options/srvServiceName.rst | 8 + 6 files changed, 428 insertions(+), 103 deletions(-) delete mode 100644 source/includes/fundamentals/code-examples/connection/LocalConnectionConfig.cs delete mode 100644 source/includes/fundamentals/code-examples/connection/MongoClientSettings.cs delete mode 100644 source/includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs create mode 100644 source/includes/fundamentals/connection-options/srvServiceName.rst diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 59a5865d..928b1ada 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -27,13 +27,17 @@ Connection Options Connection Pools Connect from AWS Lambda -This section describes the MongoDB connection and authentication options -available in the {+driver-short+}. You can configure your connection using either -the connection URI or a ``MongoClientSettings`` object. +This page describes the MongoDB connection and authentication options +available in the {+driver-short+}. + +--------------------------------- +How to Specify Connection Options +--------------------------------- + +The following sections describe the ways in which you can specify connection options. .. _csharp-connection-uri: ------------------------- Using the Connection URI ------------------------ @@ -42,20 +46,19 @@ connection options in the string as ``=`` pairs. In the following e the connection URI contains the ``connectTimeoutMS`` option with a value of ``60000`` and the ``tls`` option with a value of ``true``: -.. literalinclude:: /includes/fundamentals/code-examples/connection/LocalConnectionConfig.cs +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp :dedent: - :start-after: // start local connection config - :end-before: // end local connection config + :start-after: // start-connection-uri + :end-before: // end-connection-uri To learn more about the options that you can specify in a connection URI, see :manual:`` in the {+mdb-server+} manual. .. _csharp-mongo-client-settings: ------------------------------ -Using ``MongoClientSettings`` ------------------------------ +Using MongoClientSettings +------------------------- You can use a ``MongoClientSettings`` object to configure connection settings in code rather than in a connection URI. Configuring the connection this way makes it easier to @@ -65,25 +68,49 @@ more configuration options than the connection URI. To use a ``MongoClientSettings`` object, create an instance of the class, set its properties, and pass it as an argument to the ``MongoClient`` constructor: -.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp :dedent: - :start-after: // start mongo client settings config - :end-before: // end mongo client settings config + :start-after: // start-mongo-client-settings + :end-before: // end-mongo-client-settings + +You can also create a ``MongoClientSettings`` object from a connection string by calling the +``MongoClientSettings.FromConnectionString()`` method and passing the connection string, +as shown in the following example. This is useful if you already have a connection string +but want to modify some of the settings programmatically, or if you need to specify settings +that aren't available in the connection string. + +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :dedent: + :start-after: // start-mongo-client-settings + :end-before: // end-mongo-client-settings + +Alternatively, you can create a ``MongoClientSettings`` object from a ``MongoUrl`` object +by calling the ``MongoClientSettings.FromUrl()`` method and passing the ``MongoUrl`` +object, as shown in the following example. This is useful if you already have a ``MongoUrl`` +object but need to specify settings that aren't available in the ``MongoUrl`` class. + +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :dedent: + :start-after: // start-from-url + :end-before: // end-from-url .. _csharp-mongo-url-builder: ---------------------- Using MongoUrlBuilder --------------------- -You can use a ``MongoUrlBuilder`` object to configure connection settings in code -rather than in a connection URI. Configuring the connection this way makes it easier to -change settings at runtime, helps you catch errors during compilation, and provides -more configuration options than the connection URI. +You can use a ``MongoUrlBuilder`` object to create and configure connection settings on +a ``MongoUrl`` object. This has many of the same advantages as using a ``MongoClientSettings`` +object, although the two classes contain different properties and methods. -To use a ``MongoUrlBuilder`` object, create an instance of the class, set -its properties, and pass it as an argument to the ``MongoClient`` constructor: +To use a ``MongoUrlBuilder`` object, create an instance of the class and set the +necessary configuration properties. To create a ``MongoUrl`` object from the +``MongoUrlBuilder``, call the ``MongoUrlBuilder.ToMongoUrl()`` method. You can pass the +``MongoUrl`` object to the ``MongoClient`` constructor. The following code example shows +this process: .. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs :language: csharp @@ -91,34 +118,14 @@ its properties, and pass it as an argument to the ``MongoClient`` constructor: :start-after: // start mongo client settings config :end-before: // end mongo client settings config -.. tip:: Other MongoUrl Members - - The ``MongoUrl`` class contains other methods and read-only properties that you can - use to retrieve information about your connection. For a full list, see - `MongoUrl <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrl.html>`__ in the - API documentation. - -.. _csharp-replica-set-options: - +------------------ Connection Options ------------------ The following table lists each connection option available in the -``MongoClientSettings`` class, and, if possible, how to achieve the same result in the -connection string. If a ``MongoClientSettings`` property maps to more than one -option in the connection string, the **Connection URI Example** shows all -relevant options. +``MongoClientSettings`` and ``MongoUrlBuilder`` classes. -If you use your connection URI to create a ``MongoUrl`` or ``ConnectionString`` object, -you can use the object's read-only properties to access the values of the connection -options. These properties are listed in the ``MongoUrl`` column of the table. - -.. note:: - - If you're using a query parameter for a time duration, the value must be in - milliseconds. For example, to specify 60 seconds, use the value ``60000``. If you're - using a ``MongoClientSettings`` object for a time duration, use the appropriate - ``TimeSpan`` value. +.. _csharp-replica-set-options: Replica Set Options ------------------- @@ -128,18 +135,6 @@ Replica Set Options .. tab:: MongoClientSettings :tabid: mongo-client-settings - ReplicaSetName - ~~~~~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/replicaSetName.rst - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-replica-set-name - :end-before: // end-settings-replica-set-name - DirectConnection ~~~~~~~~~~~~~~~~ @@ -152,9 +147,6 @@ Replica Set Options :start-after: // start-settings-direct-connection :end-before: // end-settings-direct-connection - .. tab:: MongoUrlBuilder - :tabid: mongo-url-builder - ReplicaSetName ~~~~~~~~~~~~~~ @@ -164,8 +156,11 @@ Replica Set Options :language: csharp :copyable: true :dedent: 8 - :start-after: // start-builder-replica-set-name - :end-before: // end-builder-replica-set-name + :start-after: // start-settings-replica-set-name + :end-before: // end-settings-replica-set-name + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder DirectConnection ~~~~~~~~~~~~~~~~ @@ -179,6 +174,18 @@ Replica Set Options :start-after: // start-builder-direct-connection :end-before: // end-builder-direct-connection + ReplicaSetName + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/replicaSetName.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-replica-set-name + :end-before: // end-builder-replica-set-name + TLS Options ----------- @@ -243,6 +250,19 @@ TLS Options :start-after: // start-builder-allow-insecure-tls :end-before: // end-builder-allow-insecure-tls + TlsDisableCertificateRevocationCheck + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Whether to disable certificate revocation checking during the TLS handshake. The + default value is ``false``. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-tls-disable + :end-before: // end-builder-tls-disable + UseTls ~~~~~~ @@ -526,6 +546,70 @@ Write Concern Options :start-after: // start-settings-write-concern :end-before: // end-settings-write-concern + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + FSync + ~~~~~ + + The FSync component of the write concern. The default value is ``false``. To learn + more about the ``fsync`` command, see :manual:`fsync ` + in the {+mdb-server+} manual. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-fsync + :end-before: // end-builder-fsync + + Journal + ~~~~~~~ + + The ``j`` component of the write concern, which requests acknowledgment that the + MongoDB instances have written to the on-disk journal. The default value depends on + the value in the ``writeConcernMajorityJournalDefault`` setting. To learn more about the + ``j`` option, see :manual:`Write Concern ` + in the {+mdb-server+} manual. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-journal + :end-before: // end-builder-journal + + W + ~ + + The ``w`` component of the write concern, which requests acknowledgment that the write + operation has propagated to a specified number of MongoDB instances. The default + value is ``"majority"`` or ``1``, depending on the number of arbiters and voting nodes. + To learn more about the ``w`` option, see :manual:`Write Concern ` + in the {+mdb-server+} manual. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-w + :end-before: // end-builder-w + + WTimeout + ~~~~~~~~ + + The ``wtimeout`` component of the write concern, which specifies a time limit for the + write concern. To learn more about the ``wtimeout`` option, see + :manual:`Write Concern ` + in the {+mdb-server+} manual. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-w-timeout + :end-before: // end-builder-w-timeout + Read Concern Options -------------------- @@ -669,6 +753,32 @@ Authentication Options :end-before: // end-builder-authentication :emphasize-lines: 9 + Password + ~~~~~~~~ + + The password to use for authentication. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-username-password + :end-before: // end-builder-username-password + :emphasize-lines: 4 + + Username + ~~~~~~~~ + + The username to use for authentication. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-username-password + :end-before: // end-builder-username-password + :emphasize-lines: 3 + Server Selection and Discovery Options -------------------------------------- @@ -845,6 +955,14 @@ Miscellaneous Options :dedent: 8 :start-after: // start-settings-is-frozen :end-before: // end-settings-is-frozen + + .. tip:: Freeze Settings + + You can freeze the settings on a ``MongoClientSettings`` object by calling its + ``Freeze()`` method. This prevents any further changes to the settings. + + Alternatively, you can call the ``FrozenCopy()`` method to create a new + ``MongoClientSettings`` object with the current settings frozen. LoadBalanced ~~~~~~~~~~~~ @@ -982,6 +1100,18 @@ Miscellaneous Options :start-after: // start-settings-srv-max-hosts :end-before: // end-settings-srv-max-hosts + SrvServiceName + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/srvServiceName.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-srv-service-name + :end-before: // end-settings-srv-service-name + TranslationOptions ~~~~~~~~~~~~~~~~~~ @@ -995,6 +1125,20 @@ Miscellaneous Options :start-after: // start-settings-translation-options :end-before: // end-settings-translation-options + WriteEncoding + ~~~~~~~~~~~~~ + + The UTF-8 encoding to use for string serialization. The default value is + strict encoding, where the driver throws an exception when it encounters an invalid + UTF-8 byte sequence. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-write-encoding + :end-before: // end-settings-write-encoding + .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -1010,6 +1154,18 @@ Miscellaneous Options :start-after: // start-builder-application-name :end-before: // end-builder-application-name + DatabaseName + ~~~~~~~~~~~~ + + The name of the database that the client connects to. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-database-name + :end-before: // end-builder-database-name + IPv6 ~~~~ @@ -1117,3 +1273,49 @@ Miscellaneous Options :dedent: 8 :start-after: // start-builder-srv-max-hosts :end-before: // end-builder-srv-max-hosts + + SrvServiceName + ~~~~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/srvServiceName.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-srv-service-name + :end-before: // end-builder-srv-service-name + +====================== +Additional Information +====================== + +For more information about the types used on this page, see the +following API documentation: + +- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver.MongoClientSettings.html>`__ +- `MongoUrl <{+new-api-root+}/MongoDB.Driver.MongoUrl.html>`__ +- `MongoUrlBuilder <{+new-api-root+}/MongoDB.Driver.MongoUrlBuilder.html>`__ +- `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver.AutoEncryptionOptions.html>`__ +- `ClusterDescriptionChangedEvent <{+new-api-root+}/MongoDB.Driver.Events.ClusterDescriptionChangedEvent.html>`__ +- `ClusterOpenedEvent <{+new-api-root+}/MongoDB.Driver.Events.ClusterOpenedEvent.html>`__ +- `CollectionNamespace <{+new-api-root+}/MongoDB.Driver.CollectionNamespace.html>`__ +- `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver.CompressorConfiguration.html>`__ +- `CompressorType <{+new-api-root+}/MongoDB.Driver.CompressorType.html>`__ +- `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver.connectionStringScheme.html>`__ +- `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver.ExpressionTranslationOptions.html>`__ +- `LocalCertificateSelectionCallback <{+new-api-root+}/MongoDB.Driver.LocalCertificateSelectionCallback.html>`__ +- `LoggerFactory <{+new-api-root+}/MongoDB.Driver.LoggerFactory.Create.html>`__ +- `LoggingSettings <{+new-api-root+}/MongoDB.Driver.LoggingSettings.html>`__ +- `MongoCredential <{+new-api-root+}/MongoDB.Driver.CreatePlainCredential.html>`__ +- `MongoServerAddress <{+new-api-root+}/MongoDB.Driver.MongoServerAddress.html>`__ +- `ReadConcern <{+new-api-root+}/MongoDB.Driver.ReadConcern.html>`__ +- `ReadConcernLevel <{+new-api-root+}/MongoDB.Driver.ReadConcernLevel.html>`__ +- `ReadPreference <{+new-api-root+}/MongoDB.Driver.ReadPreference.html>`__ +- `RemoteCertificateValidationCallback <{+new-api-root+}/MongoDB.Driver.RemoteCertificateValidationCallback.html>`__ +- `ServerApi <{+new-api-root+}/MongoDB.Driver.ServerApi.html>`__ +- `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver.ServerMonitoringMode.html>`__ +- `SslSettings <{+new-api-root+}/MongoDB.Driver.SslSettings.html>`__ +- `UTF8Encoding <{+new-api-root+}/System.Text.UTF8Encoding.html>`__ +- `WriteConcern <{+new-api-root+}/MongoDB.Driver.WriteConcern.html>`__ +- `X509Certificate <{+new-api-root+}/System.Security.Cryptography.X509Certificates.X509Certificate.html>`__ \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs index 3a0b91b8..046885ba 100644 --- a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs +++ b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -12,6 +12,65 @@ namespace Connection; public class ConnectionOptions { + public void ConnectionUriExample() + { + // start-connection-uri + const string connectionUri = "mongodb+srv:/localhost:27017/?connectTimeoutMS=60000&tls=true"; + // end-connection-uri + } + + public void MongoClientSettingsExample() + { + // start-mongo-client-settings + var settings = new MongoClientSettings() + { + Scheme = ConnectionStringScheme.MongoDBPlusSrv, + Server = new MongoServerAddress("localhost", 27017), + ConnectTimeout = TimeSpan.FromMilliseconds(60000), + UseTls = true + }; + + var client = new MongoClient(settings); + // end-mongo-client-settings + } + + public void FromConnectionStringExample() + { + // start-from-connection-string + const string connectionUri = "mongodb+srv://localhost:27017/?connectTimeoutMS=60000&tls=true"; + var settings = MongoClientSettings.FromConnectionString(connectionUri); + settings.ServerApi = new ServerApi(ServerApiVersion.V1); + + var client = new MongoClient(settings); + // end-from-connection-string + } + + public void FromUrlExample() + { + // start-from-url + const string connectionUri = "mongodb+srv://localhost:27017/?connectTimeoutMS=60000&tls=true"; + var url = new MongoUrl(connectionUri); + var settings = MongoClientSettings.FromUrl(url); + settings.ServerApi = new ServerApi(ServerApiVersion.V1); + + var client = new MongoClient(settings); + // end-from-url + } + + public void MongoUrlBuilderExample() + { + // start-mongo-url-builder + const string connectionUri = "mongodb+srv://localhost:27017/?connectTimeoutMS=60000&tls=true"; + var builder = new MongoUrlBuilder(connectionUri) + { + ServerMonitoringMode = MongoDB.Driver.Core.Servers.ServerMonitoringMode.Stream + }; + var url = builder.ToMongoUrl(); + + var client = new MongoClient(url); + // end-mongo-url-builder + } + public void ReplicaSetName() { // start-settings-replica-set-name @@ -554,6 +613,93 @@ public void SrvMaxHosts() // end-builder-srv-max-hosts } + public void Journal() + { + // start-builder-journal + var builder = new MongoUrlBuilder + { + Journal = true + }; + // end-builder-journal + } + + public void TlsDisableCertificateRevocationCheck() + { + // start-builder-tls-disable + var builder = new MongoUrlBuilder + { + TlsDisableCertificateRevocationCheck = true + }; + // end-builder-tls-disable + } + + public void W() + { + // start-builder-w + var builder = new MongoUrlBuilder + { + W = 2 + }; + // end-builder-w + } + + public void WTimeout() + { + // start-builder-w-timeout + var builder = new MongoUrlBuilder + { + WTimeout = TimeSpan.FromSeconds(5) + }; + // end-builder-w-timeout + } + + public void UsernamePassword() + { + // start-builder-username-password + var builder = new MongoUrlBuilder + { + Username = "user", + Password = "password" + }; + // end-builder-username-password + } + + public void FSync() + { + // start-builder-fsync + var builder = new MongoUrlBuilder + { + FSync = true + }; + // end-builder-fsync + } + + public void DatabaseName() + { + // start-builder-database-name + var builder = new MongoUrlBuilder + { + DatabaseName = "test_database" + }; + // end-builder-database-name + } + + public void SrvServiceName() + { + // start-settings-srv-service-name + var settings = new MongoClientSettings + { + SrvServiceName = "yourServiceName" + }; + // end-settings-srv-service-name + + // start-builder-srv-service-name + var builder = new MongoUrlBuilder + { + SrvServiceName = "yourServiceName" + }; + // end-builder-srv-service-name + } public void TranslationOptions() { // start-settings-translation-options @@ -605,6 +751,18 @@ public void ReadEncoding() // end-settings-read-encoding } + public void WriteEncoding() + { + // start-settings-write-encoding + var settings = new MongoClientSettings + { + WriteEncoding = new UTF8Encoding( + encoderShouldEmitUTF8Identifier: false, + throwOnInvalidBytes: true) + }; + // end-settings-write-encoding + } + public void AutoEncryptionOptions() { // start-settings-auto-encryption-options diff --git a/source/includes/fundamentals/code-examples/connection/LocalConnectionConfig.cs b/source/includes/fundamentals/code-examples/connection/LocalConnectionConfig.cs deleted file mode 100644 index 01d84c84..00000000 --- a/source/includes/fundamentals/code-examples/connection/LocalConnectionConfig.cs +++ /dev/null @@ -1,11 +0,0 @@ -// Connects to a server by using a URI with configuration options - -// start local connection config -using MongoDB.Driver; - -// Sets the connection URI -const string connectionUri = "mongodb+srv://sample.host:27017/?connectTimeoutMS=60000&tls=true"; - -// Creates a new client and connects to the server -var client = new MongoClient(connectionUri); -// end local connection config \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/connection/MongoClientSettings.cs b/source/includes/fundamentals/code-examples/connection/MongoClientSettings.cs deleted file mode 100644 index c0009679..00000000 --- a/source/includes/fundamentals/code-examples/connection/MongoClientSettings.cs +++ /dev/null @@ -1,15 +0,0 @@ -// Defines a MongoClientSettings object to pass settings to the client - -// start mongo client settings -using MongoDB.Driver; - -// Creates a MongoClientSettings object -var settings = new MongoClientSettings() -{ - Scheme = ConnectionStringScheme.MongoDB, - Server = new MongoServerAddress("localhost", 27017) -}; - -// Creates a new client and connects to the server -var client = new MongoClient(settings); -// end mongo client settings \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs b/source/includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs deleted file mode 100644 index 04e8bea2..00000000 --- a/source/includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs +++ /dev/null @@ -1,17 +0,0 @@ -// Defines a MongoClientSettings object to pass configuration settings to the client - -// start mongo client settings config -//const string connectionUri = "mongodb+srv://sample.host:27017/?connectTimeoutMS=60000&tls=true"; - -// Creates a MongoClientSettings object -var settings = new MongoClientSettings() -{ - Scheme = ConnectionStringScheme.MongoDBPlusSrv, - Server = new MongoServerAddress("sample.host", 27017), - ConnectTimeout = new TimeSpan(0, 0, 60), - UseTls = true -}; - -// Creates a new client and connects to the server -var client = new MongoClient(settings); -// end mongo client settings config \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/srvServiceName.rst b/source/includes/fundamentals/connection-options/srvServiceName.rst new file mode 100644 index 00000000..eb7cc699 --- /dev/null +++ b/source/includes/fundamentals/connection-options/srvServiceName.rst @@ -0,0 +1,8 @@ +The SRV service name. The driver uses the service name to create the SRV URI, which mathces +the following format: + +.. code-block:: + + _{srvServiceName}._tcp.{hostname}.{domainname} + +The default value is ``"mongodb"``. \ No newline at end of file From 1c66f65edfa5a39b3c0271abfadbcd1f4db158da Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 29 May 2025 09:41:02 -0500 Subject: [PATCH 18/32] wip --- source/connect/connection-options.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 928b1ada..8b5e0e28 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -959,10 +959,11 @@ Miscellaneous Options .. tip:: Freeze Settings You can freeze the settings on a ``MongoClientSettings`` object by calling its - ``Freeze()`` method. This prevents any further changes to the settings. + `Freeze() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.Freeze.html>`__ + method. This prevents any further changes to the settings. - Alternatively, you can call the ``FrozenCopy()`` method to create a new - ``MongoClientSettings`` object with the current settings frozen. + Alternatively, you can call the `FrozenCopy() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.FrozenCopy.html>`__ + method to create a new ``MongoClientSettings`` object with the current settings frozen. LoadBalanced ~~~~~~~~~~~~ From 3e42fd6f57de23b613bb643bade7d3dd9db9a4fb Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 29 May 2025 09:57:45 -0500 Subject: [PATCH 19/32] fix api links --- source/connect/connection-options.txt | 79 ++++++++++--------- .../connection-options/readPreference.rst | 3 +- .../connection-options/scheme.rst | 4 +- 3 files changed, 45 insertions(+), 41 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 8b5e0e28..d9066236 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -49,11 +49,12 @@ and the ``tls`` option with a value of ``true``: .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp :dedent: - :start-after: // start-connection-uri + :start-after: // start-connection-uri :end-before: // end-connection-uri To learn more about the options that you can specify in a connection URI, see -:manual:`` in the {+mdb-server+} manual. +:manual:`Connection String Options ` in the ++mdb-server+} manual. .. _csharp-mongo-client-settings: @@ -72,7 +73,7 @@ its properties, and pass it as an argument to the ``MongoClient`` constructor: :language: csharp :dedent: :start-after: // start-mongo-client-settings - :end-before: // end-mongo-client-settings + :end-before: // end-mongo-client-settings You can also create a ``MongoClientSettings`` object from a connection string by calling the ``MongoClientSettings.FromConnectionString()`` method and passing the connection string, @@ -84,7 +85,7 @@ that aren't available in the connection string. :language: csharp :dedent: :start-after: // start-mongo-client-settings - :end-before: // end-mongo-client-settings + :end-before: // end-mongo-client-settings Alternatively, you can create a ``MongoClientSettings`` object from a ``MongoUrl`` object by calling the ``MongoClientSettings.FromUrl()`` method and passing the ``MongoUrl`` @@ -252,7 +253,7 @@ TLS Options TlsDisableCertificateRevocationCheck ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + Whether to disable certificate revocation checking during the TLS handshake. The default value is ``false``. @@ -537,7 +538,8 @@ Write Concern Options The default write-concern settings, including write timeout and journaling, for the client. The default value is ``WriteConcern.Acknowledged``. - See :ref:`write concern ` for more information. + See :manual:`Write Concern ` in the + {+mdb-server+} manual for more information. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp @@ -548,7 +550,7 @@ Write Concern Options .. tab:: MongoUrlBuilder :tabid: mongo-url-builder - + FSync ~~~~~ @@ -622,7 +624,8 @@ Read Concern Options ~~~~~~~~~~~ The client's read concern. The default value is ``ReadConcern.Default``. - For more information, see :ref:`read concern `. + For more information, see :manual:`Read Concern ` in the + {+mdb-server+} manual. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp @@ -696,7 +699,7 @@ Authentication Options f you don't specify an authentication mechanism, the driver uses either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256``, depending on the server version. See - :ref:`authentication mechanisms ` for available + :ref:`Authentication Mechanisms ` for available authentication mechanisms. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -955,7 +958,7 @@ Miscellaneous Options :dedent: 8 :start-after: // start-settings-is-frozen :end-before: // end-settings-is-frozen - + .. tip:: Freeze Settings You can freeze the settings on a ``MongoClientSettings`` object by calling its @@ -1055,8 +1058,8 @@ Miscellaneous Options ~~~~~~~~~ Allows opting into Stable API versioning. The default value is ``null``. See - :manual:`the MongoDB Manual` for more information about - Stable API versioning. + :manual:`Stable API ` in the {+mdb-server+} manual for more + information about Stable API versioning. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp @@ -1294,29 +1297,29 @@ Additional Information For more information about the types used on this page, see the following API documentation: -- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver.MongoClientSettings.html>`__ -- `MongoUrl <{+new-api-root+}/MongoDB.Driver.MongoUrl.html>`__ -- `MongoUrlBuilder <{+new-api-root+}/MongoDB.Driver.MongoUrlBuilder.html>`__ -- `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver.AutoEncryptionOptions.html>`__ -- `ClusterDescriptionChangedEvent <{+new-api-root+}/MongoDB.Driver.Events.ClusterDescriptionChangedEvent.html>`__ -- `ClusterOpenedEvent <{+new-api-root+}/MongoDB.Driver.Events.ClusterOpenedEvent.html>`__ -- `CollectionNamespace <{+new-api-root+}/MongoDB.Driver.CollectionNamespace.html>`__ -- `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver.CompressorConfiguration.html>`__ -- `CompressorType <{+new-api-root+}/MongoDB.Driver.CompressorType.html>`__ -- `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver.connectionStringScheme.html>`__ -- `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver.ExpressionTranslationOptions.html>`__ -- `LocalCertificateSelectionCallback <{+new-api-root+}/MongoDB.Driver.LocalCertificateSelectionCallback.html>`__ -- `LoggerFactory <{+new-api-root+}/MongoDB.Driver.LoggerFactory.Create.html>`__ -- `LoggingSettings <{+new-api-root+}/MongoDB.Driver.LoggingSettings.html>`__ -- `MongoCredential <{+new-api-root+}/MongoDB.Driver.CreatePlainCredential.html>`__ -- `MongoServerAddress <{+new-api-root+}/MongoDB.Driver.MongoServerAddress.html>`__ -- `ReadConcern <{+new-api-root+}/MongoDB.Driver.ReadConcern.html>`__ -- `ReadConcernLevel <{+new-api-root+}/MongoDB.Driver.ReadConcernLevel.html>`__ -- `ReadPreference <{+new-api-root+}/MongoDB.Driver.ReadPreference.html>`__ -- `RemoteCertificateValidationCallback <{+new-api-root+}/MongoDB.Driver.RemoteCertificateValidationCallback.html>`__ -- `ServerApi <{+new-api-root+}/MongoDB.Driver.ServerApi.html>`__ -- `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver.ServerMonitoringMode.html>`__ -- `SslSettings <{+new-api-root+}/MongoDB.Driver.SslSettings.html>`__ -- `UTF8Encoding <{+new-api-root+}/System.Text.UTF8Encoding.html>`__ -- `WriteConcern <{+new-api-root+}/MongoDB.Driver.WriteConcern.html>`__ -- `X509Certificate <{+new-api-root+}/System.Security.Cryptography.X509Certificates.X509Certificate.html>`__ \ No newline at end of file +- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__ +- `MongoUrl <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrl.html>`__ +- `MongoUrlBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrlBuilder.html>`__ +- `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AutoEncryptionOptions.html>`__ +- `ClusterDescriptionChangedEvent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Events.ClusterDescriptionChangedEvent.html>`__ +- `ClusterOpenedEvent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Events.ClusterOpenedEvent.html>`__ +- `CollectionNamespace <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollectionNamespace.html>`__ +- `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CompressorConfiguration.html>`__ +- `CompressorType <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CompressorType.html>`__ +- `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.connectionStringScheme.html>`__ +- `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ExpressionTranslationOptions.html>`__ +- `LocalCertificateSelectionCallback <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.LocalCertificateSelectionCallback.html>`__ +- `LoggerFactory <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.LoggerFactory.Create.html>`__ +- `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.LoggingSettings.html>`__ +- `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CreatePlainCredential.html>`__ +- `MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__ +- `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ +- `ReadConcernLevel <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcernLevel.html>`__ +- `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ +- `RemoteCertificateValidationCallback <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.RemoteCertificateValidationCallback.html>`__ +- `ServerApi <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerApi.html>`__ +- `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerMonitoringMode.html>`__ +- `SslSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SslSettings.html>`__ +- `UTF8Encoding <{+new-api-root+}/MongoDB.Driver/System.Text.UTF8Encoding.html>`__ +- `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ +- `X509Certificate <{+new-api-root+}/MongoDB.Driver/System.Security.Cryptography.X509Certificates.X509Certificate.html>`__ \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/readPreference.rst b/source/includes/fundamentals/connection-options/readPreference.rst index 982ab7a9..905d5e66 100644 --- a/source/includes/fundamentals/connection-options/readPreference.rst +++ b/source/includes/fundamentals/connection-options/readPreference.rst @@ -2,4 +2,5 @@ The client's default read-preference settings. ``MaxStaleness`` represents the longest replication lag, in wall-clock time, that a secondary can experience and still be eligible for server selection. The default value is ``ReadPreference.Primary``. Specifying ``-1`` means no maximum. -See :ref:`read preference ` for more information. \ No newline at end of file +See :manual:`Read Preference ` in the {+mdb-server+} manual +for more information. \ No newline at end of file diff --git a/source/includes/fundamentals/connection-options/scheme.rst b/source/includes/fundamentals/connection-options/scheme.rst index 44d49247..894343ed 100644 --- a/source/includes/fundamentals/connection-options/scheme.rst +++ b/source/includes/fundamentals/connection-options/scheme.rst @@ -2,8 +2,8 @@ Specifies whether to use the standard connection string format (``MongoDB``) or the DNS seed list format (``MongoDBPlusSrv``). The available values for this property are defined in the `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ConnectionStringScheme.html>`__ enum. The default value is ``ConnectionStringScheme.MongoDB``. -See :manual:`the MongoDB Manual` for more -information about connection string formats. +See :manual:`Connection Strings ` in the {+mdb-server+} +manual for more information about connection string formats. If the ``DirectConnection`` property is set to ``true`` and you try to use the DNS seed list format, the {+driver-short+} will throw an From a692968058a347f26e56ded1665aeb0f92eb4524 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 29 May 2025 10:14:47 -0500 Subject: [PATCH 20/32] wip --- source/connect/connection-options.txt | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index d9066236..6a580485 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -1301,25 +1301,18 @@ following API documentation: - `MongoUrl <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrl.html>`__ - `MongoUrlBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoUrlBuilder.html>`__ - `AutoEncryptionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AutoEncryptionOptions.html>`__ -- `ClusterDescriptionChangedEvent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Events.ClusterDescriptionChangedEvent.html>`__ -- `ClusterOpenedEvent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Events.ClusterOpenedEvent.html>`__ +- `ClusterDescriptionChangedEvent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Events.ClusterDescriptionChangedEvent.html>`__ +- `ClusterOpenedEvent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Events.ClusterOpenedEvent.html>`__ - `CollectionNamespace <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollectionNamespace.html>`__ -- `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CompressorConfiguration.html>`__ -- `CompressorType <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CompressorType.html>`__ -- `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.connectionStringScheme.html>`__ +- `CompressorConfiguration <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.CompressorConfiguration.html>`__ +- `CompressorType <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Compression.CompressorType.html>`__ +- `ConnectionStringScheme <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ConnectionStringScheme.html>`__ - `ExpressionTranslationOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ExpressionTranslationOptions.html>`__ -- `LocalCertificateSelectionCallback <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.LocalCertificateSelectionCallback.html>`__ -- `LoggerFactory <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.LoggerFactory.Create.html>`__ -- `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.LoggingSettings.html>`__ -- `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CreatePlainCredential.html>`__ +- `LoggingSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.LoggingSettings.html>`__ +- `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Credential.html>`__ - `MongoServerAddress <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoServerAddress.html>`__ - `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ - `ReadConcernLevel <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcernLevel.html>`__ - `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ -- `RemoteCertificateValidationCallback <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.RemoteCertificateValidationCallback.html>`__ - `ServerApi <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerApi.html>`__ -- `ServerMonitoringMode <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerMonitoringMode.html>`__ -- `SslSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SslSettings.html>`__ -- `UTF8Encoding <{+new-api-root+}/MongoDB.Driver/System.Text.UTF8Encoding.html>`__ -- `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ -- `X509Certificate <{+new-api-root+}/MongoDB.Driver/System.Security.Cryptography.X509Certificates.X509Certificate.html>`__ \ No newline at end of file +- `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ \ No newline at end of file From 39dcffd2016bb4cee5669cdb8b7e52b809ccb644 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 29 May 2025 10:21:15 -0500 Subject: [PATCH 21/32] fix --- source/connect/mongoclient.txt | 29 ++++++----------------------- 1 file changed, 6 insertions(+), 23 deletions(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 91477847..a93bc20e 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -85,18 +85,6 @@ For more information about creating a connection string, see :manual:`Connection Strings ` in the MongoDB Server documentation. -Formats -~~~~~~~ - -The {+driver-short+} provides the following classes for representing connection strings: - -A ``MongoURl`` object represents an immutable connection string. You can construct one -by calling the ``MongoUrl`` constructor and passing a connection string, or by -MongoUrlBuilder -- MongoUrl -- ConnectionString - -You can also just leave it as a string. MongoClient ----------- @@ -109,20 +97,15 @@ connection URI to connect to a MongoDB deployment running on port ``27017`` of ` const string uri = "mongodb://localhost:27017/"; var client = new MongoClient(uri); -Configure the MongoClient -------------------------- +Configure the Connection +----------------------- -You can configure settings for the ``MongoClient`` object by passing a -``MongoClientSettings`` object to the constructor. The following example creates a -``MongoClient`` object and sets the ``UseTls`` property to ``true``: - -.. code-block:: csharp +You can configure your connection in the following ways: - var connectionString = "mongodb://localhost:27017/" - var settings = MongoClientSettings.FromConnectionString(connectionString); - settings.UseTls = true; +- Specifying parameters in the connection URI +- Specifying settings on a ``MongoClientSettings`` or ``MongoUrlBuilder`` object -To view a full list of the settings you can configure, see the +To learn more about configuring your connection, see the :ref:`csharp-connection-options` guide. API Documentation From dd10bc2d365c69e66c636740a11289fa98b24e51 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 29 May 2025 17:28:25 -0500 Subject: [PATCH 22/32] add library info --- source/connect/connection-options.txt | 13 +++++++++++++ .../code-examples/connection/ConnectionOptions.cs | 11 +++++++++++ 2 files changed, 24 insertions(+) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 6a580485..9b92ef07 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -968,6 +968,19 @@ Miscellaneous Options Alternatively, you can call the `FrozenCopy() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.FrozenCopy.html>`__ method to create a new ``MongoClientSettings`` object with the current settings frozen. + LibraryInfo + ~~~~~~~~~~~ + + The name and version of a custom library built on the {+driver-short+}. The driver + sends this information to the server. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-library-info + :end-before: // end-settings-library-info + LoadBalanced ~~~~~~~~~~~~ diff --git a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs index 046885ba..def0e448 100644 --- a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs +++ b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -700,6 +700,17 @@ public void SrvServiceName() }; // end-builder-srv-service-name } + + public void LibraryInfo() + { + // start-settings-library-info + var settings = new MongoClientSettings + { + LibraryInfo = new LibraryInfo("customLibraryName", "1.0.0") + }; + // end-settings-library-info + } + public void TranslationOptions() { // start-settings-translation-options From 020be2d7ac5aa5260fb0f45c0f4a09eeb3713a26 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 30 May 2025 11:08:32 -0500 Subject: [PATCH 23/32] rr feedback --- source/connect/connection-options.txt | 243 ++++++++++-------- .../minConnectionPoolSize.rst | 2 +- 2 files changed, 142 insertions(+), 103 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 9b92ef07..2de3ad06 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -27,6 +27,10 @@ Connection Options Connection Pools Connect from AWS Lambda +-------- +Overview +-------- + This page describes the MongoDB connection and authentication options available in the {+driver-short+}. @@ -54,7 +58,7 @@ and the ``tls`` option with a value of ``true``: To learn more about the options that you can specify in a connection URI, see :manual:`Connection String Options ` in the -+mdb-server+} manual. +{+mdb-server+} manual. .. _csharp-mongo-client-settings: @@ -66,8 +70,14 @@ rather than in a connection URI. Configuring the connection this way makes it ea change settings at runtime, helps you catch errors during compilation, and provides more configuration options than the connection URI. -To use a ``MongoClientSettings`` object, create an instance of the class, set -its properties, and pass it as an argument to the ``MongoClient`` constructor: +To set connection options in a ``MongoClientSettings`` object, perform the +following steps: + +1. Create an instance of the ``MongoClientSettings`` class +#. Set properties on the instance to configure the connection +#. Pass the instance to the ``MongoClient`` constructor. + +The following code example shows how to perform the preceding steps: .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp @@ -78,19 +88,19 @@ its properties, and pass it as an argument to the ``MongoClient`` constructor: You can also create a ``MongoClientSettings`` object from a connection string by calling the ``MongoClientSettings.FromConnectionString()`` method and passing the connection string, as shown in the following example. This is useful if you already have a connection string -but want to modify some of the settings programmatically, or if you need to specify settings +but want to modify some settings programmatically, or if you want to specify settings that aren't available in the connection string. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp :dedent: - :start-after: // start-mongo-client-settings - :end-before: // end-mongo-client-settings + :start-after: // start-from-connection-string + :end-before: // end-from-connection-string Alternatively, you can create a ``MongoClientSettings`` object from a ``MongoUrl`` object by calling the ``MongoClientSettings.FromUrl()`` method and passing the ``MongoUrl`` object, as shown in the following example. This is useful if you already have a ``MongoUrl`` -object but need to specify settings that aren't available in the ``MongoUrl`` class. +object but want to specify settings that aren't available in the ``MongoUrl`` class. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp @@ -115,9 +125,9 @@ this process: .. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs :language: csharp - :dedent: - :start-after: // start mongo client settings config - :end-before: // end mongo client settings config + :dedent: 8 + :start-after: // start-mongo-url-builder + :end-before: // end-mongo-url-builder ------------------ Connection Options @@ -889,6 +899,123 @@ Server Selection and Discovery Options :start-after: // start-builder-server-selection-timeout :end-before: // end-builder-server-selection-timeout +Encoding Options +---------------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + ReadEncoding + ~~~~~~~~~~~~ + + The UTF-8 encoding to use for string deserialization. The default value is + strict encoding, where the driver throws an exception when it encounters an invalid + UTF-8 byte sequence. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-read-encoding + :end-before: // end-settings-read-encoding + + WriteEncoding + ~~~~~~~~~~~~~ + + The UTF-8 encoding to use for string serialization. The default value is + strict encoding, where the driver throws an exception when it encounters an invalid + UTF-8 byte sequence. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-write-encoding + :end-before: // end-settings-write-encoding + +Stable API +---------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + ServerApi + ~~~~~~~~~ + + Allows opting into Stable API versioning. The default value is ``null``. See + :manual:`Stable API ` in the {+mdb-server+} manual for more + information about Stable API versioning. + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-server-api + :end-before: // end-settings-server-api + +Retry Options +------------- + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + RetryReads + ~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryReads.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-retry-reads + :end-before: // end-settings-retry-reads + + RetryWrites + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryWrites.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-retry-writes + :end-before: // end-settings-retry-writes + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + RetryReads + ~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryReads.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-retry-reads + :end-before: // end-builder-retry-reads + + RetryWrites + ~~~~~~~~~~~ + + .. include:: /includes/fundamentals/connection-options/retryWrites.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-builder-retry-writes + :end-before: // end-builder-retry-writes + Miscellaneous Options --------------------- @@ -912,7 +1039,9 @@ Miscellaneous Options AutoEncryptionOptions ~~~~~~~~~~~~~~~~~~~~~ - Settings for automatic client-side encryption. The default value is ``null``. + Settings for automatic client-side encryption. The default value is ``null``. To + learn more about client-side encryption, see + :ref:`In-Use Encryption `. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp @@ -980,7 +1109,7 @@ Miscellaneous Options :dedent: 8 :start-after: // start-settings-library-info :end-before: // end-settings-library-info - + LoadBalanced ~~~~~~~~~~~~ @@ -1005,44 +1134,6 @@ Miscellaneous Options :start-after: // start-settings-logging-settings :end-before: // end-settings-logging-settings - ReadEncoding - ~~~~~~~~~~~~ - - The UTF-8 encoding to use for string deserialization. The default value is - strict encoding, where the driver throws an exception when it encounters an invalid - UTF-8 byte sequence. - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-read-encoding - :end-before: // end-settings-read-encoding - - RetryReads - ~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/retryReads.rst - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-retry-reads - :end-before: // end-settings-retry-reads - - RetryWrites - ~~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/retryWrites.rst - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-retry-writes - :end-before: // end-settings-retry-writes - Scheme ~~~~~~ @@ -1067,20 +1158,6 @@ Miscellaneous Options :start-after: // start-settings-server :end-before: // end-settings-server - ServerApi - ~~~~~~~~~ - - Allows opting into Stable API versioning. The default value is ``null``. See - :manual:`Stable API ` in the {+mdb-server+} manual for more - information about Stable API versioning. - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-server-api - :end-before: // end-settings-server-api - ServerMonitoringMode ~~~~~~~~~~~~~~~~~~~~ @@ -1142,20 +1219,6 @@ Miscellaneous Options :start-after: // start-settings-translation-options :end-before: // end-settings-translation-options - WriteEncoding - ~~~~~~~~~~~~~ - - The UTF-8 encoding to use for string serialization. The default value is - strict encoding, where the driver throws an exception when it encounters an invalid - UTF-8 byte sequence. - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-write-encoding - :end-before: // end-settings-write-encoding - .. tab:: MongoUrlBuilder :tabid: mongo-url-builder @@ -1207,30 +1270,6 @@ Miscellaneous Options :start-after: // start-builder-load-balanced :end-before: // end-builder-load-balanced - RetryReads - ~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/retryReads.rst - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-builder-retry-reads - :end-before: // end-builder-retry-reads - - RetryWrites - ~~~~~~~~~~~ - - .. include:: /includes/fundamentals/connection-options/retryWrites.rst - - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-builder-retry-writes - :end-before: // end-builder-retry-writes - Scheme ~~~~~~ diff --git a/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst b/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst index 08782310..eb3d4a3e 100644 --- a/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst +++ b/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst @@ -1,3 +1,3 @@ -The number of connections the driver should create and keep in the connection +The number of connections the driver creates and keeps in the connection pool even when no operations are occurring. This count includes connections in use. The default value is ``0``. \ No newline at end of file From d9c5d0ade3e4314a22f1e0f041a257526fa71b63 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 30 May 2025 11:27:50 -0500 Subject: [PATCH 24/32] fixes --- source/connect/connection-options.txt | 80 +++++++++++++-------------- 1 file changed, 39 insertions(+), 41 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 2de3ad06..9ec46f90 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -133,7 +133,7 @@ this process: Connection Options ------------------ -The following table lists each connection option available in the +The following sections describe each connection option available in the ``MongoClientSettings`` and ``MongoUrlBuilder`` classes. .. _csharp-replica-set-options: @@ -902,60 +902,58 @@ Server Selection and Discovery Options Encoding Options ---------------- -.. tabs:: +ReadEncoding +~~~~~~~~~~~ - .. tab:: MongoClientSettings - :tabid: mongo-client-settings +The UTF-8 encoding to use for string deserialization. The default value is +strict encoding, where the driver throws an exception when it encounters an invalid +UTF-8 byte sequence - ReadEncoding - ~~~~~~~~~~~~ +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-read-encoding + :end-before: // end-settings-read-encodin - The UTF-8 encoding to use for string deserialization. The default value is - strict encoding, where the driver throws an exception when it encounters an invalid - UTF-8 byte sequence. +WriteEncoding +~~~~~~~~~~~~ +The UTF-8 encoding to use for string serialization. The default value is +strict encoding, where the driver throws an exception when it encounters an invalid +UTF-8 byte sequence - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-read-encoding - :end-before: // end-settings-read-encoding - - WriteEncoding - ~~~~~~~~~~~~~ +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-write-encoding + :end-before: // end-settings-write-encoding - The UTF-8 encoding to use for string serialization. The default value is - strict encoding, where the driver throws an exception when it encounters an invalid - UTF-8 byte sequence. +.. note:: MongoClientSettings Only - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-write-encoding - :end-before: // end-settings-write-encoding + The ``ReadEncoding`` and ``WriteEncoding`` properties are available only in the + ``MongoClientSettings`` class. Stable API ---------- -.. tabs:: +ServerApi +~~~~~~~~ - .. tab:: MongoClientSettings - :tabid: mongo-client-settings +Allows opting into Stable API versioning. The default value is ``null``. See +:manual:`Stable API ` in the {+mdb-server+} manual for more +information about Stable API versioning. - ServerApi - ~~~~~~~~~ +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-server-api + :end-before: // end-settings-server-api - Allows opting into Stable API versioning. The default value is ``null``. See - :manual:`Stable API ` in the {+mdb-server+} manual for more - information about Stable API versioning. +.. note:: MongoClientSettings Only - .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs - :language: csharp - :copyable: true - :dedent: 8 - :start-after: // start-settings-server-api - :end-before: // end-settings-server-api + The ``ServerApi`` property is available only in the ``MongoClientSettings`` class. Retry Options ------------- From 04224782e80cd5f3a6bfbecebe37d67ab6e61c09 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Jun 2025 17:59:47 -0500 Subject: [PATCH 25/32] rr feedback --- source/connect/connection-options.txt | 42 +++++++++---------- source/connect/mongoclient.txt | 2 +- .../connection-options/loadBalanced.rst | 2 +- 3 files changed, 22 insertions(+), 24 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 9ec46f90..c4a90f35 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -27,23 +27,21 @@ Connection Options Connection Pools Connect from AWS Lambda --------- Overview -------- This page describes the MongoDB connection and authentication options available in the {+driver-short+}. ---------------------------------- -How to Specify Connection Options ---------------------------------- +Specify Connection Options +-------------------------- The following sections describe the ways in which you can specify connection options. .. _csharp-connection-uri: Using the Connection URI ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ If you pass a connection URI to the ``MongoClient`` constructor, you can include connection options in the string as ``=`` pairs. In the following example, @@ -63,7 +61,7 @@ To learn more about the options that you can specify in a connection URI, see .. _csharp-mongo-client-settings: Using MongoClientSettings -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ You can use a ``MongoClientSettings`` object to configure connection settings in code rather than in a connection URI. Configuring the connection this way makes it easier to @@ -111,11 +109,14 @@ object but want to specify settings that aren't available in the ``MongoUrl`` cl .. _csharp-mongo-url-builder: Using MongoUrlBuilder ---------------------- +~~~~~~~~~~~~~~~~~~~~~ You can use a ``MongoUrlBuilder`` object to create and configure connection settings on -a ``MongoUrl`` object. This has many of the same advantages as using a ``MongoClientSettings`` -object, although the two classes contain different properties and methods. +a ``MongoUrl`` object. A ``MongoUrl`` is a strongly typed representation of a +connection URI, and is useful when reading a connection URI directly from +another source. Using a ``MongoUrl`` object has many of the same advantages as using +a ``MongoClientSettings`` object, although the two classes contain different properties +and methods. To use a ``MongoUrlBuilder`` object, create an instance of the class and set the necessary configuration properties. To create a ``MongoUrl`` object from the @@ -123,16 +124,12 @@ necessary configuration properties. To create a ``MongoUrl`` object from the ``MongoUrl`` object to the ``MongoClient`` constructor. The following code example shows this process: -.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp :dedent: 8 :start-after: // start-mongo-url-builder :end-before: // end-mongo-url-builder ------------------- -Connection Options ------------------- - The following sections describe each connection option available in the ``MongoClientSettings`` and ``MongoUrlBuilder`` classes. @@ -707,7 +704,7 @@ Authentication Options authentication credentials, mechanism, source, and other settings. The default value is ``null``. - f you don't specify an authentication mechanism, the driver uses either + If you don't specify an authentication mechanism, the driver uses either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256``, depending on the server version. See :ref:`Authentication Mechanisms ` for available authentication mechanisms. @@ -914,10 +911,11 @@ UTF-8 byte sequence :copyable: true :dedent: 8 :start-after: // start-settings-read-encoding - :end-before: // end-settings-read-encodin + :end-before: // end-settings-read-encoding WriteEncoding -~~~~~~~~~~~~ +~~~~~~~~~~~~~ + The UTF-8 encoding to use for string serialization. The default value is strict encoding, where the driver throws an exception when it encounters an invalid UTF-8 byte sequence @@ -1076,8 +1074,8 @@ Miscellaneous Options IsFrozen ~~~~~~~~ - Indicates whether the settings have been frozen. Frozen settings can't be changed. - This option is read-only. The default value is ``false``. + A read-only option that indicates whether the settings have been frozen. You can't + change frozen settings. The default value is ``false``. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs :language: csharp @@ -1092,7 +1090,8 @@ Miscellaneous Options `Freeze() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.Freeze.html>`__ method. This prevents any further changes to the settings. - Alternatively, you can call the `FrozenCopy() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.FrozenCopy.html>`__ + Alternatively, you can call the `FrozenCopy() + <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.FrozenCopy.html>`__ method to create a new ``MongoClientSettings`` object with the current settings frozen. LibraryInfo @@ -1340,9 +1339,8 @@ Miscellaneous Options :start-after: // start-builder-srv-service-name :end-before: // end-builder-srv-service-name -====================== Additional Information -====================== +---------------------- For more information about the types used on this page, see the following API documentation: diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index a93bc20e..e4ef8697 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -98,7 +98,7 @@ connection URI to connect to a MongoDB deployment running on port ``27017`` of ` var client = new MongoClient(uri); Configure the Connection ------------------------ +------------------------ You can configure your connection in the following ways: diff --git a/source/includes/fundamentals/connection-options/loadBalanced.rst b/source/includes/fundamentals/connection-options/loadBalanced.rst index 0d327850..140232ea 100644 --- a/source/includes/fundamentals/connection-options/loadBalanced.rst +++ b/source/includes/fundamentals/connection-options/loadBalanced.rst @@ -1,5 +1,5 @@ Specifies whether the driver is connecting to a load balancer. You can set this -property to ``true`` only if: +property to ``true`` only if all of the following conditions are met: - You specify just one host name. - You're not connecting to a replica set. From 5e9844177327d7c5a4c44c31066819cdac9e1991 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Jun 2025 18:01:49 -0500 Subject: [PATCH 26/32] longer title --- source/connect/connection-options.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index c4a90f35..b806ab8a 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -1,8 +1,8 @@ .. _csharp-connection-options: -================== -Connection Options -================== +============================== +Configure a MongoDB Connection +============================== .. facet:: :name: genre From 24d67eb4e1416e1567dae44ec54cee6ab7640e4f Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Jun 2025 18:03:24 -0500 Subject: [PATCH 27/32] TOC title --- source/connect.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect.txt b/source/connect.txt index 6f15db31..caec388b 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -24,5 +24,5 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target - Specify Connection Options + Configure a Connection Connection Troubleshooting \ No newline at end of file From ebf3621bd129c11597ad1fef140fb5234fe91558 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Jun 2025 19:14:08 -0500 Subject: [PATCH 28/32] formatting fixes --- source/connect/connection-options.txt | 16 ++++++---------- .../connection-options/loadBalanced.rst | 8 ++++---- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index b806ab8a..231672fa 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -1,8 +1,8 @@ .. _csharp-connection-options: -============================== -Configure a MongoDB Connection -============================== +========================== +Specify Connection Options +========================== .. facet:: :name: genre @@ -30,11 +30,10 @@ Configure a MongoDB Connection Overview -------- -This page describes the MongoDB connection and authentication options -available in the {+driver-short+}. +This page describes the MongoDB connection options available in the {+driver-short+}. -Specify Connection Options --------------------------- +How to Specify Connection Options +--------------------------------- The following sections describe the ways in which you can specify connection options. @@ -130,9 +129,6 @@ this process: :start-after: // start-mongo-url-builder :end-before: // end-mongo-url-builder -The following sections describe each connection option available in the -``MongoClientSettings`` and ``MongoUrlBuilder`` classes. - .. _csharp-replica-set-options: Replica Set Options diff --git a/source/includes/fundamentals/connection-options/loadBalanced.rst b/source/includes/fundamentals/connection-options/loadBalanced.rst index 140232ea..d50cd12a 100644 --- a/source/includes/fundamentals/connection-options/loadBalanced.rst +++ b/source/includes/fundamentals/connection-options/loadBalanced.rst @@ -1,9 +1,9 @@ Specifies whether the driver is connecting to a load balancer. You can set this property to ``true`` only if all of the following conditions are met: -- You specify just one host name. -- You're not connecting to a replica set. -- You're not using the ``SrvMaxHosts`` property. -- You're not using the ``DirectConnection`` property. +- You specify just one host name +- You're not connecting to a replica set +- You're not using the ``SrvMaxHosts`` property +- You're not using the ``DirectConnection`` property The default value is ``false``. \ No newline at end of file From 913c0ba7cb8c9b2814e15aa5b09a65ed3241b479 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Jun 2025 19:27:12 -0500 Subject: [PATCH 29/32] fixes --- source/connect/connection-options.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 231672fa..2d3e4053 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -30,7 +30,8 @@ Specify Connection Options Overview -------- -This page describes the MongoDB connection options available in the {+driver-short+}. +This page describes the connection options available in the {+driver-short+} and +explains how to apply them to your MongoDB connection. How to Specify Connection Options --------------------------------- @@ -72,7 +73,7 @@ following steps: 1. Create an instance of the ``MongoClientSettings`` class #. Set properties on the instance to configure the connection -#. Pass the instance to the ``MongoClient`` constructor. +#. Pass the instance to the ``MongoClient`` constructor The following code example shows how to perform the preceding steps: @@ -896,7 +897,7 @@ Encoding Options ---------------- ReadEncoding -~~~~~~~~~~~ +~~~~~~~~~~~~ The UTF-8 encoding to use for string deserialization. The default value is strict encoding, where the driver throws an exception when it encounters an invalid @@ -932,7 +933,7 @@ Stable API ---------- ServerApi -~~~~~~~~ +~~~~~~~~~ Allows opting into Stable API versioning. The default value is ``null``. See :manual:`Stable API ` in the {+mdb-server+} manual for more From adb862a28ec544faf662d56cf83e872adaf6c10d Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Jun 2025 19:37:35 -0500 Subject: [PATCH 30/32] test --- source/connect/connection-options.txt | 201 +++++++++++++------------- 1 file changed, 102 insertions(+), 99 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 2d3e4053..bcf38e3e 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -130,10 +130,13 @@ this process: :start-after: // start-mongo-url-builder :end-before: // end-mongo-url-builder +Connection Options +------------------ + .. _csharp-replica-set-options: Replica Set Options -------------------- +~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -141,7 +144,7 @@ Replica Set Options :tabid: mongo-client-settings DirectConnection - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/directConnection.rst @@ -153,7 +156,7 @@ Replica Set Options :end-before: // end-settings-direct-connection ReplicaSetName - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/replicaSetName.rst @@ -168,7 +171,7 @@ Replica Set Options :tabid: mongo-url-builder DirectConnection - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/directConnection.rst @@ -180,7 +183,7 @@ Replica Set Options :end-before: // end-builder-direct-connection ReplicaSetName - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/replicaSetName.rst @@ -192,7 +195,7 @@ Replica Set Options :end-before: // end-builder-replica-set-name TLS Options ------------ +~~~~~~~~~~~ .. tabs:: @@ -200,7 +203,7 @@ TLS Options :tabid: mongo-client-settings AllowInsecureTls - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst @@ -212,7 +215,7 @@ TLS Options :end-before: // end-settings-allow-insecure-tls SslSettings - ~~~~~~~~~~~ + ``````````` TLS/SSL options, including client certificates, revocation handling, and enabled and disabled TLS/SSL protocols. The default value is ``null``. @@ -229,7 +232,7 @@ TLS Options :end-before: // end-settings-ssl-settings UseTls - ~~~~~~ + `````` .. include:: /includes/fundamentals/connection-options/useTls.rst @@ -244,7 +247,7 @@ TLS Options :tabid: mongo-url-builder AllowInsecureTls - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst @@ -256,7 +259,7 @@ TLS Options :end-before: // end-builder-allow-insecure-tls TlsDisableCertificateRevocationCheck - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ```````````````````````````````````` Whether to disable certificate revocation checking during the TLS handshake. The default value is ``false``. @@ -269,7 +272,7 @@ TLS Options :end-before: // end-builder-tls-disable UseTls - ~~~~~~ + `````` .. include:: /includes/fundamentals/connection-options/useTls.rst @@ -281,7 +284,7 @@ TLS Options :end-before: // end-builder-use-tls Timeout Options ---------------- +~~~~~~~~~~~~~~~ .. tabs:: @@ -289,7 +292,7 @@ Timeout Options :tabid: mongo-client-settings ConnectTimeout - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/connectTimeout.rst @@ -301,7 +304,7 @@ Timeout Options :end-before: // end-settings-connect-timeout SocketTimeout - ~~~~~~~~~~~~~ + ````````````` .. include:: /includes/fundamentals/connection-options/socketTimeout.rst @@ -316,7 +319,7 @@ Timeout Options :tabid: mongo-url-builder ConnectTimeout - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/connectTimeout.rst @@ -328,7 +331,7 @@ Timeout Options :end-before: // end-builder-connect-timeout SocketTimeout - ~~~~~~~~~~~~~ + ````````````` .. include:: /includes/fundamentals/connection-options/socketTimeout.rst @@ -340,7 +343,7 @@ Timeout Options :end-before: // end-builder-socket-timeout Compression Options -------------------- +~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -348,7 +351,7 @@ Compression Options :tabid: mongo-client-settings Compressors - ~~~~~~~~~~~ + ``````````` .. include:: /includes/fundamentals/connection-options/compressors.rst @@ -363,7 +366,7 @@ Compression Options :tabid: mongo-url-builder Compressors - ~~~~~~~~~~~ + ``````````` .. include:: /includes/fundamentals/connection-options/compressors.rst @@ -375,7 +378,7 @@ Compression Options :end-before: // end-builder-compressors Connection Pool Options ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -383,7 +386,7 @@ Connection Pool Options :tabid: mongo-client-settings MaxConnecting - ~~~~~~~~~~~~~ + ````````````` .. include:: /includes/fundamentals/connection-options/maxConnecting.rst @@ -395,7 +398,7 @@ Connection Pool Options :end-before: // end-settings-max-connecting MaxConnectionIdleTime - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/maxConnectionIdleTime.rst @@ -407,7 +410,7 @@ Connection Pool Options :end-before: // end-settings-max-connection-idle-time MaxConnectionLifeTime - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/maxConnectionLifetime.rst @@ -419,7 +422,7 @@ Connection Pool Options :end-before: // end-settings-max-connection-life-time MaxConnectionPoolSize - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/maxConnectionPoolSize.rst @@ -431,7 +434,7 @@ Connection Pool Options :end-before: // end-settings-max-connection-pool-size MinConnectionPoolSize - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/minConnectionPoolSize.rst @@ -443,7 +446,7 @@ Connection Pool Options :end-before: // end-settings-min-connection-pool-size WaitQueueTimeout - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/waitQueueTimeout.rst @@ -458,7 +461,7 @@ Connection Pool Options :tabid: mongo-url-builder MaxConnecting - ~~~~~~~~~~~~~ + ````````````` .. include:: /includes/fundamentals/connection-options/maxConnecting.rst @@ -470,7 +473,7 @@ Connection Pool Options :end-before: // end-builder-max-connecting MaxConnectionIdleTime - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/maxConnectionIdleTime.rst @@ -482,7 +485,7 @@ Connection Pool Options :end-before: // end-builder-max-connection-idle-time MaxConnectionLifeTime - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/maxConnectionLifetime.rst @@ -494,7 +497,7 @@ Connection Pool Options :end-before: // end-builder-max-connection-life-time MaxConnectionPoolSize - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/maxConnectionPoolSize.rst @@ -506,7 +509,7 @@ Connection Pool Options :end-before: // end-builder-max-connection-pool-size MinConnectionPoolSize - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` .. include:: /includes/fundamentals/connection-options/minConnectionPoolSize.rst @@ -518,7 +521,7 @@ Connection Pool Options :end-before: // end-builder-min-connection-pool-size WaitQueueTimeout - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/waitQueueTimeout.rst @@ -530,7 +533,7 @@ Connection Pool Options :end-before: // end-builder-wait-queue-timeout Write Concern Options ---------------------- +~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -538,7 +541,7 @@ Write Concern Options :tabid: mongo-client-settings WriteConcern - ~~~~~~~~~~~~ + ```````````` The default write-concern settings, including write timeout and journaling, for the client. The default value is ``WriteConcern.Acknowledged``. @@ -556,7 +559,7 @@ Write Concern Options :tabid: mongo-url-builder FSync - ~~~~~ + ````` The FSync component of the write concern. The default value is ``false``. To learn more about the ``fsync`` command, see :manual:`fsync ` @@ -570,7 +573,7 @@ Write Concern Options :end-before: // end-builder-fsync Journal - ~~~~~~~ + ``````` The ``j`` component of the write concern, which requests acknowledgment that the MongoDB instances have written to the on-disk journal. The default value depends on @@ -586,7 +589,7 @@ Write Concern Options :end-before: // end-builder-journal W - ~ + `` The ``w`` component of the write concern, which requests acknowledgment that the write operation has propagated to a specified number of MongoDB instances. The default @@ -602,7 +605,7 @@ Write Concern Options :end-before: // end-builder-w WTimeout - ~~~~~~~~ + ```````` The ``wtimeout`` component of the write concern, which specifies a time limit for the write concern. To learn more about the ``wtimeout`` option, see @@ -617,7 +620,7 @@ Write Concern Options :end-before: // end-builder-w-timeout Read Concern Options --------------------- +~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -625,7 +628,7 @@ Read Concern Options :tabid: mongo-client-settings ReadConcern - ~~~~~~~~~~~ + ``````````` The client's read concern. The default value is ``ReadConcern.Default``. For more information, see :manual:`Read Concern ` in the @@ -642,7 +645,7 @@ Read Concern Options :tabid: mongo-url-builder ReadConcernLevel - ~~~~~~~~~~~~~~~~ + ```````````````` The client's read concern level. The default value is ``ReadConcern.Local``. For more information, see :ref:`read concern `. @@ -655,7 +658,7 @@ Read Concern Options :end-before: // end-builder-read-concern-level Read Preference Options ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -663,7 +666,7 @@ Read Preference Options :tabid: mongo-client-settings ReadPreference - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/readPreference.rst @@ -687,7 +690,7 @@ Read Preference Options :end-before: // end-builder-read-preference Authentication Options ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -695,7 +698,7 @@ Authentication Options :tabid: mongo-client-settings Credential - ~~~~~~~~~~ + `````````` Settings for how the driver authenticates to the server. This includes authentication credentials, mechanism, source, and other settings. The default @@ -717,7 +720,7 @@ Authentication Options :tabid: mongo-url-builder AuthenticationMechanism - ~~~~~~~~~~~~~~~~~~~~~~~ + ``````````````````````` The mechanism that the driver uses to authenticate to {+mdb-server+}. If you don't specify an authentication mechanism, the driver uses either @@ -734,7 +737,7 @@ Authentication Options :emphasize-lines: 3 AuthenticationMechanismProperties - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ````````````````````````````````` Configuration settings for the authentication mechanism specified in the ``AuthenticationMechanism`` property. @@ -748,7 +751,7 @@ Authentication Options :emphasize-lines: 4-8 AuthenticationSource - ~~~~~~~~~~~~~~~~~~~~ + ```````````````````` The source to authenticate the client against. @@ -761,7 +764,7 @@ Authentication Options :emphasize-lines: 9 Password - ~~~~~~~~ + ```````` The password to use for authentication. @@ -774,7 +777,7 @@ Authentication Options :emphasize-lines: 4 Username - ~~~~~~~~ + ```````` The username to use for authentication. @@ -787,7 +790,7 @@ Authentication Options :emphasize-lines: 3 Server Selection and Discovery Options --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -795,7 +798,7 @@ Server Selection and Discovery Options :tabid: mongo-client-settings HeartbeatInterval - ~~~~~~~~~~~~~~~~~ + ````````````````` .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst @@ -807,7 +810,7 @@ Server Selection and Discovery Options :end-before: // end-settings-heartbeat-interval HeartbeatTimeout - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/heartbeatTimeout.rst @@ -819,7 +822,7 @@ Server Selection and Discovery Options :end-before: // end-settings-heartbeat-timeout LocalThreshold - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/localThreshold.rst @@ -831,7 +834,7 @@ Server Selection and Discovery Options :end-before: // end-settings-local-threshold ServerSelectionTimeout - ~~~~~~~~~~~~~~~~~~~~~~ + `````````````````````` .. include:: /includes/fundamentals/connection-options/localThreshold.rst @@ -846,7 +849,7 @@ Server Selection and Discovery Options :tabid: mongo-url-builder HeartbeatInterval - ~~~~~~~~~~~~~~~~~ + ````````````````` .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst @@ -858,7 +861,7 @@ Server Selection and Discovery Options :end-before: // end-builder-heartbeat-interval HeartbeatTimeout - ~~~~~~~~~~~~~~~~ + ```````````````` .. include:: /includes/fundamentals/connection-options/heartbeatTimeout.rst @@ -870,7 +873,7 @@ Server Selection and Discovery Options :end-before: // end-builder-heartbeat-timeout LocalThreshold - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/localThreshold.rst @@ -882,7 +885,7 @@ Server Selection and Discovery Options :end-before: // end-builder-local-threshold ServerSelectionTimeout - ~~~~~~~~~~~~~~~~~~~~~~ + `````````````````````` .. include:: /includes/fundamentals/connection-options/localThreshold.rst @@ -894,10 +897,10 @@ Server Selection and Discovery Options :end-before: // end-builder-server-selection-timeout Encoding Options ----------------- +~~~~~~~~~~~~~~~~ ReadEncoding -~~~~~~~~~~~~ +```````````` The UTF-8 encoding to use for string deserialization. The default value is strict encoding, where the driver throws an exception when it encounters an invalid @@ -911,7 +914,7 @@ UTF-8 byte sequence :end-before: // end-settings-read-encoding WriteEncoding -~~~~~~~~~~~~~ +````````````` The UTF-8 encoding to use for string serialization. The default value is strict encoding, where the driver throws an exception when it encounters an invalid @@ -930,10 +933,10 @@ UTF-8 byte sequence ``MongoClientSettings`` class. Stable API ----------- +~~~~~~~~~~ ServerApi -~~~~~~~~~ +````````` Allows opting into Stable API versioning. The default value is ``null``. See :manual:`Stable API ` in the {+mdb-server+} manual for more @@ -951,7 +954,7 @@ information about Stable API versioning. The ``ServerApi`` property is available only in the ``MongoClientSettings`` class. Retry Options -------------- +~~~~~~~~~~~~~ .. tabs:: @@ -959,8 +962,8 @@ Retry Options :tabid: mongo-client-settings RetryReads - ~~~~~~~~~~ - + `````````` + .. include:: /includes/fundamentals/connection-options/retryReads.rst .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -971,8 +974,8 @@ Retry Options :end-before: // end-settings-retry-reads RetryWrites - ~~~~~~~~~~~ - + ``````````` + .. include:: /includes/fundamentals/connection-options/retryWrites.rst .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -986,8 +989,8 @@ Retry Options :tabid: mongo-url-builder RetryReads - ~~~~~~~~~~ - + `````````` + .. include:: /includes/fundamentals/connection-options/retryReads.rst .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -998,7 +1001,7 @@ Retry Options :end-before: // end-builder-retry-reads RetryWrites - ~~~~~~~~~~~ + ``````````` .. include:: /includes/fundamentals/connection-options/retryWrites.rst @@ -1010,7 +1013,7 @@ Retry Options :end-before: // end-builder-retry-writes Miscellaneous Options ---------------------- +~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -1018,7 +1021,7 @@ Miscellaneous Options :tabid: mongo-client-settings ApplicationName - ~~~~~~~~~~~~~~~ + ``````````````` .. include:: /includes/fundamentals/connection-options/applicationName.rst @@ -1030,7 +1033,7 @@ Miscellaneous Options :end-before: // end-settings-application-name AutoEncryptionOptions - ~~~~~~~~~~~~~~~~~~~~~ + ````````````````````` Settings for automatic client-side encryption. The default value is ``null``. To learn more about client-side encryption, see @@ -1044,7 +1047,7 @@ Miscellaneous Options :end-before: // end-settings-auto-encryption-options ClusterConfigurator - ~~~~~~~~~~~~~~~~~~~ + ``````````````````` Low-level configuration options for sockets, TLS, cluster, and others. The default value is ``null``. @@ -1057,7 +1060,7 @@ Miscellaneous Options :end-before: // end-settings-cluster-configurator IPv6 - ~~~~ + ```` .. include:: /includes/fundamentals/connection-options/ipv6.rst @@ -1069,7 +1072,7 @@ Miscellaneous Options :end-before: // end-settings-ipv6 IsFrozen - ~~~~~~~~ + ```````` A read-only option that indicates whether the settings have been frozen. You can't change frozen settings. The default value is ``false``. @@ -1092,7 +1095,7 @@ Miscellaneous Options method to create a new ``MongoClientSettings`` object with the current settings frozen. LibraryInfo - ~~~~~~~~~~~ + ``````````` The name and version of a custom library built on the {+driver-short+}. The driver sends this information to the server. @@ -1105,7 +1108,7 @@ Miscellaneous Options :end-before: // end-settings-library-info LoadBalanced - ~~~~~~~~~~~~ + ```````````` .. include:: /includes/fundamentals/connection-options/loadBalanced.rst @@ -1117,7 +1120,7 @@ Miscellaneous Options :end-before: // end-settings-load-balanced LoggingSettings - ~~~~~~~~~~~~~~~ + ``````````````` The settings used for :ref:`logging. ` The default value is ``null``. @@ -1129,7 +1132,7 @@ Miscellaneous Options :end-before: // end-settings-logging-settings Scheme - ~~~~~~ + `````` .. include:: /includes/fundamentals/connection-options/scheme.rst @@ -1141,7 +1144,7 @@ Miscellaneous Options :end-before: // end-settings-scheme Server - ~~~~~~ + `````` .. include:: /includes/fundamentals/connection-options/server.rst @@ -1153,7 +1156,7 @@ Miscellaneous Options :end-before: // end-settings-server ServerMonitoringMode - ~~~~~~~~~~~~~~~~~~~~ + ```````````````````` .. include:: /includes/fundamentals/connection-options/serverMonitoringMode.rst @@ -1165,7 +1168,7 @@ Miscellaneous Options :end-before: // end-settings-server-monitoring-mode Servers - ~~~~~~~ + ``````` .. include:: /includes/fundamentals/connection-options/servers.rst @@ -1177,7 +1180,7 @@ Miscellaneous Options :end-before: // end-settings-servers SrvMaxHosts - ~~~~~~~~~~~ + ``````````` .. include:: /includes/fundamentals/connection-options/srvMaxHosts.rst @@ -1189,7 +1192,7 @@ Miscellaneous Options :end-before: // end-settings-srv-max-hosts SrvServiceName - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/srvServiceName.rst @@ -1201,7 +1204,7 @@ Miscellaneous Options :end-before: // end-settings-srv-service-name TranslationOptions - ~~~~~~~~~~~~~~~~~~ + `````````````````` Specifies options, such as the {+mdb-server+} version, for translating LINQ queries to the Query API. The default value is ``null``. @@ -1217,7 +1220,7 @@ Miscellaneous Options :tabid: mongo-url-builder ApplicationName - ~~~~~~~~~~~~~~~ + ``````````````` .. include:: /includes/fundamentals/connection-options/applicationName.rst @@ -1229,7 +1232,7 @@ Miscellaneous Options :end-before: // end-builder-application-name DatabaseName - ~~~~~~~~~~~~ + ```````````` The name of the database that the client connects to. @@ -1241,7 +1244,7 @@ Miscellaneous Options :end-before: // end-builder-database-name IPv6 - ~~~~ + ```` .. include:: /includes/fundamentals/connection-options/ipv6.rst @@ -1253,7 +1256,7 @@ Miscellaneous Options :end-before: // end-builder-ipv6 LoadBalanced - ~~~~~~~~~~~~ + ```````````` .. include:: /includes/fundamentals/connection-options/loadBalanced.rst @@ -1265,7 +1268,7 @@ Miscellaneous Options :end-before: // end-builder-load-balanced Scheme - ~~~~~~ + `````` .. include:: /includes/fundamentals/connection-options/scheme.rst @@ -1277,7 +1280,7 @@ Miscellaneous Options :end-before: // end-builder-scheme Server - ~~~~~~ + `````` .. include:: /includes/fundamentals/connection-options/server.rst @@ -1289,7 +1292,7 @@ Miscellaneous Options :end-before: // end-builder-server ServerMonitoringMode - ~~~~~~~~~~~~~~~~~~~~ + ```````````````````` .. include:: /includes/fundamentals/connection-options/serverMonitoringMode.rst @@ -1301,7 +1304,7 @@ Miscellaneous Options :end-before: // end-builder-server-monitoring-mode Servers - ~~~~~~~ + ``````` .. include:: /includes/fundamentals/connection-options/servers.rst @@ -1313,7 +1316,7 @@ Miscellaneous Options :end-before: // end-builder-servers SrvMaxHosts - ~~~~~~~~~~~ + ``````````` .. include:: /includes/fundamentals/connection-options/srvMaxHosts.rst @@ -1325,7 +1328,7 @@ Miscellaneous Options :end-before: // end-builder-srv-max-hosts SrvServiceName - ~~~~~~~~~~~~~~ + `````````````` .. include:: /includes/fundamentals/connection-options/srvServiceName.rst From 86e464454be41a9c04e9d57fbc3c7ad10ceee9a0 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Jun 2025 19:42:34 -0500 Subject: [PATCH 31/32] TOC fix --- source/connect.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect.txt b/source/connect.txt index caec388b..6f15db31 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -24,5 +24,5 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target - Configure a Connection + Specify Connection Options Connection Troubleshooting \ No newline at end of file From ed1a52d431a59043d37c5824f5438a24fbd3762c Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Jun 2025 09:14:04 -0500 Subject: [PATCH 32/32] vale errors --- config/intersphinx.yaml | 2 +- source/atlas-search.txt | 2 +- source/connect/connection-options.txt | 6 +++++- source/connect/connection-options/stable-api.txt | 11 ++--------- source/connect/connection-troubleshooting.txt | 8 ++++---- source/crud/gridfs.txt | 2 +- source/crud/insert.txt | 10 +++------- source/crud/query/query-filter.txt | 4 ++-- source/data-formats/bson.txt | 4 ++-- source/data-formats/custom-types/class-mapping.txt | 12 ++++++------ source/data-formats/custom-types/poco.txt | 7 +++---- source/data-formats/custom-types/serialization.txt | 6 +++--- .../code-examples/connection/ConnectionOptions.cs | 2 +- .../fundamentals/connection-options/loadBalanced.rst | 2 +- source/includes/quick-start/query-output.rst | 2 +- source/indexes.txt | 5 ++--- source/security/authentication/kerberos.txt | 2 +- source/security/tls-ssl.txt | 4 ++-- 18 files changed, 41 insertions(+), 50 deletions(-) diff --git a/config/intersphinx.yaml b/config/intersphinx.yaml index 5cad55e4..3e317721 100644 --- a/config/intersphinx.yaml +++ b/config/intersphinx.yaml @@ -1,4 +1,4 @@ -# Weirdly, giza wants a non-empty list of two or more, so we have to include extraneous/unused one --hence the python +# Weirdly, giza wants a non-empty list of two or more, so we must include extraneous/unused one --hence the python name: python url: https://docs.python.org/2/ path: python2.inv diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 770674ef..c2c946b9 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -122,7 +122,7 @@ Use the ``Compound()`` method to combine two or more operators into a single search. The following example searches the ``guitars`` collection for any documents -that match all of the following criteria: +that match all the following criteria: - The ``rating`` field exists on the document - The ``in_stock`` field is not ``false`` diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index bcf38e3e..0759047c 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -86,7 +86,7 @@ The following code example shows how to perform the preceding steps: You can also create a ``MongoClientSettings`` object from a connection string by calling the ``MongoClientSettings.FromConnectionString()`` method and passing the connection string, as shown in the following example. This is useful if you already have a connection string -but want to modify some settings programmatically, or if you want to specify settings +but want to modify some settings programmatically, or if you must specify settings that aren't available in the connection string. .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -133,6 +133,10 @@ this process: Connection Options ------------------ +The following sections describe the connection options available in the +{+driver-short+} and how to specify them by using a ``MongoClientSettings`` or +``MongoUrlBuilder`` object. + .. _csharp-replica-set-options: Replica Set Options diff --git a/source/connect/connection-options/stable-api.txt b/source/connect/connection-options/stable-api.txt index 5417a318..f41f8d3b 100644 --- a/source/connect/connection-options/stable-api.txt +++ b/source/connect/connection-options/stable-api.txt @@ -12,13 +12,6 @@ :depth: 2 :class: singlecol -.. note:: - - The {+stable-api+} feature requires {+mdb-server+} 5.0 or later. - - You should use the {+stable-api+} feature only if all of the MongoDB - servers you're connecting to support this feature. - Overview -------- @@ -46,10 +39,10 @@ version of the {+stable-api+}. .. tip:: Once you've created a ``MongoClient``, you can't change its {+stable-api+} version. - If you need to run commands using more than one version of the + If you must run commands using more than one version of the {+stable-api+}, instantiate a separate client with that version. - If you need to run commands not covered by the {+stable-api+}, make sure the + If you must run commands not covered by the {+stable-api+}, make sure the "strict" option is disabled. See the section on :ref:`{+stable-api+} Options ` for more information. diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 6c914198..7afa2669 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -168,7 +168,7 @@ You can also set configuration settings by creating a ``MongoClientSettings`` object and passing that to the ``MongoClient`` constructor. You can use the ``Credential`` property to set the login credentials including specifying the authentication database. For more information about using ``MongoClientSettings`` -as well as some examples, see +and to see some examples, see :ref:`Using MongoClientSettings `. You can check if this is the issue by attempting to connect to a MongoDB @@ -249,7 +249,7 @@ The following section describes a method that may help resolve the issue. Check the Number of Connections ------------------------------- -If you need to create more open connections, increase ``MaxConnectionPoolSize``. For more +If you must create more open connections, increase ``MaxConnectionPoolSize``. For more information about checking the number of connections, see :ref:`Check the Number of Connections ` in the Error Sending Message section. @@ -279,7 +279,7 @@ time the driver spends attempting to establish the connection by using the :manual:`Timeout Options ` in the Server manual. -You should ensure the ``connectTimeoutMS`` setting is not lower than +Ensure the ``connectTimeoutMS`` setting is not lower than the highest network latency you have to a member of the set. If one of the secondary members has a latency of 10000 milliseconds, setting the ``connectTimeoutMS`` to 9000 prevents the driver from ever connecting to that @@ -301,7 +301,7 @@ You can set this option on the connection string. The following example sets You can also set configuration settings by creating a ``MongoClientSettings`` object and passing that to the ``MongoClient`` constructor. For more information -about using ``MongoClientSettings`` as well as some examples, see +about using ``MongoClientSettings`` and to see some examples, see :ref:`Using MongoClientSettings `. Check the Number of Connections diff --git a/source/crud/gridfs.txt b/source/crud/gridfs.txt index c5906346..3e12fa98 100644 --- a/source/crud/gridfs.txt +++ b/source/crud/gridfs.txt @@ -690,7 +690,7 @@ code. .. note:: File Revisions The ``Delete()`` and ``DeleteAsync()`` methods support deleting only one file at a time. - If you want to delete each file revision, or files with different upload + To delete each file revision, or files with different upload times that share the same file name, collect the ``_id`` values of each revision. Then, pass each ``_id`` value in separate calls to the ``Delete()`` or ``DeleteAsync()`` method. diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 0530e7df..8f4a16ad 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -248,10 +248,8 @@ Assume you want to insert the following documents: If you attempt to insert these documents with default ``InsertManyOptions``, the driver throws a ``MongoBulkWriteException`` at the third -document because of the repeated ``_id`` value, but the documents before -the error-producing document are still inserted into your collection. - -If you look inside your collection, you should be able to see the following documents: +document because of the repeated ``_id`` value. The operation adds only the first two documents +to the collection: .. code-block:: json :copyable: false @@ -262,9 +260,7 @@ If you look inside your collection, you should be able to see the following docu If you set ``IsOrdered`` to ``false`` in your insert operation, the driver will continue to insert your documents even if some documents produce errors. With this modified insert behavior, the driver throws an exception but inserts all documents -that do not produce errors. - -If you look inside your collection, you should be able to see the following documents: +that do not produce errors: .. code-block:: json :copyable: false diff --git a/source/crud/query/query-filter.txt b/source/crud/query/query-filter.txt index d409d099..fd936a88 100644 --- a/source/crud/query/query-filter.txt +++ b/source/crud/query/query-filter.txt @@ -586,12 +586,12 @@ bitwise operations and the equivalent {+mdb-server+} operators: - {+mdb-server+} Operator * - ``BitsAllClear()`` - - Matches documents where all of the specified bit positions are clear (``0``) in + - Matches documents where all the specified bit positions are clear (``0``) in the specified field. - :manual:`$bitsAllClear ` * - ``BitsAllSet()`` - - Matches documents where all of the specified bit positions are set (``1``) in + - Matches documents where all the specified bit positions are set (``1``) in the specified field. - :manual:`$bitsAllSet ` diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index e04523f2..205f9110 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -95,8 +95,8 @@ write to a file, perform the following steps: #. For each BSON document and subdocument you want to create, call ``WriteStartDocument()``. #. Within each BSON document and subdocument, call ``WriteName()`` to set the field - name and the appropriate ``Write*`` method to set its value. Each data type has a - dedicated ``Write*`` method that you should use. + name and the appropriate ``Write*`` method to set its value. Use the + dedicated ``Write*`` method that corresponds to each data type. #. To start and end arrays, use ``WriteStartArray()`` and ``WriteEndArray()``. #. At the end of each document and subdocument, call ``WriteEndDocument()``. diff --git a/source/data-formats/custom-types/class-mapping.txt b/source/data-formats/custom-types/class-mapping.txt index db80899a..059051bd 100644 --- a/source/data-formats/custom-types/class-mapping.txt +++ b/source/data-formats/custom-types/class-mapping.txt @@ -21,8 +21,8 @@ Overview -------- In this guide, you can learn how to customize the way the {+driver-long+} -maps BSON documents to and from {+language+} classes. You should read this page -to learn more about the default class mapping behavior, or if you need to +maps BSON documents to and from {+language+} classes. Read this page +to learn more about the default class mapping behavior, or if you must customize the way the driver serializes or deserializes your data. Automatic Class Mapping @@ -35,7 +35,7 @@ the name of the field in the document to the name of the property in the class. .. important:: - The type of the property in your class should match the type of the field in + Match the type of the property in your class to the type of the field in the document. The {+driver-short+} instantiates a serializer based on the type of the property in your class. If the types don't match when the driver attempts to deserialize the data, the serializer throws an exception. @@ -72,7 +72,7 @@ class: .. important:: You must register a class map *before* it's needed in your code. We recommend - registering class maps prior to initializing a connection with MongoDB. + registering class maps before initializing a connection with MongoDB. You can also manually map a subset of class properties, while still allowing the driver to automatically map the remaining properties. To do this, @@ -241,11 +241,11 @@ You can also support extra elements when initializing a class map as follows: Dynamically Serialize Properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use a method to determine whether or not to serialize a property. For +You can use a method to determine whether to serialize a property. For the driver to automatically use the method when serializing, you must prefix the method name with ``ShouldSerialize`` followed by the name of the property that the method applies to. When the driver sees a method with this naming -convention, it uses that method to determine whether or not to serialize +convention, it uses that method to determine whether to serialize properties that have the provided property name. The following example creates a method that only serializes the ``Age`` property diff --git a/source/data-formats/custom-types/poco.txt b/source/data-formats/custom-types/poco.txt index 196249ad..4afda549 100644 --- a/source/data-formats/custom-types/poco.txt +++ b/source/data-formats/custom-types/poco.txt @@ -27,8 +27,8 @@ features from any framework-specific base classes or interfaces. We recommend using POCOs in your {+language+} code to adhere to idiomatic driver usage and achieve the best performance. -You should read this guide if you want to learn more about how to use -POCOs with the {+driver-short+} or if you need to adjust the driver's default +Read this guide if you want to learn more about how to use +POCOs with the {+driver-short+} or if you must adjust the driver's default field mapping behavior. Create a POCO @@ -84,8 +84,7 @@ Custom Serialization If the default field mapping behavior does not meet your needs, you can specify custom behavior using serialization-related attributes. These attributes change the way that the driver serializes each property of -your POCO. This section describes some of the common -serialization-related attributes. +your POCO. This section describes some common serialization-related attributes. Serialize Read-Only Properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/data-formats/custom-types/serialization.txt b/source/data-formats/custom-types/serialization.txt index af352a0b..5cd74713 100644 --- a/source/data-formats/custom-types/serialization.txt +++ b/source/data-formats/custom-types/serialization.txt @@ -53,8 +53,8 @@ you can pass in a delegate of type ``Func``. This delegate accepts an object type and returns a boolean value indicating whether the type is safe for serialization. -In most cases, you should pass in the ``ObjectSerializer.DefaultAllowedTypes()`` -delegate. This method returns true for a number of well-known +In most cases, pass in the ``ObjectSerializer.DefaultAllowedTypes()`` +delegate. This method returns true for several well-known framework types that we have deemed safe. To serialize custom types, create a boolean expression that evaluates to ``true`` for the types you want to include. Then, add this expression to the end of the @@ -81,7 +81,7 @@ as shown in the following example: || type.FullName.StartsWith("<>f__AnonymousType")); BsonSerializer.RegisterSerializer(objectSerializer); -You should create and register your ``ObjectSerializer`` at the start of your program, +Create and register your ``ObjectSerializer`` at the start of your program, before doing anything else. Serializer Registry diff --git a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs index def0e448..0097a059 100644 --- a/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs +++ b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -15,7 +15,7 @@ public class ConnectionOptions public void ConnectionUriExample() { // start-connection-uri - const string connectionUri = "mongodb+srv:/localhost:27017/?connectTimeoutMS=60000&tls=true"; + const string uri = "mongodb+srv:/localhost:27017/?connectTimeoutMS=60000&tls=true"; // end-connection-uri } diff --git a/source/includes/fundamentals/connection-options/loadBalanced.rst b/source/includes/fundamentals/connection-options/loadBalanced.rst index d50cd12a..cdb40261 100644 --- a/source/includes/fundamentals/connection-options/loadBalanced.rst +++ b/source/includes/fundamentals/connection-options/loadBalanced.rst @@ -1,5 +1,5 @@ Specifies whether the driver is connecting to a load balancer. You can set this -property to ``true`` only if all of the following conditions are met: +property to ``true`` only if all the following conditions are met: - You specify just one host name - You're not connecting to a replica set diff --git a/source/includes/quick-start/query-output.rst b/source/includes/quick-start/query-output.rst index 971b7e10..1f51cc67 100644 --- a/source/includes/quick-start/query-output.rst +++ b/source/includes/quick-start/query-output.rst @@ -1,4 +1,4 @@ -When you run ``Program.cs``, it should output the details of the following movie from +When you run ``Program.cs``, it outputs the details of the following movie from the sample dataset: .. code-block:: json diff --git a/source/indexes.txt b/source/indexes.txt index dbc2f98c..c57fe006 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -185,8 +185,7 @@ Clustered Indexes To create a clustered index, specify the clustered index option with the ``_id`` field as the key and the ``Unique`` property as ``true`` when you create your collection. A collection can only contain a single clustered -index. If you want to create a clustered index, then it must be specified when you create -a collection. +index. To create a clustered index, specify it when you create a collection. The following example creates a clustered index on the ``_id`` field while creating a new ``sample_mflix.reviews`` collection: @@ -301,7 +300,7 @@ The following query uses the text index created in the preceding code snippet: Multiple Fields +++++++++++++++ -A collection can only contain one text index. If you want to create a +A collection can only contain one text index. To create a text index for multiple text fields, you must create a compound index. A text search runs on all the text fields within the compound index. diff --git a/source/security/authentication/kerberos.txt b/source/security/authentication/kerberos.txt index e45af57a..5d166e50 100644 --- a/source/security/authentication/kerberos.txt +++ b/source/security/authentication/kerberos.txt @@ -76,7 +76,7 @@ see the corresponding syntax: - On Windows, the process owner running the application is the same as the user needing authentication. - - On Linux, the user has initialized their keytab via ``kinit username@REALM.COM``. + - On Linux, the user has initialized their keytab by using ``kinit username@REALM.COM``. Additional Properties ~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/security/tls-ssl.txt b/source/security/tls-ssl.txt index 9cda5e47..8fa48dd6 100644 --- a/source/security/tls-ssl.txt +++ b/source/security/tls-ssl.txt @@ -151,7 +151,7 @@ You can allow insecure TLS in two different ways: using a property on a Check Certificate Revocation ---------------------------- -When an X.509 certificate should no longer be trusted--for example, if its private key +When an X.509 certificate is no longer trusted--for example, if its private key has been compromised--the certificate authority will revoke the certificate. By default, the {+driver-short+} doesn't check whether a server's certificate has been @@ -205,7 +205,7 @@ Windows, macOS, and Linux: - :wikipedia:`Online Certificate Status Protocol (OCSP) `, a common mechanism for checking revocation - :wikipedia:`OCSP stapling `, a mechanism in which the server - includes a time-stamped OCSP response to the client along with the certificate + includes a time-stamped OCSP response to the client with the certificate - :wikipedia:`Certificate revocation lists (CRLs), `, an alternative to OCSP