Merge branch 'tech-review'

Author: jordan-smith721

.gitignore

@@ -14,4 +14,4 @@
 
 # System
 
-.DS_Store
+.DS_Store

README.rst

@@ -21,4 +21,4 @@ The MongoDB Documentation Project is governed by the terms of the
 `MongoDB Contributor Agreement
 <https://www.mongodb.com/legal/contributor-agreement>`_.
 
--- The MongoDB Docs Team
+-- The MongoDB Docs Team

config/intersphinx.yaml

@@ -6,4 +6,3 @@ path: python2.inv
 name: mongodb
 url: https:/www.mongodb.com/docs/manual/
 path: mongodb.inv
-...

snooty.toml

@@ -1,16 +1,16 @@
 name = "csharp"
 title = "C#/.NET"
 toc_landing_pages = [
-  "/fundamentals/connection",
-  "/fundamentals/crud",
-  "/usage-examples",
-  "/fundamentals",
+    "/fundamentals/connection",
+    "/fundamentals/crud",
+    "/usage-examples",
+    "/fundamentals",
 ]
 
 intersphinx = [
-  "https://www.mongodb.com/docs/manual/objects.inv",
-  "https://www.mongodb.com/docs/drivers/objects.inv",
-  "https://www.mongodb.com/docs/atlas/objects.inv",
+    "https://www.mongodb.com/docs/manual/objects.inv",
+    "https://www.mongodb.com/docs/drivers/objects.inv",
+    "https://www.mongodb.com/docs/atlas/objects.inv",
 ]
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
@@ -30,7 +30,7 @@ version = "v{+version-number+}"
 example = "https://raw.githubusercontent.com/mongodb/docs-csharp/{+docs-branch+}/source/includes/usage-examples/code-examples"
 stable-api = "Stable API"
 api-root = "https://mongodb.github.io/mongo-csharp-driver/{+version-number+}/apidocs/html"
-bool-data-type = "``bool``"
-string-data-type = "``str``"
-int-data-type = "``int``"
+bool-data-type = "``boolean``"
+string-data-type = "``string``"
+int-data-type = "``integer``"
 not-available = "N/A"

source/faq.txt

@@ -115,7 +115,9 @@ To resolve this issue, try the following steps:
    can severely affect your application performance. Before
    considering changes to this setting, address the concurrency problems
    in your application.
-   
+
+.. _csharp-faq-unsupported-expressions:
+
 Why are Certain LINQ or Builder Expressions Unsupported?
 --------------------------------------------------------
 
@@ -126,8 +128,8 @@ always possible for the following reasons:
    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 a server query. This may happen because the
-   provided query is too complicated or because a feature has not been
+   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
@@ -138,6 +140,9 @@ steps:
    <https://mongodb.github.io/mongo-csharp-driver/2.17/reference/driver/crud/linq3/>`__
    provider. The LINQ3 provider contains many fixes and new features
    over the LINQ2 provider.
+#. Use the `MongoDB Analyzer
+   <https://www.mongodb.com/docs/mongodb-analyzer/current/>`__ 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``,

source/fundamentals/authentication.txt

@@ -71,8 +71,7 @@ authentication mechanisms, depending on which MongoDB versions your server suppo
 .. note::
 
    MongoDB version 4.0 uses SCRAM as the default mechanism, and no longer
-   supports ``MONGODB-CR``. These versions automatically determine which
-   version of SCRAM to use.
+   supports ``MONGODB-CR``.
 
 
 Select the :guilabel:`Connection String` or :guilabel:`MongoCredential` tab to
@@ -200,6 +199,11 @@ see the corresponding syntax for specifying the ``X.509`` authentication mechani
              Server = new MongoServerAddress("<hostname", "<port>"),
          };
 
+      .. note:: Certificate Type
+
+         Your certificate must be a :wikipedia:`PCKS #12<PKCS_12>` type certificate
+         with a ``.p12`` extension.
+
       .. tip:: Username parameter
 
          The username parameter provided to ``CreateMongoX509Credential`` must

source/fundamentals/builders.txt

@@ -272,6 +272,66 @@ single field path``, in this case using ``Category``:
          // Using string-based field names
          var keys = builder.Wildcard("Category");
 
+Build an Aggregation Pipeline
+-----------------------------
+
+The ``PipelineDefinitionBuilder`` class provides a type-safe interface for
+defining an **aggregation pipeline**. An aggregation pipeline is a series of
+stages that are used to transform a document. Suppose you want to create a
+pipeline that performs the following operations:
+
+- Matches all documents with "spring" in the ``Season`` field
+- Sorts the results by the ``Category`` field
+- Groups the documents by category and shows the average price and total
+  available for all documents in that category
+
+Use ``PipelineDefinitionBuilder`` classes to build the pipeline:
+
+.. code-block:: csharp
+
+   var sortBuilder = Builders<Flower>.Sort.Ascending(f => f.Category);
+   var matchFilter = Builders<Flower>.Filter.AnyEq(f => f.Season, "spring");
+
+   var pipeline = new EmptyPipelineDefinition<Flower>()
+       .Match(matchFilter)
+       .Sort(sortBuilder)
+       .Group(f => f.Category,
+              g => new
+                 {
+                    name = g.Key, 
+                    avgPrice = g.Average(f => f.Price), 
+                    totalAvailable = g.Sum(f => f.Stock)
+                  }
+             );   
+
+The preceding example creates the following pipeline:
+
+.. code-block:: json
+   
+   [{ "$match" : { "season" : "spring" } }, { "$sort" : { "category" : 1 } }, { "$group" : { "_id" : "$category", "avgPrice" : { "$avg" : "$price" }, "totalAvailable" : { "$sum" : "$stock" } } }]
+
+You can add stages to your pipeline that don't have corresponding type-safe
+methods in the ``PipelineDefinitionBuilder`` interface by providing your query
+as a ``BsonDocument`` to the `AppendStage() method
+<{+api-root+}/M_MongoDB_Driver_PipelineDefinitionBuilder_AppendStage__3.htm>`__.
+
+.. code-block:: csharp
+
+   var pipeline = new EmptyPipelineDefinition<BsonDocument>().AppendStage<BsonDocument, BsonDocument, BsonDocument>("{ $set: { field1: '$field2' } }");
+
+.. note:: 
+
+   When using a ``BsonDocument`` to define your pipeline stage, the driver does
+   not take into account any ``BsonClassMap``, serialization attributes or
+   serialization conventions. The field names used in the ``BsonDocument`` must
+   match those stored on the server.
+
+   For more information on providing a query as a ``BsonDocument``, see our
+   :ref:`FAQ page <csharp-faq-unsupported-expressions>`.
+
+To learn more about the Aggregation Pipeline, see the
+:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` server manual page.
+
 Additional Information
 ----------------------
 
@@ -288,4 +348,5 @@ guide, see the following API Documentation:
 - `ProjectionDefinitionBuilder <{+api-root+}/T_MongoDB_Driver_ProjectionDefinitionBuilder_1.htm>`__
 - `SortDefinitionBuilder <{+api-root+}/T_MongoDB_Driver_SortDefinitionBuilder_1.htm>`__
 - `UpdateDefinitionBuilder <{+api-root+}/T_MongoDB_Driver_UpdateDefinitionBuilder_1.htm>`__
-- `IndexKeysDefinitionBuilder <{+api-root+}/T_MongoDB_Driver_IndexKeysDefinitionBuilder_1.htm>`__
+- `IndexKeysDefinitionBuilder <{+api-root+}/T_MongoDB_Driver_IndexKeysDefinitionBuilder_1.htm>`__
+- `IndexKeysDefinitionBuilder <{+api-root+}/T_MongoDB_Driver_PipelineDefinitionBuilder.htm>`__

source/fundamentals/class-mapping.txt

@@ -31,7 +31,7 @@ the name of the field in the document to the name of the property in the class.
    The type of the property in your class should match 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 serialize the data, the serializer will throw an exception.
+   attempts to deserialize the data, the serializer throws an exception.
 
 Manually Creating A Class Map
 -----------------------------
@@ -55,11 +55,11 @@ class:
 
 .. code-block:: csharp
 
-   BsonClassMap.RegisterClassMap<Person>(classmap => 
+   BsonClassMap.RegisterClassMap<Person>(classMap => 
    {
-       classmap.MapMember(p => p.Name);
-       classmap.MapMember(p => p.Age);
-       classmap.MapMember(p => p.Hobbies);
+       classMap.MapMember(p => p.Name);
+       classMap.MapMember(p => p.Age);
+       classMap.MapMember(p => p.Hobbies);
    });
 
 .. important::
@@ -73,14 +73,15 @@ register a class map and call the ``AutoMap()`` method before manually
 specifying your properties.
 
 In the following code example, the ``AutoMap()`` method maps all properties
-of the ``Person`` class except ``Hobbies``, which is mapped manually:
+of the ``Person`` class, then manually adjusts the mapping for the ``Hobbies``
+field:
 
 .. code-block:: csharp
 
-   BsonClassMap.RegisterClassMap<Person>(classmap => 
+   BsonClassMap.RegisterClassMap<Person>(classMap => 
    {
-       classmap.AutoMap();
-       classmap.MapMember(p => p.Hobbies);
+       classMap.AutoMap();
+       classMap.MapMember(p => p.Hobbies).SetElementName("favorite_hobbies");
    });
 
 Customize Class Serialization
@@ -120,10 +121,10 @@ You can also ignore any extra elements when registering a class map:
 
 .. code-block:: csharp
 
-   BsonClassMap.RegisterClassMap<Person>(classmap => 
+   BsonClassMap.RegisterClassMap<Person>(classMap => 
    {
-        classmap.AutoMap();
-        classmap.SetIgnoreExtraElements(true);
+        classMap.AutoMap();
+        classMap.SetIgnoreExtraElements(true);
    });
 
 Using Class Discriminators
@@ -152,10 +153,10 @@ You can also specify a discriminator when registering a class map as follows:
 
 .. code-block:: csharp
 
-   BsonClassMap.RegisterClassMap<Person>(classmap => 
+   BsonClassMap.RegisterClassMap<Person>(classMap => 
    {
-       classmap.AutoMap();
-       classmap.SetDiscriminator("personClass");
+       classMap.AutoMap();
+       classMap.SetDiscriminator("personClass");
    });
 
 In BSON, discriminators have the field name ``_t``. 
@@ -165,7 +166,7 @@ The following example shows how a document from the ``Person`` class with the
 
 .. code-block:: json
 
-   { "_id": "...", "_t": "personClass", "name": "...", "age": "...", "hobbies": [...]}
+   { "_id": "...", "_t": "personClass", "Name": "...", "Age": "...", "Hobbies": [...]}
 
 .. TODO: Link to page on polymorphism/discriminators
 
@@ -175,7 +176,7 @@ Mapping with Constructors
 By default, the {+driver-short+} can automatically map a class only if the class has
 a constructor with no arguments. If you want the driver to use a constructor that accepts
 one or more arguments, you can add the ``BsonConstructor`` attribute to the constructor.
-In this case, the driver parses the expression tree to determine how to map the   
+In this case, the driver the driver examines the types to determine how to map the
 constructor arguments to class properties or fields.
 
 When the driver creates a class map for the following ``Person`` class, it will use the 
@@ -223,10 +224,10 @@ You can also specify the constructor to use when registering your class map:
        }
    }
 
-   BsonClassMap.RegisterClassMap<Person>(classmap =>
+   BsonClassMap.RegisterClassMap<Person>(classMap =>
    {
-       classmap.AutoMap();
-       classmap.MapCreator(p => new Person(p.Name, p.Age));
+       classMap.AutoMap();
+       classMap.MapCreator(p => new Person(p.Name, p.Age));
    });
 
 Customize Property Serialization
@@ -261,10 +262,10 @@ You can also support extra elements when initializing a class map as follows:
 
 .. code-block:: csharp
 
-   BsonClassMap.RegisterClassMap<Person>(classmap => 
+   BsonClassMap.RegisterClassMap<Person>(classMap => 
    {
-       classmap.AutoMap();
-       classmap.MapExtraElementsMember(p => p.ExtraElements);
+       classMap.AutoMap();
+       classMap.MapExtraElementsMember(p => p.ExtraElements);
    });
 
 .. note::
@@ -277,14 +278,15 @@ Dynamically Serialize Properties
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can use a method to determine whether or not to serialize a property. For
-the driver to automatically use the method when serializing, the method must be
-named ``ShouldSerialize<property name>``. When the driver sees a method with
-this naming convention, it will use the method to determine whether or not to
-serialize properties of the provided property name.
+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
+properties that have the provided property name.
 
 The following example creates a method that only serializes the ``Age`` property
-if its value is greater than ``0``. The driver ignores any properties whose
-values don't meet this requirement:
+if its value is not equal to ``0``. The driver does not serialize any properties
+whose values don't meet this requirement:
 
 .. code-block:: csharp
 
@@ -296,19 +298,19 @@ values don't meet this requirement:
 
        public bool ShouldSerializeAge()
        {
-          return Age > 0;
+          return Age != 0;
        }
    }
 
 You can also specify the method while registering a class map:
 
 .. code-block:: csharp
 
-   BsonClassMap.RegisterClassMap<Employee>(classmap => 
+   BsonClassMap.RegisterClassMap<Employee>(classMap => 
    {
-       classmap.AutoMap();
-       classmap.MapMember(p => c.Age).SetShouldSerializeMethod(
-           obj => ((Person) obj).Age > 0
+       classMap.AutoMap();
+       classMap.MapMember(p => c.Age).SetShouldSerializeMethod(
+           obj => ((Person) obj).Age != 0
        );
    });