Skip to content

Commit 7b4f584

Browse files
gewarrengewarren
authored
Two ASP.NET Core breaking changes (#24082)
1 parent aa646e8 commit 7b4f584

File tree

4 files changed

+180
-1
lines changed

4 files changed

+180
-1
lines changed

‎docs/core/compatibility/6.0.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Breaking changes in .NET 6
33
description: Navigate to the breaking changes in .NET 6.
4-
ms.date: 04/21/2021
4+
ms.date: 05/06/2021
55
no-loc: [Blazor, Razor, Kestrel]
66
---
77
# Breaking changes in .NET 6
@@ -19,7 +19,9 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
1919
- [Blazor: WebEventDescriptor.EventArgsType property replaced](aspnet-core/6.0/blazor-eventargstype-property-replaced.md)
2020
- [Changed MessagePack library in @microsoft/signalr-protocol-msgpack](aspnet-core/6.0/messagepack-library-change.md)
2121
- [Kestrel: Log message attributes changed](aspnet-core/6.0/kestrel-log-message-attributes-changed.md)
22+
- [Microsoft.AspNetCore.Http.Features split](aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md)
2223
- [Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports](aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md)
24+
- [Middleware: New Use overload](aspnet-core/6.0/middleware-new-use-overload.md)
2325
- [Nullable reference type annotations changed](aspnet-core/6.0/nullable-reference-type-annotations-changed.md)
2426
- [Obsoleted and removed APIs](aspnet-core/6.0/obsolete-removed-apis.md)
2527
- [PreserveCompilationContext not configured by default](aspnet-core/6.0/preservecompilationcontext-not-set-by-default.md)

‎docs/core/compatibility/aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: "Breaking change: Microsoft.AspNetCore.Http.Features split up"
3+
description: "Learn about the breaking change in ASP.NET Core 6.0 where the Microsoft.AspNetCore.Http.Features package has been split, and no longer ships as a package."
4+
ms.date: 05/06/2021
5+
---
6+
# Microsoft.AspNetCore.Http.Features split
7+
8+
Microsoft.AspNetCore.Http.Features has been split into the following two assemblies:
9+
10+
- Microsoft.AspNetCore.Http.Features
11+
- Microsoft.Extensions.Features
12+
13+
For discussion, see GitHub issue [dotnet/aspnetcore#32307](https://github.com/dotnet/aspnetcore/issues/32307).
14+
15+
## Version introduced
16+
17+
ASP.NET Core 6.0
18+
19+
## Old behavior
20+
21+
Microsoft.AspNetCore.Http.Features 5.0 shipped both in the ASP.NET shared framework and as a NuGet package. Microsoft.AspNetCore.Http.Features 5.0 targeted .NET 4.6.1, .NET Standard 2.0, and .NET 5.
22+
23+
## New behavior
24+
25+
Microsoft.AspNetCore.Http.Features 6.0 ships only in the ASP.NET shared framework, not as a NuGet package. It targets .NET 6 only.
26+
27+
Microsoft.Extensions.Features 6.0 ships in both the ASP.NET shared framework and as a NuGet package. It targets .NET 4.6.1, .NET Standard 2.0, and .NET 6.0.
28+
29+
The following types have been moved to the new Microsoft.Extensions.Features assembly:
30+
31+
- <xref:Microsoft.AspNetCore.Http.Features.IFeatureCollection>
32+
- <xref:Microsoft.AspNetCore.Http.Features.FeatureCollection>
33+
- <xref:Microsoft.AspNetCore.Http.Features.FeatureReference%601>
34+
- <xref:Microsoft.AspNetCore.Http.Features.FeatureReferences%601>
35+
36+
These types are still in the `Microsoft.AspNetCore.Http.Features` namespace, and type forwards have been added for compatibility.
37+
38+
## Reason for change
39+
40+
This change was introduced for two reasons:
41+
42+
- Allows the core types to be shared more broadly across components.
43+
- Allows the remaining Http-specific components in Microsoft.AspNetCore.Http.Features to take advantage of new runtime and language features.
44+
45+
## Recommended action
46+
47+
When upgrading to ASP.NET 6.0, remove any packages references for Microsoft.AspNetCore.Http.Features. Add a package reference for Microsoft.Extensions.Features only if required.
48+
49+
For class libraries that need to consume the types from Microsoft.AspNetCore.Http.Features, add a `FrameworkReference` instead:
50+
51+
```xml
52+
<ItemGroup>
53+
<FrameworkReference Include="Microsoft.AspNetCore.App" />
54+
</ItemGroup>
55+
```
56+
57+
For more information about adding the framework reference, see [Use the ASP.NET Core shared framework](/aspnet/core/fundamentals/target-aspnetcore?#use-the-aspnet-core-shared-framework).
58+
59+
Libraries with out of date references may encounter a <xref:System.TypeLoadException> or the following error:
60+
61+
**Error CS0433 The type 'IFeatureCollection' exists in both 'Microsoft.AspNetCore.Http.Features, Version=5.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60' and 'Microsoft.Extensions.Features, Version=6.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'**
62+
63+
To resolve the error, add a `FrameworkReference` to Microsoft.AspNetCore.App to any of the affected projects.
64+
65+
For questions, see [dotnet/aspnetcore#32307](https://github.com/dotnet/aspnetcore/issues/32307).
66+
67+
## Affected APIs
68+
69+
- <xref:Microsoft.AspNetCore.Http.Features.IFeatureCollection?displayProperty=fullName>
70+
- <xref:Microsoft.AspNetCore.Http.Features.FeatureCollection?displayProperty=fullName>
71+
- <xref:Microsoft.AspNetCore.Http.Features.FeatureReference%601?displayProperty=fullName>
72+
- <xref:Microsoft.AspNetCore.Http.Features.FeatureReferences%601?displayProperty=fullName>
73+
74+
<!--
75+
76+
## Category
77+
78+
ASP.NET Core
79+
80+
## Affected APIs
81+
82+
- `T:Microsoft.AspNetCore.Http.Features.IFeatureCollection`
83+
- `T:Microsoft.AspNetCore.Http.Features.FeatureCollection`
84+
- `T:Microsoft.AspNetCore.Http.Features.FeatureReference%601`
85+
- `T:Microsoft.AspNetCore.Http.Features.FeatureReferences%601`
86+
87+
-->

‎docs/core/compatibility/aspnet-core/6.0/middleware-new-use-overload.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: "Breaking change: Middleware: New Use overload"
3+
description: "Learn about the breaking change in ASP.NET Core 6.0 where a new overload of Use middleware was introduced."
4+
ms.date: 05/06/2021
5+
---
6+
# Middleware: New Use overload
7+
8+
A new overload of `app.Use` has been introduced. If you call `app.Use` but never call the `next` middleware, you'll now get compiler error CS0121:
9+
10+
**The call is ambiguous between the following methods or properties: 'UseExtensions.Use(IApplicationBuilder, Func<HttpContext, Func, Task>)' and 'UseExtensions.Use(IApplicationBuilder, Func<HttpContext, RequestDelegate, Task>)'**
11+
12+
To resolve the error, use `app.Run` instead of `app.Use`.
13+
14+
For discussion, see GitHub issue [dotnet/aspnetcore#32020](https://github.com/dotnet/aspnetcore/issues/32020).
15+
16+
## Version introduced
17+
18+
ASP.NET Core 6.0 Preview 4
19+
20+
## Old behavior
21+
22+
```csharp
23+
app.Use(async (context, next) =>
24+
{
25+
await next();
26+
});
27+
```
28+
29+
or
30+
31+
```csharp
32+
app.Use(async (context, next) =>
33+
{
34+
await SomeAsyncWork();
35+
// next not called...
36+
});
37+
```
38+
39+
## New behavior
40+
41+
You can now pass `context` to the `next` delegate:
42+
43+
```csharp
44+
app.Use(async (context, next) =>
45+
{
46+
await next(context);
47+
});
48+
```
49+
50+
Use `app.Run` when your middleware never calls `next`:
51+
52+
```csharp
53+
app.Run(async (context) =>
54+
{
55+
await SomeAsyncWork();
56+
// next never called
57+
});
58+
```
59+
60+
## Reason for change
61+
62+
The previous `Use` method allocates two objects per request. The new overload avoids these allocations with a small change to how you invoke the `next` middleware.
63+
64+
## Recommended action
65+
66+
If you get a compile error, it means you are calling `app.Use` without using the `next` delegate. Switch to `app.Run` to fix the error.
67+
68+
## Affected APIs
69+
70+
None.
71+
72+
<!--
73+
74+
## Category
75+
76+
ASP.NET Core
77+
78+
## Affected APIs
79+
80+
Not detectible via API analysis.
81+
82+
-->

‎docs/core/compatibility/toc.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,12 @@ items:
3535
href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md
3636
- name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack"
3737
href: aspnet-core/6.0/messagepack-library-change.md
38+
- name: Microsoft.AspNetCore.Http.Features split
39+
href: aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md
3840
- name: "Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports"
3941
href: aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md
42+
- name: "Middleware: New Use overload"
43+
href: aspnet-core/6.0/middleware-new-use-overload.md
4044
- name: Nullable reference type annotations changed
4145
href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md
4246
- name: Obsoleted and removed APIs
@@ -361,8 +365,12 @@ items:
361365
href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md
362366
- name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack"
363367
href: aspnet-core/6.0/messagepack-library-change.md
368+
- name: Microsoft.AspNetCore.Http.Features split
369+
href: aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md
364370
- name: "Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports"
365371
href: aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md
372+
- name: "Middleware: New Use overload"
373+
href: aspnet-core/6.0/middleware-new-use-overload.md
366374
- name: Nullable reference type annotations changed
367375
href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md
368376
- name: Obsoleted and removed APIs

0 commit comments

Comments
 (0)