diff --git a/docs/core/compatibility/6.0.md b/docs/core/compatibility/6.0.md index 5b22af10caaef..643032ee4849d 100644 --- a/docs/core/compatibility/6.0.md +++ b/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) diff --git a/docs/core/compatibility/aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md b/docs/core/compatibility/aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md new file mode 100644 index 0000000000000..586edeaf94e46 --- /dev/null +++ b/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: + +- +- +- +- + +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 + + + +``` + +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 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 + +- +- +- +- + + diff --git a/docs/core/compatibility/aspnet-core/6.0/middleware-new-use-overload.md b/docs/core/compatibility/aspnet-core/6.0/middleware-new-use-overload.md new file mode 100644 index 0000000000000..2dac25cb8697a --- /dev/null +++ b/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)' and 'UseExtensions.Use(IApplicationBuilder, Func)'** + +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. + + diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 488fb66e4df28..e1cf437b052b5 100644 --- a/docs/core/compatibility/toc.yml +++ b/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