Add UnionBy documentation examples (#12518)

Author: mahmoudbakeer

snippets/csharp/System.Linq/Enumerable/AggregateTSource/enumerable.cs

@@ -3277,5 +3277,85 @@ public static void AggregateBySeedExample()
             // </Snippet206>
         }
         #endregion
+
+        #region UnionBy
+        static class UnionBy
+        {
+            // <Snippet207>
+            public static void UnionByKeySelectorExample()
+            {
+                (int ProductId, string Name , decimal Price)[] localProducts =
+                {
+                    (101, "Laptop", 1000m),                 
+                    (102, "Mouse", 100m),
+                    (103, "Keyboard", 120m)
+                };
+
+                (int ProductId, string Name, decimal Price)[] warehouseProducts =
+                {
+                    (102, "Mouse", 100m),      // Duplicate ProductId (already in local)
+                    (104, "Monitor", 800m),
+                    (101, "Laptop", 1000m)     // Duplicate ProductId (already in local)
+                };
+                var combinedProducts =
+                    localProducts.UnionBy(
+                        warehouseProducts,
+                        product => product.ProductId
+                    );
+
+                foreach (var product in combinedProducts)
+                {
+                    Console.WriteLine($"{product.ProductId}: {product.Name} - ${product.Price}");
+                }
+
+                /*
+                This code produces the following output:
+
+                101: Laptop - $1000
+                102: Mouse - $100
+                103: Keyboard - $120
+                104: Monitor - $800
+                */
+            }
+            // </Snippet207>
+
+            // <Snippet208>
+            public static void UnionByComparerExample()
+            {
+                (string Email, string FullName)[] marketingList =
+                {
+                    ("Mahmoud.Doe@example.com", "Mahmoud Doe"),
+                    ("alice.smith@example.com", "Alice Smith")
+                };
+
+                (string Email, string FullName)[] salesList =
+                {
+                    ("ALICE.SMITH@EXAMPLE.COM", "Alice S."), // Duplicate email, different casing
+                    ("Sara.jones@example.com", "Sara Jones")
+                };
+
+                var combinedList =
+                    marketingList.UnionBy(
+                        salesList,
+                        contact => contact.Email,
+                        StringComparer.OrdinalIgnoreCase
+                    );
+
+                foreach (var contact in combinedList)
+                {
+                    Console.WriteLine($"{contact.FullName} ({contact.Email})");
+                }
+
+                /*
+                This code produces the following output:
+
+                Mahmoud Doe (Mahmoud.Doe@example.com)
+                Alice Smith (alice.smith@example.com)
+                Sara Jones (Sara.jones@example.com)
+                */
+            }
+            // </Snippet208>
+        }
+        #endregion
     }
 }

xml/System.Linq/Enumerable.xml

@@ -17924,6 +17924,12 @@ The default equality comparer, <xref:System.Collections.Generic.EqualityComparer
 
 When the object returned by this method is enumerated, <xref:System.Linq.Enumerable.UnionBy*> enumerates `first` and `second` in that order and yields each element that has not already been yielded.
 
+## Examples
+
+The following example demonstrates how to use `UnionBy` to merge two collections of objects while excluding duplicates based on a specific property.
+
+:::code language="csharp" source="~/snippets/csharp/System.Linq/Enumerable/AggregateTSource/enumerable.cs" id="Snippet207":::
+
           ]]></format>
         </remarks>
         <related type="Article" href="/dotnet/csharp/programming-guide/concepts/linq/set-operations?branch=main#union-and-unionby">Union and UnionBy examples</related>
@@ -18008,6 +18014,12 @@ If `comparer` is `null`, the default equality comparer, <xref:System.Collections
 
 When the object returned by this method is enumerated, <xref:System.Linq.Enumerable.UnionBy*> enumerates `first` and `second` in that order and yields each element that has not already been yielded.
 
+## Examples
+
+The following example demonstrates how to use `UnionBy` to merge two collections while using a custom comparer to ignore case sensitivity when checking for duplicate keys.
+
+:::code language="csharp" source="~/snippets/csharp/System.Linq/Enumerable/AggregateTSource/enumerable.cs" id="Snippet208":::
+
           ]]></format>
         </remarks>
         <related type="Article" href="/dotnet/csharp/programming-guide/concepts/linq/set-operations?branch=main#union-and-unionby">Union and UnionBy examples</related>