Skip to content

Commit 441d490

Browse files
authored
Improve System.Linq.Async exclusion guidance for .NET 10 migration (#47931)
1 parent 92825ad commit 441d490

File tree

1 file changed

+22
-8
lines changed

1 file changed

+22
-8
lines changed

docs/core/compatibility/core-libraries/10.0/asyncenumerable.md

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,23 +24,37 @@ The <xref:System.Linq.AsyncEnumerable> class in .NET 10, and in the [`System.Lin
2424

2525
## Type of breaking change
2626

27-
This is a [source incompatible](../../categories.md#source-compatibility) change.
27+
This change can affect [source compatibility](../../categories.md#source-compatibility).
2828

2929
## Reason for change
3030

3131
<xref:System.Collections.Generic.IAsyncEnumerable`1> is a commonly used interface, so the platform itself should provide LINQ support for the type. Maintainers of `System.Linq.Async` and other community members petitioned for inclusion directly in the platform.
3232

3333
## Recommended action
3434

35-
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.
35+
If you're upgrading to .NET 10 and your code includes a direct package reference to `System.Linq.Async`, remove that package reference. For multitargeting both .NET 10 and a previous version, add a package reference to `System.Linq.AsyncEnumerable` instead.
3636

37-
If `System.Linq.Async` is consumed indirectly via another package, avoid ambiguity errors by including this in the project:
37+
If `System.Linq.Async` is consumed indirectly via another package, avoid ambiguity errors by adding `<ExcludeAssets>` metadata with a value of `compile` or `all`:
3838

39-
```xml
40-
<PackageReference Include="System.Linq.Async" Version="6.0.1">
41-
<ExcludeAssets>all</ExcludeAssets>
42-
</PackageReference>
43-
```
39+
- To allow transitive use of `System.Linq.Async`, set `<ExcludeAssets>` to `compile`:
40+
41+
```xml
42+
<PackageReference Include="System.Linq.Async" Version="6.0.1">
43+
<ExcludeAssets>compile</ExcludeAssets>
44+
</PackageReference>
45+
```
46+
47+
This configuration prevents direct usage in your code while allowing other packages to continue using System.Linq.Async internally.
48+
49+
- For complete exclusion, set `<ExcludeAssets>` to `all`:
50+
51+
```xml
52+
<PackageReference Include="System.Linq.Async" Version="6.0.1">
53+
<ExcludeAssets>all</ExcludeAssets>
54+
</PackageReference>
55+
```
56+
57+
Use this configuration only if you're certain no dependencies require System.Linq.Async at run time.
4458

4559
Most consuming code should be compatible without changes, but some call sites might need updates to refer to newer names and signatures. For example, a `Select` call like `e.Select(i => i * 2)` will work the same before and after. However, the call `e.SelectAwait(async (int i, CancellationToken ct) => i * 2)` will need to be changed to use `Select` instead of `SelectAwait`, as in `e.Select(async (int i, CancellationToken ct) => i * 2)`.
4660

0 commit comments

Comments
 (0)