From 04d40fb846f2bfa753fd9c2f6c253e39a35e2e44 Mon Sep 17 00:00:00 2001
From: Mike Woofter <108414937+mongoKart@users.noreply.github.com>
Date: Wed, 4 Dec 2024 15:52:13 -0600
Subject: [PATCH] DOCSP-44706 - Type discriminator note (#342)

Co-authored-by: Stephanie <52582720+stephmarie17@users.noreply.github.com>
(cherry picked from commit ab7d99ce1dfada3033e5679b857a56a22a6c7e60)
---
 .../serialization/polymorphic-objects.txt     | 14 +++++++-
 source/upgrade/v3.txt                         | 33 ++++++++++++++++++-
 source/whats-new.txt                          |  2 +-
 3 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/source/fundamentals/serialization/polymorphic-objects.txt b/source/fundamentals/serialization/polymorphic-objects.txt
index 0a921f01..07a4dc92 100644
--- a/source/fundamentals/serialization/polymorphic-objects.txt
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/source/upgrade/v3.txt b/source/upgrade/v3.txt
index 0cd51180..63c9686c 100644
--- a/source/upgrade/v3.txt
+++ b/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>`__.
\ No newline at end of file
+  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>`.
\ No newline at end of file
diff --git a/source/whats-new.txt b/source/whats-new.txt
index a6ccfef9..25e53852 100644
--- a/source/whats-new.txt
+++ b/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: