connection-options.txt

.. _csharp-connection-options:

==================
Connection Options
==================

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: connection string, URI, server, Atlas, settings, configure
   :description: Explore MongoDB connection and authentication options in the .NET/C# Driver using connection URI or `MongoClientSettings` for flexible configuration.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

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.

.. _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 ``<name>=<value>`` 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
   :language: csharp
   :dedent:
   :start-after: // start local connection config
   :end-before: // end local connection config

.. _csharp-mongo-client-settings:

-----------------------------
Using ``MongoClientSettings``
-----------------------------

You can use a ``MongoClientSettings`` object to configure connection settings in code
rather than in a connection URI. Configuring the connection this way makes it easier to
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:

.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettingsConfig.cs
   :language: csharp
   :dedent:
   :start-after: // start mongo client settings config
   :end-before: // end mongo client settings config

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.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 <csharp-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. </reference/connection-string/#std-label-connections-dns-seedlist>`
       | You must use the :manual:`standard connection URI format </reference/connection-string/#standard-connection-string-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. <csharp-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 <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 <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</reference/connection-string/>` 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</reference/stable-api>` 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``

   * - **SrvServiceName**
     - | The service name of the `SRV resource records <https://www.rfc-editor.org/rfc/rfc2782>`__
       | that the driver retrieves to construct your seedlist. This
       | property overrides the default service name for SRV lookup in
       | discovery and polling.
       |
       | 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**: {+string-data-type+}
       | **Default**: ``"mongodb"``
       | **Connection URI Example**: ``srvServiceName="customname"``

   * - **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 <wc-j>` 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+}