Two ASP.NET Core breaking changes

docs/core/compatibility/6.0.md

@@ -1,7 +1,7 @@
 ---
 title: Breaking changes in .NET 6
 description: Navigate to the breaking changes in .NET 6.
-ms.date: 04/21/2021
+ms.date: 05/06/2021
 no-loc: [Blazor, Razor, Kestrel]
 ---
 # 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
 - [Blazor: WebEventDescriptor.EventArgsType property replaced](aspnet-core/6.0/blazor-eventargstype-property-replaced.md)
 - [Changed MessagePack library in @microsoft/signalr-protocol-msgpack](aspnet-core/6.0/messagepack-library-change.md)
 - [Kestrel: Log message attributes changed](aspnet-core/6.0/kestrel-log-message-attributes-changed.md)
+- [Microsoft.AspNetCore.Http.Features split](aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md)
 - [Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports](aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md)
+- [Middleware: New Use overload](aspnet-core/6.0/middleware-new-use-overload.md)
 - [Nullable reference type annotations changed](aspnet-core/6.0/nullable-reference-type-annotations-changed.md)
 - [Obsoleted and removed APIs](aspnet-core/6.0/obsolete-removed-apis.md)
 - [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

@@ -0,0 +1,87 @@
+---
+title: "Breaking change: Microsoft.AspNetCore.Http.Features split up"
+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."
+ms.date: 05/06/2021
+---
+# Microsoft.AspNetCore.Http.Features split
+
+Microsoft.AspNetCore.Http.Features has been split into the following two assemblies:
+
+- Microsoft.AspNetCore.Http.Features
+- Microsoft.Extensions.Features
+
+For discussion, see GitHub issue [dotnet/aspnetcore#32307](https://github.com/dotnet/aspnetcore/issues/32307).
+
+## Version introduced
+
+ASP.NET Core 6.0
+
+## Old behavior
+
+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.
+
+## New behavior
+
+Microsoft.AspNetCore.Http.Features 6.0 ships only in the ASP.NET shared framework, not as a NuGet package. It targets .NET 6 only.
+
+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.
+
+The following types have been moved to the new Microsoft.Extensions.Features assembly:
+
+- <xref:Microsoft.AspNetCore.Http.Features.IFeatureCollection>
+- <xref:Microsoft.AspNetCore.Http.Features.FeatureCollection>
+- <xref:Microsoft.AspNetCore.Http.Features.FeatureReference%601>
+- <xref:Microsoft.AspNetCore.Http.Features.FeatureReferences%601>
+
+These types are still in the `Microsoft.AspNetCore.Http.Features` namespace, and type forwards have been added for compatibility.
+
+## Reason for change
+
+This change was introduced for two reasons:
+
+- Allows the core types to be shared more broadly across components.
+- Allows the remaining Http-specific components in Microsoft.AspNetCore.Http.Features to take advantage of new runtime and language features.
+
+## Recommended action
+
+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.
+
+For class libraries that need to consume the types from Microsoft.AspNetCore.Http.Features, add a `FrameworkReference` instead:
+
+```xml
+<ItemGroup>
+  <FrameworkReference Include="Microsoft.AspNetCore.App" />
+</ItemGroup>
+```
+
+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).
+
+Libraries with out of date references may encounter a <xref:System.TypeLoadException> or the following error:
+
+**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'**
+
+To resolve the error, add a `FrameworkReference` to Microsoft.AspNetCore.App to any of the affected projects.
+
+For questions, see [dotnet/aspnetcore#32307](https://github.com/dotnet/aspnetcore/issues/32307).
+
+## Affected APIs
+
+- <xref:Microsoft.AspNetCore.Http.Features.IFeatureCollection?displayProperty=fullName>
+- <xref:Microsoft.AspNetCore.Http.Features.FeatureCollection?displayProperty=fullName>
+- <xref:Microsoft.AspNetCore.Http.Features.FeatureReference%601?displayProperty=fullName>
+- <xref:Microsoft.AspNetCore.Http.Features.FeatureReferences%601?displayProperty=fullName>
+
+<!--
+
+## Category
+
+ASP.NET Core
+
+## Affected APIs
+
+- `T:Microsoft.AspNetCore.Http.Features.IFeatureCollection`
+- `T:Microsoft.AspNetCore.Http.Features.FeatureCollection`
+- `T:Microsoft.AspNetCore.Http.Features.FeatureReference%601`
+- `T:Microsoft.AspNetCore.Http.Features.FeatureReferences%601`
+
+-->

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

@@ -0,0 +1,82 @@
+---
+title: "Breaking change: Middleware: New Use overload"
+description: "Learn about the breaking change in ASP.NET Core 6.0 where a new overload of Use middleware was introduced."
+ms.date: 05/06/2021
+---
+# Middleware: New Use overload
+
+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:
+
+**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>)'**
+
+To resolve the error, use `app.Run` instead of `app.Use`.
+
+For discussion, see GitHub issue [dotnet/aspnetcore#32020](https://github.com/dotnet/aspnetcore/issues/32020).
+
+## Version introduced
+
+ASP.NET Core 6.0 Preview 4
+
+## Old behavior
+
+```csharp
+app.Use(async (context, next) =>
+{
+    await next();
+});
+```
+
+or
+
+```csharp
+app.Use(async (context, next) =>
+{
+    await SomeAsyncWork();
+    // next not called...
+});
+```
+
+## New behavior
+
+You can now pass `context` to the `next` delegate:
+
+```csharp
+app.Use(async (context, next) =>
+{
+    await next(context);
+});
+```
+
+Use `app.Run` when your middleware never calls `next`:
+
+```csharp
+app.Run(async (context) =>
+{
+    await SomeAsyncWork();
+    // next never called
+});
+```
+
+## Reason for change
+
+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.
+
+## Recommended action
+
+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.
+
+## Affected APIs
+
+None.
+
+<!--
+
+## Category
+
+ASP.NET Core
+
+## Affected APIs
+
+Not detectible via API analysis.
+
+-->

docs/core/compatibility/toc.yml

@@ -35,8 +35,12 @@ items:
           href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md
         - name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack"
           href: aspnet-core/6.0/messagepack-library-change.md
+        - name: Microsoft.AspNetCore.Http.Features split
+          href: aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md
         - name: "Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports"
           href: aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md
+        - name: "Middleware: New Use overload"
+          href: aspnet-core/6.0/middleware-new-use-overload.md
         - name: Nullable reference type annotations changed
           href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md
         - name: Obsoleted and removed APIs
@@ -361,8 +365,12 @@ items:
           href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md
         - name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack"
           href: aspnet-core/6.0/messagepack-library-change.md
+        - name: Microsoft.AspNetCore.Http.Features split
+          href: aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md
         - name: "Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports"
           href: aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md
+        - name: "Middleware: New Use overload"
+          href: aspnet-core/6.0/middleware-new-use-overload.md
         - name: Nullable reference type annotations changed
           href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md
         - name: Obsoleted and removed APIs