diff --git a/.github/workflows/add-netlify-links.yml b/.github/workflows/add-netlify-links.yml index cb0770c8..69377f9f 100644 --- a/.github/workflows/add-netlify-links.yml +++ b/.github/workflows/add-netlify-links.yml @@ -26,7 +26,7 @@ jobs: CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }} run: | new_links="" - base_link='https://deploy-preview-${{ github.event.number }}--mongodb-docs-csharp.netlify.app' + base_link='https://deploy-preview-${{ github.event.number }}--docs-csharp.netlify.app' files=$(echo "$CHANGED_FILES" | tr "," "\n") for file in $files; do echo "processing ${file}" @@ -55,4 +55,4 @@ jobs: appendContentOnMatchOnly: true regexFlags: is content: "\n${{ steps.build_page_links.outputs.staging_links }}\n" - token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/source/faq.txt b/source/faq.txt deleted file mode 100644 index 3cf1dae9..00000000 --- a/source/faq.txt +++ /dev/null @@ -1,324 +0,0 @@ -.. _csharp-faq: - -=== -FAQ -=== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: .NET, questions, errors, problems - -This page contains frequently asked questions and their corresponding answers. - -.. tip:: - - If you can't find an answer to your problem on this page, - see the :ref:`csharp-issues-help` page for next steps and more - resources. - -Why Am I Getting Errors While Connecting to MongoDB? ----------------------------------------------------- - -If you have trouble connecting to a MongoDB deployment, see -the :ref:`Connection Troubleshooting Guide ` -for possible solutions. - -.. _csharp-faq-connection-pool: - -How Does Connection Pooling Work in the {+driver-short+}? ---------------------------------------------------------- - -Every ``MongoClient`` instance has a built-in connection pool for each server -in your MongoDB topology. Connection pools open sockets on demand to -support concurrent MongoDB operations in your multi-threaded application. - -The maximum size of each connection pool is set by the ``MaxConnectionPoolSize`` option, which -defaults to ``100``. If the number of in-use connections to a server reaches -the value of ``MaxConnectionPoolSize``, the next request to that server will wait -until a connection becomes available. The following diagram illustrates a high-level view -of how the ``MongoClient`` manages a connection pool: - -.. figure:: /includes/figures/CMAP_diagram.svg - :alt: CMAP diagram - -In addition to the sockets needed to support your application's threads, -each ``MongoClient`` instance opens two additional sockets per server -in your MongoDB topology for monitoring the server's state. -For example, a client connected to a three-node replica set opens six -monitoring sockets. If the application uses the default setting for -``MaxConnectionPoolSize`` and only queries the primary (default) node, then -there can be at most ``106`` total connections in use. If the -application uses a :ref:`read preference ` to query the -secondary nodes, those connection pools grow and there can be -``306`` total connections. - -To support high numbers of concurrent MongoDB threads -within one process, you can increase ``MaxConnectionPoolSize``. - -The driver has a wait queue that limits the number of threads that can -wait for a connection. The size of the wait queue is determined by the -``WaitQueueMultiple`` option, which defaults to ``5``. To calculate the -maximum wait queue size, the driver multiplies ``WaitQueueMultiple`` by -``MaxConnectionPoolSize``. If you use the default value for each option, -the wait queue size will be ``500``. You can also set the wait queue -size by specifying the ``WaitQueueSize`` option, which overrides the -other settings. However, we do not recommend changing the wait queue -size from the default. - -Connection pools are rate-limited. The ``MaxConnecting`` setting -determines the number of connections that the pool can create in -parallel at any time. For example, if the value of ``MaxConnecting`` is -``2``, the third thread that attempts to concurrently check out a -connection succeeds only in one of the following cases: - -- One of the first two threads finishes creating a connection. -- An existing connection is checked back into the pool. -- The driver's ability to reuse existing connections improves due to - rate-limits on connection creation. - -You can set the minimum number of concurrent connections to -each server by using the ``MinConnectionPoolSize`` option, which -defaults to ``0``. The connection pool will be initialized with this -number of sockets. If errors cause any sockets to close and the -total number of sockets (both in-use and idle) drops below the minimum, -the driver opens more sockets until the number reaches the minimum. - -You can set the maximum number of milliseconds that a connection can -remain idle in the pool by using the ``MaxConnectionIdleTime`` option. -Once a connection is idle for ``MaxConnectionIdleTime``, the driver -removes it. This option defaults to 10 minutes. If the pool size falls -below ``MinConnectionPoolSize``, the driver removes *and* replaces the -idle connection. - -``MongoClient`` also has the ``MaxConnectionLifeTime`` option, which -specifies the length of time, 30 minutes by default, that a connection -can be pooled before expiring. - -The following default configuration for a ``MongoClient`` works for most -applications: - -.. code-block:: csharp - - var client = new MongoClient(""); - -Create a client once for each process, and reuse it for all -operations. It is a common mistake to create a new client for each -request, which is very inefficient. - -There is no supported way to terminate a ``MongoClient`` in the driver. - -Why Does the Driver Throw a Timeout During Server Selection? ------------------------------------------------------------- - -Each driver operation requires that you choose a healthy server -satisfying the :manual:`server selection criteria -`. If you do not select an appropriate -server within the `server selection timeout <{+new-api-root+}/MongoDB.Driver.Legacy/MongoDB.Driver.MongoServerSettings.ServerSelectionTimeout.html>`__, the driver throws a -server selection timeout exception. The exception looks similar to the -following: - -.. code-block:: none - - A timeout occurred after 30000ms selecting a server using CompositeServerSelector{ Selectors = MongoDB.Driver.MongoClient+AreSessionsSupportedServerSelector, LatencyLimitingServerSelector{ AllowedLatencyRange = 00:00:00.0150000 }, OperationsCountServerSelector }. - Client view of cluster state is - { - ClusterId : "1", - Type : "Unknown", - State : "Disconnected", - Servers : - [{ - ServerId: "{ ClusterId : 1, EndPoint : "Unspecified/localhost:27017" }", - EndPoint: "Unspecified/localhost:27017", - ReasonChanged: "Heartbeat", - State: "Disconnected", - ServerVersion: , - TopologyVersion: , - Type: "Unknown", - HeartbeatException: "" - }] - }. - -The error message consists of multiple parts: - -1. The server selection timeout (30000 ms). -#. The server selectors considered (``CompositeServerSelector`` - containing ``AreSessionsSupportedServerSelector``, - ``LatencyLimitingServerSelector``, and - ``OperationsCountServerSelector``). -#. The driver’s current view of the cluster topology. The list of - servers that the driver is aware of is a key part of this view. Each - server description contains an exhaustive description of its current - state including information about an endpoint, a server version, a - server type, and its current health state. If the server encounters issues in - reporting its health, ``HeartbeatException`` contains the exception from the - last failed heartbeat. Analyzing the ``HeartbeatException`` on each - cluster node can assist in diagnosing most server selection issues. - The following heartbeat exceptions are common: - - * ``No connection could be made because the target machine actively - refused it``: The driver cannot see this cluster node. This can be - because the cluster node has crashed, a firewall is preventing - network traffic from reaching the cluster node or port, or some other - network error is preventing traffic from being successfully routed to - the cluster node. - * ``Attempted to read past the end of the stream``: This error - happens when the driver cannot connect to the cluster nodes due to a - network error, misconfigured firewall, or other network issue. To - address this exception, ensure that all cluster nodes are reachable. - This error commonly occurs when the client machine’s IP address is - not configured in the Atlas IPs Access List, which can be found under - the :guilabel:`Network Access` tab for your Atlas Project. - * ``The remote certificate is invalid according to the validation - procedure``: This error typically indicates a TLS/SSL-related problem - such as an expired/invalid certificate or an untrusted root CA. You - can use tools like ``openssl s_client`` to debug TLS/SSL-related - certificate problems. - -.. _csharp-faq-linq-vs-builder: - -Should I Use LINQ or Builder Classes When Querying for Documents? ------------------------------------------------------------------ - -If you're used to programming in {+language+}, consider using LINQ because of its similar feel -to programming in native {+language+}. If you have prior experience with other MongoDB drivers, -consider using Builder classes because of their consistency with other drivers. - -We encourage experimenting with both approaches to determine the most suitable mechanism -for your purposes. - -.. _csharp-faq-unsupported-expressions: - -Why are Certain LINQ or Builder Expressions Unsupported? --------------------------------------------------------- - -Each LINQ or Builder expression must be available in the Query API. This is not -always possible for the following reasons: - -1. You are attempting to use a {+lang-framework+} feature that does not have an - equivalent MongoDB representation. For example, {+lang-framework+} and MongoDB have - different semantics around collations. -#. The driver does not support a particular transformation from LINQ or - Builder expression into MQL (MongoDB Query Language). This may happen because the - provided query has no MQL translation or because a feature has not been - implemented yet in the driver. - -If you receive an ``Unsupported filter ...`` or ``Expression not -supported ...`` exception message, try the following -steps: - -1. Use the `{+analyzer+} - `__ to analyze your - expressions. -#. Try to simplify your query where possible. -#. Provide a query as a ``BsonDocument`` or JSON string. All driver - definition classes such as ``FilterDefinition``, - ``ProjectionDefinition``, and ``PipelineDefinition`` support implicit - conversion from ``BsonDocument`` or JSON string. For example, the - following filters are equivalent when used in a query or - aggregation: - -.. code-block:: csharp - - FilterDefinition typedFilter = Builders.Filter.Eq(e => e.A, 1); - FilterDefinition bsonFilter = new BsonDocument {{ "a", 1 }}; - FilterDefinition jsonFilter = "{ a : 1 }"; - -.. note:: - - If you use ``BsonDocument`` or JSON string, then `BsonClassMap - `__, - BSON serialization attributes, and serialization conventions are not - taken into account in the Query API. Field names must match the - names and casing as stored by the server. For example, when referencing - the ``_id`` field, you must refer to it using ``_id`` in - ``BsonDocument`` or JSON string definitions. Similarly, if a document - has a field ``FirstName`` annotated with ``[BsonElement("first_name")]``, you - must refer to it as ``first_name`` in ``BsonDocument`` or JSON string - definitions. - -You can combine the raw and typed forms in the same query, as the -following code demonstrates: - -.. code-block:: csharp - - FilterDefinition filter = Builders.Filter - .And(Builders.Filter - .Eq(e => e.A, 1), BsonDocument - .Parse("{ b : 2 }")); - -.. _csharp-faq-object-serializer: - -What Object Types Can Be Serialized? ------------------------------------- - -The ``ObjectSerializer`` allows serialization and deserialization only of types -that are considered safe. When you construct an ``ObjectSerializer``, -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 -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 -delegate you pass to the ``ObjectSerializer`` constructor. - -In the following example, -the ``ObjectSerializer`` will serialize and deserialize any type that is allowed by -``ObjectSerializer.DefaultAllowedTypes()`` or whose full name begins with -``"MyNamespace"``: - -.. code-block:: csharp - - var objectSerializer = new ObjectSerializer(type => ObjectSerializer.DefaultAllowedTypes(type) - || type.FullName.StartsWith("MyNamespace")); - BsonSerializer.RegisterSerializer(objectSerializer); - -To allow anonymous types to be serialized, add the boolean expression -``type.FullName.StartsWith("<>f__AnonymousType"))`` to your delegate, -as shown in the following example: - -.. code-block:: csharp - - var objectSerializer = new ObjectSerializer(type => ObjectSerializer.DefaultAllowedTypes(type) - || type.FullName.StartsWith("<>f__AnonymousType")); - BsonSerializer.RegisterSerializer(objectSerializer); - -You should create and register your ``ObjectSerializer`` at the start of your program, -before doing anything else. - -What is the Difference Between the {+driver-short+} and the {+ef-provider-long+}? -------------------------------------------------------------------------------------------------- - -The {+driver-short+} is a library that exposes MongoDB functionality -directly and includes a LINQ provider with projections, group -operations, and flexible mapping. The driver includes features such as the -following: - -- Transactions -- Bulk operations -- LINQ queries -- Operations that directly modify the database -- Aggregation operations -- Custom mapping - -The `{+ef-provider-short+} `__ -allows you to use Microsoft's Entity Framework Core with -MongoDB in your {+lang-framework+} applications. The {+ef-provider-short+} supports -change tracking, entity-based LINQ operations, and modeling familiar to -Entity Framework Core users. The provider includes features such as the following: - -- Intelligent object tracking -- Entity-based LINQ operations -- Entity Framework modeling and mapping with the fluent API -- Automatic database updates through change tracking \ No newline at end of file diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 1876e831..4ccf6189 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -20,6 +20,8 @@ Operations with Builders Overview -------- +.. include:: /includes/linq-vs-builders.rst + In this guide, you can learn about the helper classes, or **builders**, that the {+driver-short+} provides to create types used in your operations. Using builders helps you identify errors at compile time and avoid them @@ -488,6 +490,11 @@ The results of the preceding example contain the following documents: To learn more about Atlas Vector Search, see :atlas:`Atlas Vector Search Overview ` in the Atlas manual. +Troubleshooting +--------------- + +.. include:: /includes/troubleshooting/unsupported-filter-expression.rst + Additional Information ---------------------- diff --git a/source/fundamentals/connection/connection-pools.txt b/source/fundamentals/connection/connection-pools.txt new file mode 100644 index 00000000..db9a3a7e --- /dev/null +++ b/source/fundamentals/connection/connection-pools.txt @@ -0,0 +1,86 @@ +.. TODO: Connection Pools page + +.. _csharp-faq-connection-pool: +.. _csharp-connection-pools: + +How Does Connection Pooling Work in the {+driver-short+}? +--------------------------------------------------------- + +Every ``MongoClient`` instance has a built-in connection pool for each server +in your MongoDB topology. Connection pools open sockets on demand to +support concurrent MongoDB operations in your multi-threaded application. + +The maximum size of each connection pool is set by the ``MaxConnectionPoolSize`` option, which +defaults to ``100``. If the number of in-use connections to a server reaches +the value of ``MaxConnectionPoolSize``, the next request to that server will wait +until a connection becomes available. The following diagram illustrates a high-level view +of how the ``MongoClient`` manages a connection pool: + +.. figure:: /includes/figures/CMAP_diagram.svg + :alt: CMAP diagram + +In addition to the sockets needed to support your application's threads, +each ``MongoClient`` instance opens two additional sockets per server +in your MongoDB topology for monitoring the server's state. +For example, a client connected to a three-node replica set opens six +monitoring sockets. If the application uses the default setting for +``MaxConnectionPoolSize`` and only queries the primary (default) node, then +there can be at most ``106`` total connections in use. If the +application uses a :ref:`read preference ` to query the +secondary nodes, those connection pools grow and there can be +``306`` total connections. + +To support high numbers of concurrent MongoDB threads +within one process, you can increase ``MaxConnectionPoolSize``. + +The driver has a wait queue that limits the number of threads that can +wait for a connection. The size of the wait queue is determined by the +``WaitQueueMultiple`` option, which defaults to ``5``. To calculate the +maximum wait queue size, the driver multiplies ``WaitQueueMultiple`` by +``MaxConnectionPoolSize``. If you use the default value for each option, +the wait queue size will be ``500``. You can also set the wait queue +size by specifying the ``WaitQueueSize`` option, which overrides the +other settings. However, we do not recommend changing the wait queue +size from the default. + +Connection pools are rate-limited. The ``MaxConnecting`` setting +determines the number of connections that the pool can create in +parallel at any time. For example, if the value of ``MaxConnecting`` is +``2``, the third thread that attempts to concurrently check out a +connection succeeds only in one of the following cases: + +- One of the first two threads finishes creating a connection. +- An existing connection is checked back into the pool. +- The driver's ability to reuse existing connections improves due to + rate-limits on connection creation. + +You can set the minimum number of concurrent connections to +each server by using the ``MinConnectionPoolSize`` option, which +defaults to ``0``. The connection pool will be initialized with this +number of sockets. If errors cause any sockets to close and the +total number of sockets (both in-use and idle) drops below the minimum, +the driver opens more sockets until the number reaches the minimum. + +You can set the maximum number of milliseconds that a connection can +remain idle in the pool by using the ``MaxConnectionIdleTime`` option. +Once a connection is idle for ``MaxConnectionIdleTime``, the driver +removes it. This option defaults to 10 minutes. If the pool size falls +below ``MinConnectionPoolSize``, the driver removes *and* replaces the +idle connection. + +``MongoClient`` also has the ``MaxConnectionLifeTime`` option, which +specifies the length of time, 30 minutes by default, that a connection +can be pooled before expiring. + +The following default configuration for a ``MongoClient`` works for most +applications: + +.. code-block:: csharp + + var client = new MongoClient(""); + +Create a client once for each process, and reuse it for all +operations. It is a common mistake to create a new client for each +request, which is very inefficient. + +There is no supported way to terminate a ``MongoClient`` in the driver. \ No newline at end of file diff --git a/source/fundamentals/connection/server-selection.txt b/source/fundamentals/connection/server-selection.txt new file mode 100644 index 00000000..57772394 --- /dev/null +++ b/source/fundamentals/connection/server-selection.txt @@ -0,0 +1,68 @@ +.. TODO: Server Selection page + +Why Does the Driver Throw a Timeout During Server Selection? +------------------------------------------------------------ + +Each driver operation requires that you choose a healthy server +satisfying the :manual:`server selection criteria +`. If you do not select an appropriate +server within the `server selection timeout <{+new-api-root+}/MongoDB.Driver.Legacy/MongoDB.Driver.MongoServerSettings.ServerSelectionTimeout.html>`__, the driver throws a +server selection timeout exception. The exception looks similar to the +following: + +.. code-block:: none + + A timeout occurred after 30000ms selecting a server using CompositeServerSelector{ Selectors = MongoDB.Driver.MongoClient+AreSessionsSupportedServerSelector, LatencyLimitingServerSelector{ AllowedLatencyRange = 00:00:00.0150000 }, OperationsCountServerSelector }. + Client view of cluster state is + { + ClusterId : "1", + Type : "Unknown", + State : "Disconnected", + Servers : + [{ + ServerId: "{ ClusterId : 1, EndPoint : "Unspecified/localhost:27017" }", + EndPoint: "Unspecified/localhost:27017", + ReasonChanged: "Heartbeat", + State: "Disconnected", + ServerVersion: , + TopologyVersion: , + Type: "Unknown", + HeartbeatException: "" + }] + }. + +The error message consists of multiple parts: + +1. The server selection timeout (30000 ms). +#. The server selectors considered (``CompositeServerSelector`` + containing ``AreSessionsSupportedServerSelector``, + ``LatencyLimitingServerSelector``, and + ``OperationsCountServerSelector``). +#. The driver’s current view of the cluster topology. The list of + servers that the driver is aware of is a key part of this view. Each + server description contains an exhaustive description of its current + state including information about an endpoint, a server version, a + server type, and its current health state. If the server encounters issues in + reporting its health, ``HeartbeatException`` contains the exception from the + last failed heartbeat. Analyzing the ``HeartbeatException`` on each + cluster node can assist in diagnosing most server selection issues. + The following heartbeat exceptions are common: + + * ``No connection could be made because the target machine actively + refused it``: The driver cannot see this cluster node. This can be + because the cluster node has crashed, a firewall is preventing + network traffic from reaching the cluster node or port, or some other + network error is preventing traffic from being successfully routed to + the cluster node. + * ``Attempted to read past the end of the stream``: This error + happens when the driver cannot connect to the cluster nodes due to a + network error, misconfigured firewall, or other network issue. To + address this exception, ensure that all cluster nodes are reachable. + This error commonly occurs when the client machine’s IP address is + not configured in the Atlas IPs Access List, which can be found under + the :guilabel:`Network Access` tab for your Atlas Project. + * ``The remote certificate is invalid according to the validation + procedure``: This error typically indicates a TLS/SSL-related problem + such as an expired/invalid certificate or an untrusted root CA. You + can use tools like ``openssl s_client`` to debug TLS/SSL-related + certificate problems. \ No newline at end of file diff --git a/source/fundamentals/linq.txt b/source/fundamentals/linq.txt index 2e72709d..a66598c0 100644 --- a/source/fundamentals/linq.txt +++ b/source/fundamentals/linq.txt @@ -21,6 +21,8 @@ LINQ Overview -------- +.. include:: /includes/linq-vs-builders.rst + In this guide you can learn how to use `LINQ `__ with the {+driver-long+}. LINQ allows you to construct queries against @@ -1060,3 +1062,8 @@ uses a scalar operation, then prints the translated query: ``LoggedStages`` is not thread-safe. Executing a query and accessing the associated ``LoggedStages`` property from multiple threads might have non-deterministic results. + +Troubleshooting +--------------- + +.. include:: /includes/troubleshooting/unsupported-filter-expression.rst \ No newline at end of file diff --git a/source/fundamentals/serialization.txt b/source/fundamentals/serialization.txt index f5a0bfce..a144c98a 100644 --- a/source/fundamentals/serialization.txt +++ b/source/fundamentals/serialization.txt @@ -48,6 +48,50 @@ primitive types, collection types, and custom classes. For a full list of available serializers, see the `Serializers namespace API documentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Serializers.html>`__. +.. TODO: Revisit this page + +.. _csharp-faq-object-serializer: + +ObjectSerializer +---------------- + +The ``ObjectSerializer`` class allows serialization and deserialization only of types +that are considered safe. When you construct an ``ObjectSerializer``, +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 +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 +delegate you pass to the ``ObjectSerializer`` constructor. + +In the following example, +the ``ObjectSerializer`` will serialize and deserialize any type that is allowed by +``ObjectSerializer.DefaultAllowedTypes()`` or whose full name begins with +``"MyNamespace"``: + +.. code-block:: csharp + + var objectSerializer = new ObjectSerializer(type => ObjectSerializer.DefaultAllowedTypes(type) + || type.FullName.StartsWith("MyNamespace")); + BsonSerializer.RegisterSerializer(objectSerializer); + +To allow anonymous types to be serialized, add the boolean expression +``type.FullName.StartsWith("<>f__AnonymousType"))`` to your delegate, +as shown in the following example: + +.. code-block:: csharp + + var objectSerializer = new ObjectSerializer(type => ObjectSerializer.DefaultAllowedTypes(type) + || type.FullName.StartsWith("<>f__AnonymousType")); + BsonSerializer.RegisterSerializer(objectSerializer); + +You should create and register your ``ObjectSerializer`` at the start of your program, +before doing anything else. + Serializer Registry ------------------- diff --git a/source/includes/linq-vs-builders.rst b/source/includes/linq-vs-builders.rst new file mode 100644 index 00000000..2d016a5a --- /dev/null +++ b/source/includes/linq-vs-builders.rst @@ -0,0 +1,8 @@ +.. tip:: LINQ or Builders? + + If you're used to programming in {+language+}, consider using LINQ because of its similar feel + to programming in native {+language+}. If you have prior experience with other MongoDB drivers, + consider using ``Builder`` classes because of their consistency with other drivers. + + We encourage experimenting with both approaches to determine the most suitable mechanism + for your purposes. \ No newline at end of file diff --git a/source/includes/troubleshooting/unsupported-filter-expression.rst b/source/includes/troubleshooting/unsupported-filter-expression.rst new file mode 100644 index 00000000..69344be0 --- /dev/null +++ b/source/includes/troubleshooting/unsupported-filter-expression.rst @@ -0,0 +1,60 @@ +.. _csharp-faq-unsupported-expressions: + +``Unsupported filter`` or ``Expression not supported`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you use a LINQ or builder expression that isn't available in the Query API, +you might receive an ``Unsupported filter ...`` or ``Expression not +supported ...`` exception message. +An expression might not be available in the following cases: + +1. You are attempting to use a {+lang-framework+} feature that doesn't have an + equivalent MongoDB representation. For example, {+lang-framework+} and MongoDB have + different semantics around collations. +#. The driver doesn't support a particular transformation from the LINQ or + builder expression into the Query API. This might happen because the + provided query has no Query API translation or because a feature hasn't been + implemented in the driver. + +If you receive one of these exceptions, try the following steps: + +1. Use the `{+analyzer+} + `__ to analyze your + expressions. +#. Simplify your query where possible. +#. Provide a query as a ``BsonDocument`` object or JSON string. All + definition classes, such as ``FilterDefinition``, + ``ProjectionDefinition``, and ``PipelineDefinition``, support implicit + conversion from ``BsonDocument`` objects or JSON strings. For example, the + following filters are equivalent when used in a query or + aggregation: + + .. code-block:: csharp + + FilterDefinition typedFilter = Builders.Filter.Eq(e => e.A, 1); + FilterDefinition bsonFilter = new BsonDocument {{ "a", 1 }}; + FilterDefinition jsonFilter = "{ a : 1 }"; + +You can combine ``BsonDocument`` objects, JSON strings, POCOs in the same +query, as shown in the following example: + +.. code-block:: csharp + + FilterDefinition filter = Builders.Filter + .And(Builders.Filter + .Eq(e => e.A, 1), BsonDocument + .Parse("{ b : 2 }")); + +.. note:: + + If you use a ``BsonDocument`` object or JSON string, your field names must match + the case-sensitive names stored by the server. For example, when referencing + the ``_id`` field, you must refer to it by using the field name ``_id``. + + Because the Query API doesn't recognize + :ref:`manual class mappings `, + BSON serialization attributes, or serialization conventions, you can't use these + mechanisms to change field names. For example, if a document contains a field named + ``FirstName`` annotated with ``[BsonElement("first_name")]``, you must refer to it + as ``first_name`` in ``BsonDocument`` or JSON string definitions. + diff --git a/source/index.txt b/source/index.txt index 72444317..0730ca4c 100644 --- a/source/index.txt +++ b/source/index.txt @@ -134,6 +134,13 @@ The MongoDB Entity Framework Provider is an object-relational mapper (ORM) that use Microsoft's Entity Framework to work with MongoDB data. ORMs provide an object-oriented interface for data management. +The provider includes features such as the following: + +- Intelligent object tracking +- Entity-based LINQ operations +- Entity Framework modeling and mapping with the fluent API +- Automatic database updates through change tracking + To learn more, see the `MongoDB Entity Framework Provider documentation `__. @@ -143,4 +150,4 @@ To learn more, see the The {+analyzer-short+} is a tool that helps you understand how your {+driver-short+} code translates into the {+query-api+} and if your code includes any unsupported LINQ or builder expressions. To learn more, see the -`{+analyzer-short+} documentation `__. +`{+analyzer-short+} documentation `__. \ No newline at end of file