System.Linq.AsyncEnumerable breaking change in .NET 10 (#44989)

* Switched to new defintion, revised tables * lint * fix table * wip * Update docs/core/compatibility/core-libraries/10.0/asyncenumerable.md Co-authored-by: Stephen Toub <[email protected]> * Feedback and ToC --------- Co-authored-by: Stephen Toub <[email protected]>
dotnet · Feb 25, 2025 · df83502 · df83502
1 parent 5ffd99f
commit df83502
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 7 deletions.
diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md
@@ -19,13 +19,14 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 ## Core .NET libraries
 
 | Title                                                                                                                      | Type of change      | Introduced version |
-|----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
-| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md)                                    | Source incompatible | Preview 1          |
-| [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change   | Preview 1          |
-| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md)                        | Behavioral change   | Preview 1          |
-| [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md)                                           | Behavioral change   | Preview 1          |
-| [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md)                | Behavioral change   | Preview 1          |
-| [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md)                              | Behavioral change   | Preview 1          |
+| ---------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------------------- |
+|------------------------------------------------------------------------------------------------------------------------------|-----------------------|----------------------|
+| [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md)   | Behavioral change     | Preview 1            |
+| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md)                          | Behavioral change     | Preview 1            |
+| [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md)                                             | Behavioral change     | Preview 1            |
+| [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md)                  | Behavioral change     | Preview 1            |
+| [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md)                                | Behavioral change     | Preview 1            |
+| [System.Linq.AsyncEnumerable included in core libraries](core-libraries/10.0/asyncenumerable.md)                             | Source incompatible   | Preview 1            |
 
 ## Globalization
 

diff --git a/docs/core/compatibility/core-libraries/10.0/asyncenumerable.md b/docs/core/compatibility/core-libraries/10.0/asyncenumerable.md
@@ -0,0 +1,50 @@
+---
+title: "Breaking change - System.Linq.AsyncEnumerable in .NET 10"
+description: "Learn about the breaking change in .NET 10 where the AsyncEnumerable class is now included."
+ms.date: 2/21/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/44886
+---
+
+# System.Linq.AsyncEnumerable in .NET 10
+
+.NET 10 introduces the `AsyncEnumerable` class, which provides a full set of LINQ extension methods for the <xref:System.Collections.Generic.IAsyncEnumerable`1> type. This class replaces the community-maintained `System.Linq.Async` NuGet library, potentially causing compilation errors due to ambiguities.
+
+## Version introduced
+
+.NET 10 Preview 1
+
+## Previous behavior
+
+The `AsyncEnumerable` class in the `System.Linq.Async` package provided LINQ support for <xref:System.Collections.Generic.IAsyncEnumerable`1>.
+
+## New behavior
+
+The `AsyncEnumerable` class in .NET 10, as well as in the `System.Linq.AsyncEnumerable` NuGet package, provides LINQ support for <xref:System.Collections.Generic.IAsyncEnumerable`1>.
+
+## Type of breaking change
+
+This is a [source incompatible](../../categories.md#source-compatibility) change.
+
+## Reason for change
+
+<xref:System.Collections.Generic.IAsyncEnumerable`1> has become core enough that the platform itself should provide LINQ support for the type. Community support, including from the maintainers of `System.Linq.Async`, petitioned for this inclusion directly in the platform.
+
+## Recommended action
+
+If upgrading to .NET 10 and the code includes a direct package reference to `System.Linq.Async`, remove that package reference. For multitargeting both .NET 10 and previous versions, add a package reference to `System.Linq.AsyncEnumerable` instead.
+
+If `System.Linq.Async` is consumed indirectly via another package, avoid ambiguity errors by including this in the project:
+
+```xml
+<PackageReference Include="System.Linq.Async" Version="6.0.1">
+  <ExcludeAssets>all</ExcludeAssets>
+</PackageReference>
+```
+
+Most consuming code will not need changes, but some call sites might need updates to refer to newer names and signatures.
+
+## Affected APIs
+
+- `System.Linq.AsyncEnumerable`
+- <xref:System.Collections.Generic.IAsyncEnumerable`1>
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -22,6 +22,8 @@ items:
                 href: core-libraries/10.0/ldap-directorycontrol-parsing.md
               - name: MacCatalyst version normalization
                 href: core-libraries/10.0/maccatalyst-version-normalization.md
+              - name: System.Linq.AsyncEnumerable included in core libraries
+                href: core-libraries/10.0/asyncenumerable.md         
           - name: Cryptography
             items:
               - name: X500DistinguishedName validation is stricter
@@ -1352,6 +1354,8 @@ items:
                 href: core-libraries/10.0/ldap-directorycontrol-parsing.md
               - name: MacCatalyst version normalization
                 href: core-libraries/10.0/maccatalyst-version-normalization.md
+              - name: System.Linq.AsyncEnumerable included in core libraries
+                href: core-libraries/10.0/asyncenumerable.md
           - name: .NET 9
             items:
               - name: Adding a ZipArchiveEntry sets header general-purpose bit flags