[Breaking change]: System.Linq.AsyncEnumerable in .NET 10

[stephentoub]

Description

.NET 10 now includes the AsyncEnumerable class, which provides a full set of Language Integrated Query (LINQ) extension methods for the IAsyncEnumerable<T> type. The System.Linq.Async NuGet library, although it sports a "System." prefix, was written and maintained by the community. This library is being replaced by the new built-in support in .NET 10, in part at the behest of the maintainers of System.Linq.Async. As a result, applications that currently reference the System.Linq.Async package may get compilation errors about ambiguities, due to extension methods with the same signatures being provided both by the old System.Linq.Async library and by the built-in support.

Version

.NET 10 Preview 1

Previous behavior

An AsyncEnumerable class in the System.Linq.Async package provides LINQ support for IAsyncEnumerable<T>.

New behavior

An AsyncEnumerable class in .NET 10 as well as in a System.Linq.AsyncEnumerable nuget package provides LINQ support for IAsyncEnumerable<T>.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

IAsyncEnumerable<T> has become core enough that it's important the platform itself provide LINQ support for the type. A swell of community support, including from the current maintainers of System.Linq.Async, petitioned for inclusion of such LINQ support directly in the platform.

Recommended action

If the consuming code being upgraded to .NET 10 includes a direct package reference to System.Linq.Async, remove that package reference. If the code needs to multitarget, such that it needs to compile for both .NET 10 and for previous versions of .NET, add a package reference to System.Linq.AsyncEnumerable instead.

If System.Linq.Async is being consumed indirectly via a dependency on another package that depends on System.Linq.Async, and that indirect dependency is leading to similar ambiguity errors, they can be avoided by including this in the project:

<PackageReference Include="System.Linq.Async" Version="6.0.1">
  <ExcludeAssets>all</ExcludeAssets>
</PackageReference>

Most consuming code will not need to change. However, some call sites might need updating to refer to newer names and signatures for functionality.

Feature area

Core .NET libraries

Affected APIs

System.Linq.AsyncEnumerable

---

Associated WorkItem - 373407

[eiriktsarpalis]

Reopening so that details regarding this request can be added.

[CamSoper]

@eiriktsarpalis At the time the original breaking change was published, we didn't have the API documented so we couldn't include XREFs. Those have been added, liberally, to answer the first part of the request asking for the details of what's included in the new library.

Regarding the rest of the request, it appears there is no documentation available for System.Linq.Async. Consequently, I don't have any way of establishing a delta between System.Linq.Async and the new API without writing samples to test every overload of every method. This will also require me to familiarize myself with IAsyncEnumerable, which I haven't worked with much.

I thought @stephentoub's recommendations were pretty clear, but what else can we provide here?