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 2d4198e0..0759047c 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -1,8 +1,8 @@ .. _csharp-connection-options: -================== -Connection Options -================== +========================== +Specify Connection Options +========================== .. facet:: :name: genre @@ -18,7 +18,7 @@ Connection Options :class: singlecol .. toctree:: - :caption: Specify Connection Options + :caption: Specify Connection Options Compress Network Traffic Customize Server Selection @@ -27,441 +27,1344 @@ 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. +Overview +-------- + +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 +--------------------------------- + +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, 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:`Connection String Options ` 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 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 + :dedent: + :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 settings programmatically, or if you must specify settings +that aren't available in the connection string. + +.. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :dedent: + :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 want to specify settings that aren't available in the ``MongoUrl`` class. -.. 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-from-url + :end-before: // end-from-url + +.. _csharp-mongo-url-builder: + +Using MongoUrlBuilder +~~~~~~~~~~~~~~~~~~~~~ + +You can use a ``MongoUrlBuilder`` object to create and configure connection settings on +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 +``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/ConnectionOptions.cs + :language: csharp + :dedent: 8 + :start-after: // start-mongo-url-builder + :end-before: // end-mongo-url-builder 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. - -.. 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. - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - **MongoClientSettings** Property - - Description - - * - **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`` - - * - **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`` - - * - **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+} - - * - **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+} - - * - **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`` - - * - **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`` - - * - **Credential** - - | 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. - | - | **Data Type**: `MongoCredential <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCredential.html>`__ - | **Default**: ``null`` - | **Connection URI Example**: - - .. code-block:: none - :copyable: false - - mongodb://user1:password1&authMechanism=GSSAPI - &authMechanismProperties=SERVICE_NAME:other,REALM:otherrealm - &authSource=$external - - * - **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** - - | 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`` - - * - **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`` - - * - **IPv6** - - | Specifies whether the host address is in IPv6 format. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``false`` - | **Connection URI Example**: ``ipv6=true`` - - * - **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+} - - * - **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`` - | **Connection URI Example**: ``loadBalanced=true`` - - * - **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`` - - * - **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+} - - * - **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** - - | 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`` - - * - **MaxConnectionLifeTime** - - | The length of time a connection can be pooled before expiring. - | - | **Data Type**: ``TimeSpan`` - | **Default**: 30 minutes - | **Connection URI Example**: ``maxLifetimeMS=50000`` - - * - **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** - - | 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`` - | **Connection URI Example**: ``minPoolSize=1`` - - * - **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`` - - * - **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. - | - | **Data Type**: ``UTF8Encoding`` - | **Default**: Strict encoding - | **Connection URI Example**: {+not-available+} - - * - **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``. - - * - **ReplicaSetName** - - | The name of the replica set to connect to. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``null`` - | **Connection URI Example**: ``replicaSet=yourReplicaSet`` - - * - **RetryReads** - - | Enables retryable reads. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``true`` - | **Connection URI Example**: ``retryReads=false`` - - * - **RetryWrites** - - | Enables retryable writes. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``true`` - | **Connection URI Example**: ``retryWrites=false`` - - * - **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://`` - - * - **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`` - - * - **ServerApi** - - | 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+} - - * - **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`` - - * - **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`` - - * - **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** - - | 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** - - | 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** - - | 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** - - | 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+} - - * - **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** - - | 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** - - | 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** - - | 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+} +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 +~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + DirectConnection + ```````````````` + + .. include:: /includes/fundamentals/connection-options/directConnection.rst + + .. 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 + + 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 + + .. tab:: MongoUrlBuilder + :tabid: mongo-url-builder + + DirectConnection + ```````````````` + + .. include:: /includes/fundamentals/connection-options/directConnection.rst + + .. 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 + + 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 +~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + AllowInsecureTls + ```````````````` + + .. include:: /includes/fundamentals/connection-options/allowInsecureTls.rst + + .. 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. + + .. 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 + + UseTls + `````` + + .. include:: /includes/fundamentals/connection-options/useTls.rst + + .. 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 + + .. 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 + + 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 + `````` + + .. include:: /includes/fundamentals/connection-options/useTls.rst + + .. 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 +~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + ConnectTimeout + `````````````` + + .. include:: /includes/fundamentals/connection-options/connectTimeout.rst + + .. 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 + + .. 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 + + ConnectTimeout + `````````````` + + .. include:: /includes/fundamentals/connection-options/connectTimeout.rst + + .. 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 + + .. 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 +~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + Compressors + ``````````` + + .. include:: /includes/fundamentals/connection-options/compressors.rst + + .. 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 + + Compressors + ``````````` + + .. include:: /includes/fundamentals/connection-options/compressors.rst + + .. 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 +~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + MaxConnecting + ````````````` + + .. include:: /includes/fundamentals/connection-options/maxConnecting.rst + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + MaxConnecting + ````````````` + + .. include:: /includes/fundamentals/connection-options/maxConnecting.rst + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + .. 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 +~~~~~~~~~~~~~~~~~~~~~ + +.. 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 :manual:`Write Concern ` in the + {+mdb-server+} manual for more information. + + .. 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 + + .. 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 +~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :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 + {+mdb-server+} manual. + + .. 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 + ```````````````` + + The client's read concern level. The default value is ``ReadConcern.Local``. + For more information, see :ref:`read concern `. + + .. 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 +~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + ReadPreference + `````````````` + + .. include:: /includes/fundamentals/connection-options/readPreference.rst + + .. 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 + + .. 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 +~~~~~~~~~~~~~~~~~~~~~~ + +.. 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``. + + 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. + + .. 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 + + 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. + + .. 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 + ````````````````````````````````` + + Configuration settings for the authentication mechanism specified in the + ``AuthenticationMechanism`` property. + + .. 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. + + .. 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 + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + HeartbeatInterval + ````````````````` + + .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + HeartbeatInterval + ````````````````` + + .. include:: /includes/fundamentals/connection-options/heartbeatInterval.rst + + .. 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 + + .. 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 + + .. 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 + + .. 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 + +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 +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 + +.. note:: MongoClientSettings Only + + The ``ReadEncoding`` and ``WriteEncoding`` properties are available only in the + ``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 +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 + +.. note:: MongoClientSettings Only + + The ``ServerApi`` property is available only in the ``MongoClientSettings`` class. + +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 +~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongo-client-settings + + ApplicationName + ``````````````` + + .. include:: /includes/fundamentals/connection-options/applicationName.rst + + .. 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``. To + learn more about client-side encryption, see + :ref:`In-Use Encryption `. + + .. 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 + ``````````````````` + + Low-level configuration options for sockets, TLS, cluster, and others. The default + value is ``null``. + + .. 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 + + .. 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 + ```````` + + 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 + :copyable: true + :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() <{+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>`__ + 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 + ```````````` + + .. include:: /includes/fundamentals/connection-options/loadBalanced.rst + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: 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``. + + .. 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 + + Scheme + `````` + + .. include:: /includes/fundamentals/connection-options/scheme.rst + + .. 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 + + .. literalinclude:: /includes/fundamentals/code-examples/connection/ConnectionOptions.cs + :language: csharp + :copyable: true + :dedent: 8 + :start-after: // start-settings-server + :end-before: // end-settings-server + + ServerMonitoringMode + ```````````````````` + + .. include:: /includes/fundamentals/connection-options/serverMonitoringMode.rst + + .. 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 + + .. 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 + + .. 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 + + 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 + `````````````````` + + Specifies options, such as the {+mdb-server+} version, for translating LINQ + queries to the Query API. The default value is ``null``. + + .. 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 + + .. 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 + + 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 + ```` + + .. include:: /includes/fundamentals/connection-options/ipv6.rst + + .. 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 + + .. 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 + + Scheme + `````` + + .. include:: /includes/fundamentals/connection-options/scheme.rst + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + .. 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 + + 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/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.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.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>`__ +- `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>`__ +- `ServerApi <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ServerApi.html>`__ +- `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ \ No newline at end of file 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/connect/mongoclient.txt b/source/connect/mongoclient.txt index b2bdff0f..e4ef8697 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -97,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``: +You can configure your connection in the following ways: -.. code-block:: csharp - - 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 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 new file mode 100644 index 00000000..0097a059 --- /dev/null +++ b/source/includes/fundamentals/code-examples/connection/ConnectionOptions.cs @@ -0,0 +1,855 @@ +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 ConnectionUriExample() + { + // start-connection-uri + const string uri = "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 + 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 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 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 + 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 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 + 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/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/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 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/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/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/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..cdb40261 --- /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 all 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 + +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/maxConnecting.rst b/source/includes/fundamentals/connection-options/maxConnecting.rst new file mode 100644 index 00000000..b6ac4280 --- /dev/null +++ b/source/includes/fundamentals/connection-options/maxConnecting.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..eb3d4a3e --- /dev/null +++ b/source/includes/fundamentals/connection-options/minConnectionPoolSize.rst @@ -0,0 +1,3 @@ +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 diff --git a/source/includes/fundamentals/connection-options/readPreference.rst b/source/includes/fundamentals/connection-options/readPreference.rst new file mode 100644 index 00000000..905d5e66 --- /dev/null +++ b/source/includes/fundamentals/connection-options/readPreference.rst @@ -0,0 +1,6 @@ +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 :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/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 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..894343ed --- /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:`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 +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/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/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 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 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 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