DOCSP-44706 - Type discriminator note (#342)

Co-authored-by: Stephanie <[email protected]>

Author: mongoKart

source/fundamentals/serialization/polymorphic-objects.txt

@@ -156,7 +156,19 @@ you must explicitly list each class you're looking for:
 .. code-block:: csharp
    :copyable: true
 
-   var query = coll.Aggregate().Match(a => a is Cat || a is Lion || a is Tiger);
+   var query = coll.AsQueryable().Where(
+       item => item.GetType() == typeof(Cat) ||
+       item.GetType() == typeof(Lion) ||
+       item.GetType() == typeof(Tiger));
+
+.. note:: OfType<T>() and the is Operator
+
+   When checking the type of a scalar discriminator, use the ``Where`` syntax shown in
+   the preceding code example. If you try to use the ``Aggregate().OfType<T>()`` method,
+   or if you pass an expression containing the ``is`` operator to the
+   ``Aggregate().Match()`` method, the driver throws an exception.
+
+.. _csharp-discriminator-hierarchical:
 
 HierarchicalDiscriminatorConvention
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/upgrade/v3.txt

@@ -203,4 +203,35 @@ Version 3.0 Breaking Changes
     property instead.
 
 - The driver removes individual cluster events from ``MongoClient.Cluster``. To listen for
-  cluster events, use `ClusterBuilder.Subscribe() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.Subscribe.html>`__.
+  cluster events, call the `ClusterBuilder.Subscribe() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.Subscribe.html>`__
+  method.
+
+- If any type in a collection uses a scalar discriminator, the driver throws
+  an exception if you perform either of the following actions on the collection:
+  
+  - Call the ``Aggregate().OfType<T>()`` method, as in the following example:
+
+    .. code-block:: csharp
+
+       collection.Aggregate().OfType<T>()
+
+  - Call the ``Aggregate().Match(item => item is T)`` method, as in the following example:
+
+    .. code-block:: csharp
+
+       collection.Aggregate().Match(item => item is T)
+  
+  To use either of the preceding methods on a collection, you can apply a hierarchical
+  discriminator to each class in the collection. See
+  the :ref:`Polymorphic Objects <csharp-discriminator-hierarchical>`
+  page to learn how.
+
+  Alternatively, you can check each item's type in a different way. For example, you
+  can call the ``Where()`` method and pass an expression that compares the item's type
+  to the type you're looking for, as in the following example:
+
+  .. code-block:: csharp
+
+     collection.AsQueryable().Where(item => item.GetType() == typeof(T));
+
+  To learn more about type discriminators, see :ref:`<csharp-polymorphism>`.

source/whats-new.txt

@@ -15,7 +15,7 @@ What's New
    :values: reference
 
 .. meta::
-   :keywords: update, new feature, deprecation, upgrade, driver v2.19, driver v2.20, driver v2.21, driver v2.22, driver v2.23, driver v2.24, driver v2.25, driver v2.26, driver v2.27, driver v2.28, driver v3.0
+   :keywords: update, new feature, deprecation, upgrade, driver v2.22, driver v2.23, driver v2.24, driver v2.25, driver v2.26, driver v2.27, driver v2.28, driver v3.0
 
 Learn what's new in: