diff --git a/docs/core/compatibility/2.2-3.0.md b/docs/core/compatibility/2.2-3.0.md index 5e3b591529a75..f56525c213d97 100644 --- a/docs/core/compatibility/2.2-3.0.md +++ b/docs/core/compatibility/2.2-3.0.md @@ -1,16 +1,196 @@ --- title: Breaking changes, version 2.2 to 3.0 - .NET Core description: Lists the breaking changes from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, and EF Core. -ms.date: "09/10/2019" +ms.date: "10/15/2019" author: "rpetrusha" ms.author: "ronpet" --- # Breaking changes for migration from Version 2.2 to 3.0 > [!IMPORTANT] -> This article is under construction. This is not a complete list of .NET Core breaking changes. For more information on .NET Core breaking changes, you can examine individual [breaking changes issues](https://github.com/dotnet/docs/issues?q=is%3Aissue+is%3Aopen+label%3Abreaking-change) in the dotnet/docs repository on GitHub. +> This article is under construction. This is not a complete list of .NET Core breaking changes. For more information on .NET Core breaking changes, you can examine individual [breaking changes issues](https://github.com/dotnet/docs/issues?q=is%3Aissue+is%3Aopen+label%3Abreaking-change) in the dotnet/docs repository on GitHub. -If you are migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, or EF Core, review the following topics for breaking changes that may affect your app: +If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, or EF Core, review the following topics for breaking changes that may affect your app: + +## ASP.NET Core + +[!INCLUDE[obsolete Antiforgery, CORS, Diagnostics, MVC, and Routing APIs removed](~/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md)] + +*** + +[!INCLUDE[Authentication: Google+ deprecation](~/includes/core-changes/aspnetcore/3.0/authn-google-plus-authn-changes.md)] + +*** + +[!INCLUDE[Authentication: HttpContext.Authentication property removed](~/includes/core-changes/aspnetcore/3.0/authn-httpcontext-property-removed.md)] + +*** + +[!INCLUDE[Authentication: Json.NET types replaced](~/includes/core-changes/aspnetcore/3.0/authn-apis-json-types.md)] + +*** + +[!INCLUDE[Authentication: OAuthHandler ExchangeCodeAsync signature changed](~/includes/core-changes/aspnetcore/3.0/authn-exchangecodeasync-signature-change.md)] + +*** + +[!INCLUDE[Authorization: AddAuthorization overload assembly change](~/includes/core-changes/aspnetcore/3.0/authz-assembly-change.md)] + +*** + +[!INCLUDE[Authorization: IAuthorizationPolicyProvider implementations require new method](~/includes/core-changes/aspnetcore/3.0/authz-iauthzpolicyprovider-new-method.md)] + +*** + +[!INCLUDE[Caching: CompactOnMemoryPressure property removed](~/includes/core-changes/aspnetcore/3.0/caching-memory-property-removed.md)] + +*** + +[!INCLUDE[Caching: Microsoft.Extensions.Caching.SqlServer uses new SqlClient package](~/includes/core-changes/aspnetcore/3.0/caching-new-sqlclient-package.md)] + +*** + +[!INCLUDE[Caching: ResponseCaching types changed to internal](~/includes/core-changes/aspnetcore/3.0/caching-response-pubternal-to-internal.md)] + +*** + +[!INCLUDE[Data Protection: DataProtection.AzureStorage uses new Azure Storage APIs](~/includes/core-changes/aspnetcore/3.0/dataprotection-azstorage-using-azstorage-apis.md)] + +*** + +[!INCLUDE[Hosting: ANCM version 1 removed from hosting bundle](~/includes/core-changes/aspnetcore/3.0/hosting-ancmv1-hosting-bundle-removal.md)] + +*** + +[!INCLUDE[Hosting: Generic host restriction on Startup constructor injection](~/includes/core-changes/aspnetcore/3.0/hosting-generic-host-startup-ctor-restriction.md)] + +*** + +[!INCLUDE[Hosting: IHostingEnvironment and IApplicationLifetime types replaced](~/includes/core-changes/aspnetcore/3.0/hosting-ihostingenv-iapplifetime-types-replaced.md)] + +*** + +[!INCLUDE[Hosting: ObjectPoolProvider removed from WebHostBuilder dependencies](~/includes/core-changes/aspnetcore/3.0/hosting-objectpoolprovider-webhostbuilder-dependencies.md)] + +*** + +[!INCLUDE[HTTP: DefaultHttpContext extensibility removed](~/includes/core-changes/aspnetcore/3.0/http-defaulthttpcontext-extensibility-removed.md)] + +*** + +[!INCLUDE[HTTP: HeaderNames fields changed to static readonly](~/includes/core-changes/aspnetcore/3.0/http-headernames-constants-staticreadonly.md)] + +*** + +[!INCLUDE[HTTP: Response body infrastructure changes](~/includes/core-changes/aspnetcore/3.0/http-response-body-changes.md)] + +*** + +[!INCLUDE[HTTP: Synchronous IO disabled by default](~/includes/core-changes/aspnetcore/3.0/http-synchronous-io-disabled.md)] + +*** + +[!INCLUDE[Identity: UI Bootstrap version change](~/includes/core-changes/aspnetcore/3.0/identity-ui-bootstrap-version.md)] + +*** + +[!INCLUDE[Identity: SignInAsync throws exception for unauthenticated identity](~/includes/core-changes/aspnetcore/3.0/identity-signinasync-throws-exception.md)] + +*** + +[!INCLUDE[Identity: SignInManager constructor accepts new parameter](~/includes/core-changes/aspnetcore/3.0/identity-signinmanager-ctor-parameter.md)] + +*** + +[!INCLUDE[Identity: UI uses static web assets feature](~/includes/core-changes/aspnetcore/3.0/identity-ui-static-web-assets.md)] + +*** + +[!INCLUDE[Kestrel: Connection adapters removed](~/includes/core-changes/aspnetcore/3.0/kestrel-connection-adapters-removed.md)] + +*** + +[!INCLUDE[Kestrel: Empty HTTPS assembly removed](~/includes/core-changes/aspnetcore/3.0/kestrel-empty-assembly-removed.md)] + +*** + +[!INCLUDE[Kestrel: Request trailer headers moved to new collection](~/includes/core-changes/aspnetcore/3.0/kestrel-request-trailer-headers.md)] + +*** + +[!INCLUDE[Kestrel: Transport abstraction layer changes](~/includes/core-changes/aspnetcore/3.0/kestrel-transport-abstractions.md)] + +*** + +[!INCLUDE[Localization: APIs marked obsolete](~/includes/core-changes/aspnetcore/3.0/localization-apis-marked-obsolete.md)] + +*** + +[!INCLUDE[Logging: DebugLogger class made internal](~/includes/core-changes/aspnetcore/3.0/logging-debuglogger-to-internal.md)] + +*** + +[!INCLUDE[MVC: Controller action Async suffix removed](~/includes/core-changes/aspnetcore/3.0/mvc-action-async-suffix-trimmed.md)] + +*** + +[!INCLUDE[MVC: Precompilation tool deprecated](~/includes/core-changes/aspnetcore/3.0/mvc-precompilation-tool-deprecated.md)] + +*** + +[!INCLUDE[MVC: Types changed to internal](~/includes/core-changes/aspnetcore/3.0/mvc-pubternal-to-internal.md)] + +*** + +[!INCLUDE[MVC: Web API compatibility shim removed](~/includes/core-changes/aspnetcore/3.0/mvc-webapi-compat-shim-removed.md)] + +*** + +[!INCLUDE[Razor: Runtime compilation moved to a package](~/includes/core-changes/aspnetcore/3.0/razor-runtime-compilation-package.md)] + +*** + +[!INCLUDE[Session state: Obsolete APIs removed](~/includes/core-changes/aspnetcore/3.0/session-obsolete-apis-removed.md)] + +*** + +[!INCLUDE[Shared framework: Assembly removal from Microsoft.AspNetCore.App](~/includes/core-changes/aspnetcore/3.0/sharedfx-app-shared-framework-assemblies.md)] + +*** + +[!INCLUDE[Shared framework: Microsoft.AspNetCore.All removed](~/includes/core-changes/aspnetcore/3.0/sharedfx-all-framework-removed.md)] + +*** + +[!INCLUDE[SignalR: HandshakeProtocol.SuccessHandshakeData replaced](~/includes/core-changes/aspnetcore/3.0/signalr-successhandshakedata-replaced.md)] + +*** + +[!INCLUDE[SignalR: HubConnection methods removed](~/includes/core-changes/aspnetcore/3.0/signalr-hubconnection-methods-removed.md)] + +*** + +[!INCLUDE[SignalR: HubConnectionContext constructors changed](~/includes/core-changes/aspnetcore/3.0/signalr-hubconnectioncontext-ctors.md)] + +*** + +[!INCLUDE[SignalR: JavaScript client package name change](~/includes/core-changes/aspnetcore/3.0/signalr-js-client-package-name.md)] + +*** + +[!INCLUDE[SignalR: Obsolete APIs](~/includes/core-changes/aspnetcore/3.0/signalr-obsolete-apis.md)] + +*** + +[!INCLUDE[SPAs: SpaServices and NodeServices marked obsolete](~/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-obsolete.md)] + +*** + +[!INCLUDE[SPAs: SpaServices and NodeServices console logger fallback default change](~/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-fallback.md)] + +*** + +[!INCLUDE[Target framework: .NET Framework not supported](~/includes/core-changes/aspnetcore/3.0/targetfx-netfx-tfm-support.md)] ## CoreFx @@ -56,6 +236,10 @@ If you are migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, [!INCLUDE[.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](~/includes/core-changes/cryptography/net-core-3-0-prefers-openssl-1-1-x.md)] +## Entity Framework Core + +[Entity Framework Core breaking changes](/ef/core/what-is-new/ef-core-3.0/breaking-changes) + ## Globalization [!INCLUDE["C" locale maps to the invariant locale](~/includes/core-changes/globalization/c-locale-maps-to-invariant-locale.md)] @@ -67,11 +251,3 @@ If you are migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, ## Visual Basic [!INCLUDE[vbNewLine is obsolete](~/includes/core-changes/visualbasic/vbnewline-is-obsolete.md)] - -## ASP.NET Core - -[ASP.NET Core breaking change announcements (on GitHub)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+is%3Aopen+label%3A%22Breaking+change%22+label%3A3.0.0) - -## Entity Framework Core - -[Entity Framework Core breaking changes](/ef/core/what-is-new/ef-core-3.0/breaking-changes) diff --git a/docs/core/compatibility/aspnetcore.md b/docs/core/compatibility/aspnetcore.md new file mode 100644 index 0000000000000..c0beaec3f7453 --- /dev/null +++ b/docs/core/compatibility/aspnetcore.md @@ -0,0 +1,193 @@ +--- +title: ASP.NET Core breaking changes - .NET Core +description: Lists the breaking changes in ASP.NET Core. +ms.date: "10/15/2019" +author: "scottaddie" +ms.author: "scaddie" +--- +# ASP.NET Core breaking changes + +> [!IMPORTANT] +> This article is under construction. This is not a complete list of ASP.NET Core breaking changes. For more information on ASP.NET Core breaking changes, you can examine individual [breaking changes issues](https://github.com/dotnet/docs/issues?q=is%3Aissue+is%3Aopen+label%3Abreaking-change) in the dotnet/docs repository on GitHub. + +The following is a list of ASP.NET Core breaking changes by ASP.NET Core version. ASP.NET Core provides the web app development features used by .NET Core. + +## ASP.NET Core 3.0 + +[!INCLUDE[obsolete Antiforgery, CORS, Diagnostics, MVC, and Routing APIs removed](~/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md)] + +*** + +[!INCLUDE[Authentication: Google+ deprecation](~/includes/core-changes/aspnetcore/3.0/authn-google-plus-authn-changes.md)] + +*** + +[!INCLUDE[Authentication: HttpContext.Authentication property removed](~/includes/core-changes/aspnetcore/3.0/authn-httpcontext-property-removed.md)] + +*** + +[!INCLUDE[Authentication: Json.NET types replaced](~/includes/core-changes/aspnetcore/3.0/authn-apis-json-types.md)] + +*** + +[!INCLUDE[Authentication: OAuthHandler ExchangeCodeAsync signature changed](~/includes/core-changes/aspnetcore/3.0/authn-exchangecodeasync-signature-change.md)] + +*** + +[!INCLUDE[Authorization: AddAuthorization overload assembly change](~/includes/core-changes/aspnetcore/3.0/authz-assembly-change.md)] + +*** + +[!INCLUDE[Authorization: IAuthorizationPolicyProvider implementations require new method](~/includes/core-changes/aspnetcore/3.0/authz-iauthzpolicyprovider-new-method.md)] + +*** + +[!INCLUDE[Caching: CompactOnMemoryPressure property removed](~/includes/core-changes/aspnetcore/3.0/caching-memory-property-removed.md)] + +*** + +[!INCLUDE[Caching: Microsoft.Extensions.Caching.SqlServer uses new SqlClient package](~/includes/core-changes/aspnetcore/3.0/caching-new-sqlclient-package.md)] + +*** + +[!INCLUDE[Caching: ResponseCaching types changed to internal](~/includes/core-changes/aspnetcore/3.0/caching-response-pubternal-to-internal.md)] + +*** + +[!INCLUDE[Data Protection: DataProtection.AzureStorage uses new Azure Storage APIs](~/includes/core-changes/aspnetcore/3.0/dataprotection-azstorage-using-azstorage-apis.md)] + +*** + +[!INCLUDE[Hosting: ANCM version 1 removed from hosting bundle](~/includes/core-changes/aspnetcore/3.0/hosting-ancmv1-hosting-bundle-removal.md)] + +*** + +[!INCLUDE[Hosting: Generic host restriction on Startup constructor injection](~/includes/core-changes/aspnetcore/3.0/hosting-generic-host-startup-ctor-restriction.md)] + +*** + +[!INCLUDE[Hosting: IHostingEnvironment and IApplicationLifetime types replaced](~/includes/core-changes/aspnetcore/3.0/hosting-ihostingenv-iapplifetime-types-replaced.md)] + +*** + +[!INCLUDE[Hosting: ObjectPoolProvider removed from WebHostBuilder dependencies](~/includes/core-changes/aspnetcore/3.0/hosting-objectpoolprovider-webhostbuilder-dependencies.md)] + +*** + +[!INCLUDE[HTTP: DefaultHttpContext extensibility removed](~/includes/core-changes/aspnetcore/3.0/http-defaulthttpcontext-extensibility-removed.md)] + +*** + +[!INCLUDE[HTTP: HeaderNames fields changed to static readonly](~/includes/core-changes/aspnetcore/3.0/http-headernames-constants-staticreadonly.md)] + +*** + +[!INCLUDE[HTTP: Response body infrastructure changes](~/includes/core-changes/aspnetcore/3.0/http-response-body-changes.md)] + +*** + +[!INCLUDE[HTTP: Synchronous IO disabled by default](~/includes/core-changes/aspnetcore/3.0/http-synchronous-io-disabled.md)] + +*** + +[!INCLUDE[Identity: UI Bootstrap version change](~/includes/core-changes/aspnetcore/3.0/identity-ui-bootstrap-version.md)] + +*** + +[!INCLUDE[Identity: SignInAsync throws exception for unauthenticated identity](~/includes/core-changes/aspnetcore/3.0/identity-signinasync-throws-exception.md)] + +*** + +[!INCLUDE[Identity: SignInManager constructor accepts new parameter](~/includes/core-changes/aspnetcore/3.0/identity-signinmanager-ctor-parameter.md)] + +*** + +[!INCLUDE[Identity: UI uses static web assets feature](~/includes/core-changes/aspnetcore/3.0/identity-ui-static-web-assets.md)] + +*** + +[!INCLUDE[Kestrel: Connection adapters removed](~/includes/core-changes/aspnetcore/3.0/kestrel-connection-adapters-removed.md)] + +*** + +[!INCLUDE[Kestrel: Empty HTTPS assembly removed](~/includes/core-changes/aspnetcore/3.0/kestrel-empty-assembly-removed.md)] + +*** + +[!INCLUDE[Kestrel: Request trailer headers moved to new collection](~/includes/core-changes/aspnetcore/3.0/kestrel-request-trailer-headers.md)] + +*** + +[!INCLUDE[Kestrel: Transport abstraction layer changes](~/includes/core-changes/aspnetcore/3.0/kestrel-transport-abstractions.md)] + +*** + +[!INCLUDE[Localization: APIs marked obsolete](~/includes/core-changes/aspnetcore/3.0/localization-apis-marked-obsolete.md)] + +*** + +[!INCLUDE[Logging: DebugLogger class made internal](~/includes/core-changes/aspnetcore/3.0/logging-debuglogger-to-internal.md)] + +*** + +[!INCLUDE[MVC: Controller action Async suffix removed](~/includes/core-changes/aspnetcore/3.0/mvc-action-async-suffix-trimmed.md)] + +*** + +[!INCLUDE[MVC: Precompilation tool deprecated](~/includes/core-changes/aspnetcore/3.0/mvc-precompilation-tool-deprecated.md)] + +*** + +[!INCLUDE[MVC: Types changed to internal](~/includes/core-changes/aspnetcore/3.0/mvc-pubternal-to-internal.md)] + +*** + +[!INCLUDE[MVC: Web API compatibility shim removed](~/includes/core-changes/aspnetcore/3.0/mvc-webapi-compat-shim-removed.md)] + +*** + +[!INCLUDE[Razor: Runtime compilation moved to a package](~/includes/core-changes/aspnetcore/3.0/razor-runtime-compilation-package.md)] + +*** + +[!INCLUDE[Session state: Obsolete APIs removed](~/includes/core-changes/aspnetcore/3.0/session-obsolete-apis-removed.md)] + +*** + +[!INCLUDE[Shared framework: Assembly removal from Microsoft.AspNetCore.App](~/includes/core-changes/aspnetcore/3.0/sharedfx-app-shared-framework-assemblies.md)] + +*** + +[!INCLUDE[Shared framework: Microsoft.AspNetCore.All removed](~/includes/core-changes/aspnetcore/3.0/sharedfx-all-framework-removed.md)] + +*** + +[!INCLUDE[SignalR: HandshakeProtocol.SuccessHandshakeData replaced](~/includes/core-changes/aspnetcore/3.0/signalr-successhandshakedata-replaced.md)] + +*** + +[!INCLUDE[SignalR: HubConnection methods removed](~/includes/core-changes/aspnetcore/3.0/signalr-hubconnection-methods-removed.md)] + +*** + +[!INCLUDE[SignalR: HubConnectionContext constructors changed](~/includes/core-changes/aspnetcore/3.0/signalr-hubconnectioncontext-ctors.md)] + +*** + +[!INCLUDE[SignalR: JavaScript client package name change](~/includes/core-changes/aspnetcore/3.0/signalr-js-client-package-name.md)] + +*** + +[!INCLUDE[SignalR: Obsolete APIs](~/includes/core-changes/aspnetcore/3.0/signalr-obsolete-apis.md)] + +*** + +[!INCLUDE[SPAs: SpaServices and NodeServices marked obsolete](~/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-obsolete.md)] + +*** + +[!INCLUDE[SPAs: SpaServices and NodeServices console logger fallback default change](~/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-fallback.md)] + +*** + +[!INCLUDE[Target framework: .NET Framework not supported](~/includes/core-changes/aspnetcore/3.0/targetfx-netfx-tfm-support.md)] diff --git a/docs/core/compatibility/breaking-changes.md b/docs/core/compatibility/breaking-changes.md index 963e06b9b0535..da6485997b707 100644 --- a/docs/core/compatibility/breaking-changes.md +++ b/docs/core/compatibility/breaking-changes.md @@ -11,9 +11,9 @@ The following version selector provides a filtered list of breaking changes for You can also view individual issues that detail the breaking changes introduced in .NET Core 3.0 in the following GitHub repositories: -- For .NET Core, the [dotnet/docs](https://github.com/dotnet/docs/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking-change) repo. -- For ASP.NET Core, the [aspnet/AspNetCore](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+is%3Aopen+label%3A%22Breaking+change%22+label%3A3.0.0) repo. -- For Entity Framework Core, the [aspnet/EntityFrameworkCore](https://github.com/aspnet/EntityFrameworkCore/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking-change) repo. +- For .NET Core, the [dotnet/docs](https://github.com/dotnet/docs/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking-change) repository. +- For ASP.NET Core, the [aspnet/Announcements](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+is%3Aopen+label%3A%22Breaking+change%22+label%3A3.0.0) repository. +- For Entity Framework Core, the [aspnet/EntityFrameworkCore](https://github.com/aspnet/EntityFrameworkCore/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking-change) repository. ## Breaking changes by version diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index fd26eda771b66..717fafa5bb174 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -22,19 +22,19 @@ href: 3.0.9-3.0rc1.md - name: By category items: + - name: ASP.NET Core + href: aspnetcore.md - name: CoreFx href: corefx.md - name: Cryptography href: cryptography.md + - name: Entity Framework Core + href: /ef/core/what-is-new/ef-core-3.0/breaking-changes - name: Globalization href: globalization.md - name: Networking href: networking.md - name: Visual Basic href: visualbasic.md - - name: ASP.NET Core (on GitHub) - href: https://github.com/aspnet/Announcements/issues?q=is%3Aissue+is%3Aopen+label%3A%22Breaking+change%22+label%3A3.0.0 - - name: Entity Framework Core - href: /ef/core/what-is-new/ef-core-3.0/breaking-changes - name: Windows Forms href: winforms.md diff --git a/includes/core-changes/aspnetcore/3.0/authn-apis-json-types.md b/includes/core-changes/aspnetcore/3.0/authn-apis-json-types.md new file mode 100644 index 0000000000000..4a93235b833fa --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/authn-apis-json-types.md @@ -0,0 +1,53 @@ +### Authentication: Newtonsoft.Json types replaced + +In ASP.NET Core 3.0, `Newtonsoft.Json` types used in Authentication APIs have been replaced with `System.Text.Json` types. Except for the following cases, basic usage of the Authentication packages remains unaffected: + +* Classes derived from the OAuth providers, such as those from [aspnet-contrib](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers). +* Advanced claim manipulation implementations. + +For more information, see [aspnet/AspNetCore#7105](https://github.com/aspnet/AspNetCore/pull/7105). For discussion, see [aspnet/AspNetCore#7289](https://github.com/aspnet/AspNetCore/issues/7289). + +#### Version introduced + +3.0 + +#### Recommended action + +For derived OAuth implementations, the most common change is to replace `JObject.Parse` with `JsonDocument.Parse` in the `CreateTicketAsync` override as shown [here](https://github.com/aspnet/AspNetCore/pull/7105/files?utf8=%E2%9C%93&diff=unified&w=1#diff-e1c9f9740a6fe8021020a6f249c589b0L40). `JsonDocument` implements `IDisposable`. + +The following list outlines known changes: + +- becomes `ClaimAction.Run(JsonElement userData, ClaimsIdentity identity, string issuer)`. All derived implementations of `ClaimAction` are similarly affected. +- becomes `MapCustomJson(this ClaimActionCollection collection, string claimType, Func resolver)` +- becomes `MapCustomJson(this ClaimActionCollection collection, string claimType, string valueType, Func resolver)` +- has had one old constructor removed and the other replaced `JObject` with `JsonElement`. The `User` property and `RunClaimActions` method have been updated to match. +- now accepts a parameter of type `JsonDocument` instead of `JObject`. The `Response` property has been updated to match. `OAuthTokenResponse` is now disposable and will be disposed by `OAuthHandler`. Derived OAuth implementations overriding `ExchangeCodeAsync` don't need to dispose the `JsonDocument` or `OAuthTokenResponse`. +- changed from `JObject` to `JsonDocument`. +- changed from `JObject` to `JsonElement`. +- changed from accepting `JObject` to `JsonElement`. + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- +- +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/authn-exchangecodeasync-signature-change.md b/includes/core-changes/aspnetcore/3.0/authn-exchangecodeasync-signature-change.md new file mode 100644 index 0000000000000..1dd43de90e684 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/authn-exchangecodeasync-signature-change.md @@ -0,0 +1,49 @@ +### Authentication: OAuthHandler ExchangeCodeAsync signature changed + +In ASP.NET Core 3.0, the signature of `OAuthHandler.ExchangeCodeAsync` was changed from: + +```csharp +protected virtual System.Threading.Tasks.Task ExchangeCodeAsync(string code, string redirectUri) { throw null; } +``` + +To: + +```csharp +protected virtual System.Threading.Tasks.Task ExchangeCodeAsync(Microsoft.AspNetCore.Authentication.OAuth.OAuthCodeExchangeContext context) { throw null; } +``` + +#### Version introduced + +3.0 + +#### Old behavior + +The `code` and `redirectUri` strings were passed as separate arguments. + +#### New behavior + +`Code` and `RedirectUri` are properties on `OAuthCodeExchangeContext` that can be set via the `OAuthCodeExchangeContext` constructor. The new `OAuthCodeExchangeContext` type is the only argument passed to `OAuthHandler.ExchangeCodeAsync`. + +#### Reason for change + +This change allows additional parameters to be provided in a non-breaking manner. There's no need to create new `ExchangeCodeAsync` overloads. + +#### Recommended action + +Construct an `OAuthCodeExchangeContext` with the appropriate `code` and `redirectUri` values. An instance must be provided. This single `OAuthCodeExchangeContext` instance can be passed to `OAuthHandler.ExchangeCodeAsync` instead of multiple arguments. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/authn-google-plus-authn-changes.md b/includes/core-changes/aspnetcore/3.0/authn-google-plus-authn-changes.md new file mode 100644 index 0000000000000..2f0081b592a61 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/authn-google-plus-authn-changes.md @@ -0,0 +1,78 @@ +### Authentication: Google+ deprecated and replaced + +Google is starting to [shut down](https://developers.google.com/+/api-shutdown) Google+ Sign-in for apps as early as January 28, 2019. + +#### Change description + +ASP.NET 4.x and ASP.NET Core have been using the Google+ Sign-in APIs to authenticate Google account users in web apps. The affected NuGet packages are [Microsoft.AspNetCore.Authentication.Google](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.Google/) for ASP.NET Core and [Microsoft.Owin.Security.Google](https://www.nuget.org/packages/Microsoft.Owin.Security.Google/) for `Microsoft.Owin` with ASP.NET Web Forms and MVC. + +Google's replacement APIs use a different data source and format. The mitigations and solutions provided below account for the structural changes. Apps should verify the data itself still satisfies their requirements. For example, names, email addresses, profile links, and profile photos may provide subtly different values than before. + +#### Version introduced + +All versions. This change is external to ASP.NET Core. + +#### Recommended action + +##### Owin with ASP.NET Web Forms and MVC + +For `Microsoft.Owin` 3.1.0 and later, a temporary mitigation is outlined [here](https://github.com/aspnet/AspNetKatana/issues/251#issuecomment-449587635). Apps should complete testing with the mitigation to check for changes in the data format. There are plans to release `Microsoft.Owin` 4.0.1 with a fix. Apps using any prior version should update to version 4.0.1. + +##### ASP.NET Core 1.x + +The mitigation in [Owin with ASP.NET Web Forms and MVC](#owin-with-aspnet-web-forms-and-mvc) can be adapted to ASP.NET Core 1.x. NuGet package patches aren't planned because 1.x has reached [end of life](https://dotnet.microsoft.com/platform/support-policy) status. + +##### ASP.NET Core 2.x + +For `Microsoft.AspNetCore.Authentication.Google` version 2.x, replace your existing call to `AddGoogle` in `Startup.ConfigureServices` with the following code: + +```csharp +.AddGoogle(o => +{ + o.ClientId = Configuration["Authentication:Google:ClientId"]; + o.ClientSecret = Configuration["Authentication:Google:ClientSecret"]; + o.UserInformationEndpoint = "https://www.googleapis.com/oauth2/v2/userinfo"; + o.ClaimActions.Clear(); + o.ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "id"); + o.ClaimActions.MapJsonKey(ClaimTypes.Name, "name"); + o.ClaimActions.MapJsonKey(ClaimTypes.GivenName, "given_name"); + o.ClaimActions.MapJsonKey(ClaimTypes.Surname, "family_name"); + o.ClaimActions.MapJsonKey("urn:google:profile", "link"); + o.ClaimActions.MapJsonKey(ClaimTypes.Email, "email"); +}); +``` + +The February 2.1 and 2.2 patches incorporated the preceding reconfiguration as the new default. No patch is planned for ASP.NET Core 2.0 since it has reached [end of life](https://dotnet.microsoft.com/platform/support-policy). + +##### ASP.NET Core 3.0 + +The mitigation given for ASP.NET Core 2.x can also be used for ASP.NET Core 3.0. In future 3.0 previews, the `Microsoft.AspNetCore.Authentication.Google` package may be removed. Users would be directed to `Microsoft.AspNetCore.Authentication.OpenIdConnect` instead. The following code shows how to replace `AddGoogle` with `AddOpenIdConnect` in `Startup.ConfigureServices`. This replacement can be used with ASP.NET Core 2.0 and later and can be adapted for ASP.NET Core 1.x as needed. + +```csharp +.AddOpenIdConnect("Google", o => +{ + o.ClientId = Configuration["Authentication:Google:ClientId"]; + o.ClientSecret = Configuration["Authentication:Google:ClientSecret"]; + o.Authority = "https://accounts.google.com"; + o.ResponseType = OpenIdConnectResponseType.Code; + o.CallbackPath = "/signin-google"; // Or register the default "/sigin-oidc" + o.Scope.Add("email"); +}); +JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/authn-httpcontext-property-removed.md b/includes/core-changes/aspnetcore/3.0/authn-httpcontext-property-removed.md new file mode 100644 index 0000000000000..5ab6eabd153bf --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/authn-httpcontext-property-removed.md @@ -0,0 +1,59 @@ +### Authentication: HttpContext.Authentication property removed + +The deprecated `Authentication` property on `HttpContext` has been removed. + +#### Change description + +As part of [aspnet/AspNetCore#6504](https://github.com/aspnet/AspNetCore/pull/6504), the deprecated `Authentication` property on `HttpContext` has been removed. The `Authentication` property has been deprecated since 2.0. A [migration guide](/aspnet/core/migration/1x-to-2x/identity-2x?view=aspnetcore-2.2#use-httpcontext-authentication-extensions) was published to migrate code using this deprecated property to the new replacement APIs. The remaining unused classes / APIs related to the old ASP.NET Core 1.x authentication stack were removed in commit [aspnet/AspNetCore@d7a7c65](https://github.com/aspnet/AspNetCore/commit/d7a7c65). + +For discussion, see [aspnet/AspNetCore#6533](https://github.com/aspnet/AspNetCore/issues/6533). + +#### Version introduced + +3.0 + +#### Reason for change + +ASP.NET Core 1.0 APIs have been replaced by extension methods in . + +#### Recommended action + +See the [migration guide](/aspnet/core/migration/1x-to-2x/identity-2x?view=aspnetcore-2.2#use-httpcontext-authentication-extensions). + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- +- +- +- +- +- +- +- +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/authz-assembly-change.md b/includes/core-changes/aspnetcore/3.0/authz-assembly-change.md new file mode 100644 index 0000000000000..54ae5b601d9db --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/authz-assembly-change.md @@ -0,0 +1,39 @@ +### Authorization: AddAuthorization overload moved to different assembly + +The core `AddAuthorization` methods that used to reside in `Microsoft.AspNetCore.Authorization` were renamed to `AddAuthorizationCore`. The old `AddAuthorization` methods still exist, but are in the `Microsoft.AspNetCore.Authorization.Policy` package instead. Apps using both methods should see no impact. Apps that weren't using the policy package must switch to using `AddAuthorizationCore`. + +#### Version introduced + +3.0 + +#### Old behavior + +`AddAuthorization` methods existed in `Microsoft.AspNetCore.Authorization`. + +#### New behavior + +`AddAuthorization` methods exist in `Microsoft.AspNetCore.Authorization.Policy`. `AddAuthorizationCore` is the new name for the old methods. + +#### Reason for change + +`AddAuthorization` is a better method name for adding all common services needed for authorization. + +#### Recommended action + +Either add a reference to `Microsoft.AspNetCore.Authorization.Policy` or use `AddAuthorizationCore` instead. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/authz-iauthzpolicyprovider-new-method.md b/includes/core-changes/aspnetcore/3.0/authz-iauthzpolicyprovider-new-method.md new file mode 100644 index 0000000000000..f9cf03f9c8aaa --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/authz-iauthzpolicyprovider-new-method.md @@ -0,0 +1,41 @@ +### Authorization: IAuthorizationPolicyProvider implementations require new method + +In ASP.NET Core 3.0, a new `GetFallbackPolicyAsync` method was added to `IAuthorizationPolicyProvider`. This fallback policy is used by the authorization middleware when no policy is specified. + +For more information, see [aspnet/AspNetCore#9759](https://github.com/aspnet/AspNetCore/pull/9759). + +#### Version introduced + +3.0 + +#### Old behavior + +Implementations of `IAuthorizationPolicyProvider` didn't require a `GetFallbackPolicyAsync` method. + +#### New behavior + +Implementations of `IAuthorizationPolicyProvider` require a `GetFallbackPolicyAsync` method. + +#### Reason for change + +A new method was needed for the new `AuthorizationMiddleware` to use when no policy is specified. + +#### Recommended action + +Add the `GetFallbackPolicyAsync` method to your implementations of `IAuthorizationPolicyProvider`. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/caching-memory-property-removed.md b/includes/core-changes/aspnetcore/3.0/caching-memory-property-removed.md new file mode 100644 index 0000000000000..ab9e81fa1334c --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/caching-memory-property-removed.md @@ -0,0 +1,43 @@ +### Caching: CompactOnMemoryPressure property removed + +The ASP.NET Core 3.0 release removed the [obsolete MemoryCacheOptions APIs](https://github.com/aspnet/Extensions/blob/dc5c593da7b72c82e6fe85abb91d03818f9b700c/src/Caching/Memory/src/MemoryCacheOptions.cs#L17-L18). + +#### Change description + +This change is a follow-up to [aspnet/Caching#221](https://github.com/aspnet/Caching/issues/221). For discussion, see [aspnet/Extensions#1062](https://github.com/aspnet/Extensions/issues/1062). + +#### Version introduced + +3.0 + +#### Old behavior + +`MemoryCacheOptions.CompactOnMemoryPressure` property was available. + +#### New behavior + +The `MemoryCacheOptions.CompactOnMemoryPressure` property has been removed. + +#### Reason for change + +Automatically compacting the cache caused problems. To avoid unexpected behavior, the cache should only be compacted when needed. + +#### Recommended action + +To compact the cache, downcast to `MemoryCache` and call `Compact` when needed. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/caching-new-sqlclient-package.md b/includes/core-changes/aspnetcore/3.0/caching-new-sqlclient-package.md new file mode 100644 index 0000000000000..b424cbdfea8ad --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/caching-new-sqlclient-package.md @@ -0,0 +1,39 @@ +### Caching: Microsoft.Extensions.Caching.SqlServer uses new SqlClient package + +The `Microsoft.Extensions.Caching.SqlServer` package will use the new `Microsoft.Data.SqlClient` package instead of `System.Data.SqlClient` package. This change could cause slight behavioral breaking changes. For more information, see [Introducing the new Microsoft.Data.SqlClient](https://devblogs.microsoft.com/dotnet/introducing-the-new-microsoftdatasqlclient/). + +#### Version introduced + +3.0 + +#### Old behavior + +The `Microsoft.Extensions.Caching.SqlServer` package used the `System.Data.SqlClient` package. + +#### New behavior + +`Microsoft.Extensions.Caching.SqlServer` is now using the `Microsoft.Data.SqlClient` package. + +#### Reason for change + +`Microsoft.Data.SqlClient` is a new package that is built off of `System.Data.SqlClient`. It's where all new feature work will be done from now on. + +#### Recommended action + +Customers shouldn't need to worry about this breaking change unless they were using types returned by the `Microsoft.Extensions.Caching.SqlServer` package and casting them to `System.Data.SqlClient` types. For example, if someone was casting a `DbConnection` to the [old SqlConnection type](xref:System.Data.SqlClient.SqlConnection), they would need to change the cast to the new `Microsoft.Data.SqlClient.SqlConnection` type. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/caching-response-pubternal-to-internal.md b/includes/core-changes/aspnetcore/3.0/caching-response-pubternal-to-internal.md new file mode 100644 index 0000000000000..07be641926790 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/caching-response-pubternal-to-internal.md @@ -0,0 +1,66 @@ +### Caching: ResponseCaching "pubternal" types changed to internal + +In ASP.NET Core 3.0, "pubternal" types in `ResponseCaching` have been changed to `internal`. + +In addition, default implementations of `IResponseCachingPolicyProvider` and `IResponseCachingKeyProvider` are no longer added to services as part of the `AddResponseCaching` method. + +#### Change description + +In ASP.NET Core, "pubternal" types are declared as `public` but reside in a namespace suffixed with `.Internal`. While these types are public, they have no support policy and are subject to breaking changes. Unfortunately, accidental use of these types has been common, resulting in breaking changes to these projects and limiting the ability to maintain the framework. + +#### Version introduced + +3.0 + +#### Old behavior + +These types were publicly visible, but unsupported. + +#### New behavior + +These types are now `internal`. + +#### Reason for change + +The `internal` scope better reflects the unsupported policy. + +#### Recommended action + +Copy types that are used by your app or library. + +#### Category + +ASP.NET Core + +#### Affected APIs + +- `Microsoft.AspNetCore.ResponseCaching.Internal.CachedResponse` +- `Microsoft.AspNetCore.ResponseCaching.Internal.CachedVaryByRules` +- `Microsoft.AspNetCore.ResponseCaching.Internal.IResponseCache` +- `Microsoft.AspNetCore.ResponseCaching.Internal.IResponseCacheEntry` +- `Microsoft.AspNetCore.ResponseCaching.Internal.IResponseCachingKeyProvider` +- `Microsoft.AspNetCore.ResponseCaching.Internal.IResponseCachingPolicyProvider` +- `Microsoft.AspNetCore.ResponseCaching.Internal.MemoryResponseCache` +- `Microsoft.AspNetCore.ResponseCaching.Internal.ResponseCachingContext` +- `Microsoft.AspNetCore.ResponseCaching.Internal.ResponseCachingKeyProvider` +- `Microsoft.AspNetCore.ResponseCaching.Internal.ResponseCachingPolicyProvider` +- + + diff --git a/includes/core-changes/aspnetcore/3.0/dataprotection-azstorage-using-azstorage-apis.md b/includes/core-changes/aspnetcore/3.0/dataprotection-azstorage-using-azstorage-apis.md new file mode 100644 index 0000000000000..f42f398f1ce56 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/dataprotection-azstorage-using-azstorage-apis.md @@ -0,0 +1,50 @@ +### Data Protection: DataProtection.AzureStorage uses new Azure Storage APIs + + depends on the [Azure Storage libraries](https://github.com/Azure/azure-storage-net). These libraries renamed their assemblies, packages, and namespaces. Starting in ASP.NET Core 3.0, `Microsoft.AspNetCore.DataProtection.AzureStorage` uses the new `Microsoft.Azure.Storage.`-prefixed APIs and packages. + +For questions about the Azure Storage APIs, use . For discussion on this issue, see [aspnet/AspNetCore#8472](https://github.com/aspnet/AspNetCore/issues/8472). + +#### Version introduced + +3.0 + +#### Old behavior + +The package referenced the `WindowsAzure.Storage` NuGet package. + +#### New behavior + +The package references the `Microsoft.Azure.Storage.Blob` NuGet package. + +#### Reason for change + +This change allows `Microsoft.AspNetCore.DataProtection.AzureStorage` to migrate to the recommended Azure Storage packages. + +#### Recommended action + +If you still need to use the older Azure Storage APIs with ASP.NET Core 3.0, add a direct dependency to the [WindowsAzure.Storage](https://www.nuget.org/packages/WindowsAzure.Storage/) package. This package can be installed alongside the new `Microsoft.Azure.Storage` APIs. + +In many cases, the upgrade only involves changing the `using` statements to use the new namespaces: + +```diff +- using Microsoft.WindowsAzure.Storage; +- using Microsoft.WindowsAzure.Storage.Blob; ++ using Microsoft.Azure.Storage; ++ using Microsoft.Azure.Storage.Blob; +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/hosting-ancmv1-hosting-bundle-removal.md b/includes/core-changes/aspnetcore/3.0/hosting-ancmv1-hosting-bundle-removal.md new file mode 100644 index 0000000000000..30ca56230987f --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/hosting-ancmv1-hosting-bundle-removal.md @@ -0,0 +1,50 @@ +### Hosting: AspNetCoreModule V1 removed from Windows Hosting Bundle + +Starting with ASP.NET Core 3.0, the Windows Hosting Bundle won't contain AspNetCoreModule (ANCM) V1. + +ANCM V2 is backwards compatible with ANCM OutOfProcess and is recommended for use with ASP.NET Core 3.0 apps. + +For discussion, see [aspnet/AspNetCore#7095](https://github.com/aspnet/AspNetCore/issues/7095). + +#### Version introduced + +3.0 + +#### Old behavior + +ANCM V1 is included in the Windows Hosting Bundle. + +#### New behavior + +ANCM V1 isn't included in the Windows Hosting Bundle. + +#### Reason for change + +ANCM V2 is backwards compatible with ANCM OutOfProcess and is recommended for use with ASP.NET Core 3.0 apps. + +#### Recommended action + +Use ANCM V2 with ASP.NET Core 3.0 apps. + +If ANCM V1 is required, it can be installed using the ASP.NET Core 2.1 or 2.2 Windows Hosting Bundle. + +This change will break ASP.NET Core 3.0 apps that: + +- Explicitly opted into using ANCM V1 with `AspNetCoreModule`. +- Have a custom *web.config* file with ``. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/hosting-generic-host-startup-ctor-restriction.md b/includes/core-changes/aspnetcore/3.0/hosting-generic-host-startup-ctor-restriction.md new file mode 100644 index 0000000000000..8329a4489ff37 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/hosting-generic-host-startup-ctor-restriction.md @@ -0,0 +1,49 @@ +### Hosting: Generic host restricts Startup constructor injection + +The only types the generic host supports for `Startup` class constructor injection are `IHostEnvironment`, `IWebHostEnvironment`, and `IConfiguration`. Apps using `WebHost` are unaffected. + +#### Change description + +Prior to ASP.NET Core 3.0, constructor injection could be used for arbitrary types in the `Startup` class's constructor. In ASP.NET Core 3.0, the web stack was replatformed onto the generic host library. You can see the change in the *Program.cs* file of the templates: + +**ASP.NET Core 2.x:** + + + +**ASP.NET Core 3.0:** + + + +`Host` uses one dependency injection (DI) container to build the app. `WebHost` uses two containers: one for the host and one for the app. As a result, the `Startup` constructor no longer supports custom service injection. Only `IHostEnvironment`, `IWebHostEnvironment`, and `IConfiguration` can be injected. This change prevents DI issues such as the duplicate creation of a singleton service. + +#### Version introduced + +3.0 + +#### Reason for change + +This change is a consequence of replatforming the web stack onto the generic host library. + +#### Recommended action + +Inject services into the `Startup.Configure` method signature. For example: + +```csharp +public void Configure(IApplicationBuilder app, IOptions options) +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/hosting-ihostingenv-iapplifetime-types-replaced.md b/includes/core-changes/aspnetcore/3.0/hosting-ihostingenv-iapplifetime-types-replaced.md new file mode 100644 index 0000000000000..57d439e70b56a --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/hosting-ihostingenv-iapplifetime-types-replaced.md @@ -0,0 +1,67 @@ +### Hosting: IHostingEnvironment and IApplicationLifetime types marked obsolete and replaced + +New types have been introduced to replace existing `IHostingEnvironment` and `IApplicationLifetime` types. + +#### Version introduced + +3.0 + +#### Old behavior + +There were two different `IHostingEnvironment` and `IApplicationLifetime` types from `Microsoft.Extensions.Hosting` and `Microsoft.AspNetCore.Hosting`. + +#### New behavior + +The old types have been marked as obsolete and replaced with new types. + +#### Reason for change + +When `Microsoft.Extensions.Hosting` was introduced in ASP.NET Core 2.1, some types like `IHostingEnvironment` and `IApplicationLifetime` were copied from `Microsoft.AspNetCore.Hosting`. Some ASP.NET Core 3.0 changes cause apps to include both the `Microsoft.Extensions.Hosting` and `Microsoft.AspNetCore.Hosting` namespaces. Any use of those duplicate types causes an "ambiguous reference" compiler error when both namespaces are referenced. + +#### Recommended action + +Replaced any usages of the old types with the newly introduced types as below: + +**Obsolete types (warning):** + +- +- +- +- +- +- + +**New types:** + +- +- `Microsoft.AspNetCore.Hosting.IWebHostEnvironment : IHostEnvironment` +- +- + +The new `IHostEnvironment` `IsDevelopment` and `IsProduction` extension methods are in the `Microsoft.Extensions.Hosting` namespace. That namespace may need to be added to your project. + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- +- +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/hosting-objectpoolprovider-webhostbuilder-dependencies.md b/includes/core-changes/aspnetcore/3.0/hosting-objectpoolprovider-webhostbuilder-dependencies.md new file mode 100644 index 0000000000000..2ac4be8d59b22 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/hosting-objectpoolprovider-webhostbuilder-dependencies.md @@ -0,0 +1,41 @@ +### Hosting: ObjectPoolProvider removed from WebHostBuilder dependencies + +As part of making ASP.NET Core more pay for play, the `ObjectPoolProvider` was removed from the main set of dependencies. Specific components relying on `ObjectPoolProvider` now add it themselves. + +For discussion, see [aspnet/AspNetCore#5944](https://github.com/aspnet/AspNetCore/issues/5944). + +#### Version introduced + +3.0 + +#### Old behavior + +`WebHostBuilder` provides `ObjectPoolProvider` by default in the DI container. + +#### New behavior + +`WebHostBuilder` no longer provides `ObjectPoolProvider` by default in the DI container. + +#### Reason for change + +This change was made to make ASP.NET Core more pay for play. + +#### Recommended action + +If your component requires `ObjectPoolProvider`, it needs to be added to your dependencies via the `IServiceCollection`. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/http-defaulthttpcontext-extensibility-removed.md b/includes/core-changes/aspnetcore/3.0/http-defaulthttpcontext-extensibility-removed.md new file mode 100644 index 0000000000000..aa69f27ff44e3 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/http-defaulthttpcontext-extensibility-removed.md @@ -0,0 +1,43 @@ +### HTTP: DefaultHttpContext extensibility removed + +As part of ASP.NET Core 3.0 performance improvements, the extensibility of `DefaultHttpContext` was removed. The class is now `sealed`. For more information, see [aspnet/AspNetCore#6504](https://github.com/aspnet/AspNetCore/pull/6504). + +If your unit tests use `Mock`, use `Mock` instead. + +For discussion, see [aspnet/AspNetCore#6534](https://github.com/aspnet/AspNetCore/issues/6534). + +#### Version introduced + +3.0 + +#### Old behavior + +Classes can derive from `DefaultHttpContext`. + +#### New behavior + +Classes can't derive from `DefaultHttpContext`. + +#### Reason for change + +The extensibility was provided initially to allow pooling of the `HttpContext`, but it introduced unnecessary complexity and impeded other optimizations. + +#### Recommended action + +If you're using `Mock` in your unit tests, begin using `Mock` instead. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/http-headernames-constants-staticreadonly.md b/includes/core-changes/aspnetcore/3.0/http-headernames-constants-staticreadonly.md new file mode 100644 index 0000000000000..1ebfec557739c --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/http-headernames-constants-staticreadonly.md @@ -0,0 +1,50 @@ +### HTTP: HeaderNames constants changed to static readonly + +Starting in ASP.NET Core 3.0 Preview 5, the fields in changed from `const` to `static readonly`. + +For discussion, see [aspnet/AspNetCore#9514](https://github.com/aspnet/AspNetCore/issues/9514). + +#### Version introduced + +3.0 + +#### Old behavior + +These fields used to be `const`. + +#### New behavior + +These fields are now `static readonly`. + +#### Reason for change + +The change: + +* Prevents the values from being embedded across assembly boundaries, allowing for value corrections as needed. +* Enables faster reference equality checks. + +#### Recommended action + +Recompile against 3.0. Source code using these fields in the following ways can no longer do so: + +* As an attribute argument +* As a `case` in a `switch` statement +* When defining another `const` + +To work around the breaking change, switch to using self-defined header name constants or string literals. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/http-response-body-changes.md b/includes/core-changes/aspnetcore/3.0/http-response-body-changes.md new file mode 100644 index 0000000000000..77b1dfd199e14 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/http-response-body-changes.md @@ -0,0 +1,48 @@ +### HTTP: Response body infrastructure changes + +The infrastructure backing an HTTP response body has changed. If you're using `HttpResponse` directly, you shouldn't need to make any code changes. Read further if you're wrapping or replacing `HttpResponse.Body` or accessing `HttpContext.Features`. + +#### Version introduced + +3.0 + +#### Old behavior + +There were three APIs associated with the HTTP response body: + +- `IHttpResponseFeature.Body` +- `IHttpSendFileFeature.SendFileAsync` +- `IHttpBufferingFeature.DisableResponseBuffering` + +#### New behavior + +If you replace `HttpResponse.Body`, it replaces the entire `IHttpResponseBodyFeature` with a wrapper around your given stream using `StreamResponseBodyFeature` to provide default implementations for all of the expected APIs. Setting back the original stream reverts this change. + +#### Reason for change + +The motivation is to combine the response body APIs into a single new feature interface. + +#### Recommended action + +Use `IHttpResponseBodyFeature` where you previously were using `IHttpResponseFeature.Body`, +`IHttpSendFileFeature`, or `IHttpBufferingFeature`. + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/http-synchronous-io-disabled.md b/includes/core-changes/aspnetcore/3.0/http-synchronous-io-disabled.md new file mode 100644 index 0000000000000..21f5540cb0d69 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/http-synchronous-io-disabled.md @@ -0,0 +1,90 @@ +### HTTP: Synchronous IO disabled in all servers + +Starting with ASP.NET Core 3.0, synchronous server operations are disabled by default. + +#### Change description + +`AllowSynchronousIO` is an option in each server that enables or disables synchronous IO APIs like `HttpRequest.Body.Read`, `HttpResponse.Body.Write`, and `Stream.Flush`. These APIs have long been a source of thread starvation and app hangs. Starting in ASP.NET Core 3.0 Preview 3, these synchronous operations are disabled by default. + +Affected servers: + +- Kestrel +- HttpSys +- IIS in-process +- TestServer + +Expect errors similar to: + +- `Synchronous operations are disallowed. Call ReadAsync or set AllowSynchronousIO to true instead.` +- `Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.` +- `Synchronous operations are disallowed. Call FlushAsync or set AllowSynchronousIO to true instead.` + +Each server has an `AllowSynchronousIO` option that controls this behavior and the default for all of them is now `false`. + +The behavior can also be overridden on a per-request basis as a temporary mitigation. For example: + +```csharp +var syncIOFeature = HttpContext.Features.Get(); +if (syncIOFeature != null) +{ + syncIOFeature.AllowSynchronousIO = true; +} +``` + +If you have trouble with a `TextWriter` or another stream calling a synchronous API in `Dispose`, call the new `DisposeAsync` API instead. + +For discussion, see [aspnet/AspNetCore#7644](https://github.com/aspnet/AspNetCore/issues/7644). + +#### Version introduced + +3.0 + +#### Old behavior + +`HttpRequest.Body.Read`, `HttpResponse.Body.Write`, and `Stream.Flush` were allowed by default. + +#### New behavior + +These synchronous APIs are disallowed by default: + +Expect errors similar to: + +- `Synchronous operations are disallowed. Call ReadAsync or set AllowSynchronousIO to true instead.` +- `Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.` +- `Synchronous operations are disallowed. Call FlushAsync or set AllowSynchronousIO to true instead.` + +#### Reason for change + +These synchronous APIs have long been a source of thread starvation and app hangs. Starting in ASP.NET Core 3.0 Preview 3, the synchronous operations are disabled by default. + +#### Recommended action + +Use the asynchronous versions of the methods. The behavior can also be overridden on a per-request basis as a temporary mitigation. + +```csharp +var syncIOFeature = HttpContext.Features.Get(); +if (syncIOFeature != null) +{ + syncIOFeature.AllowSynchronousIO = true; +} +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/identity-signinasync-throws-exception.md b/includes/core-changes/aspnetcore/3.0/identity-signinasync-throws-exception.md new file mode 100644 index 0000000000000..8a68806454205 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/identity-signinasync-throws-exception.md @@ -0,0 +1,39 @@ +### Identity: SignInAsync throws exception for unauthenticated identity + +By default, `SignInAsync` throws an exception for principals / identities in which `IsAuthenticated` is `false`. + +#### Version introduced + +3.0 + +#### Old behavior + +`SignInAsync` accepts any principals / identities, including identities in which `IsAuthenticated` is `false`. + +#### New behavior + +By default, `SignInAsync` throws an exception for principals / identities in which `IsAuthenticated` is `false`. There's a new flag to suppress this behavior, but the default behavior has changed. + +#### Reason for change + +The old behavior was problematic because, by default, these principals were rejected by `[Authorize]` / `RequireAuthenticatedUser()`. + +#### Recommended action + +In ASP.NET Core 3.0 Preview 6, there's a `RequireAuthenticatedSignIn` flag on `AuthenticationOptions` that is `true` by default. Set this flag to `false` to restore the old behavior. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/identity-signinmanager-ctor-parameter.md b/includes/core-changes/aspnetcore/3.0/identity-signinmanager-ctor-parameter.md new file mode 100644 index 0000000000000..0453accbd5d74 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/identity-signinmanager-ctor-parameter.md @@ -0,0 +1,31 @@ +### Identity: SignInManager constructor accepts new parameter + +Starting with ASP.NET Core 3.0, a new `IUserConfirmation` parameter was added to the `SignInManager` constructor. For more information, see [aspnet/AspNetCore#8356](https://github.com/aspnet/AspNetCore/issues/8356). + +#### Version introduced + +3.0 + +#### Reason for change + +The motivation for the change was to add support for new email / confirmation flows in Identity. + +#### Recommended action + +If manually constructing a `SignInManager`, provide an implementation of `IUserConfirmation` or grab one from dependency injection to provide. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/identity-ui-bootstrap-version.md b/includes/core-changes/aspnetcore/3.0/identity-ui-bootstrap-version.md new file mode 100644 index 0000000000000..15f8800935ad2 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/identity-ui-bootstrap-version.md @@ -0,0 +1,52 @@ +### Identity: Default Bootstrap version of UI changed + +Starting in ASP.NET Core 3.0, Identity UI defaults to using version 4 of Bootstrap. + +#### Version introduced + +3.0 + +#### Old behavior + +The `services.AddDefaultIdentity().AddDefaultUI();` method call was the same as `services.AddDefaultIdentity().AddDefaultUI(UIFramework.Bootstrap3);` + +#### New behavior + +The `services.AddDefaultIdentity().AddDefaultUI();` method call is the same as `services.AddDefaultIdentity().AddDefaultUI(UIFramework.Bootstrap4);` + +#### Reason for change + +Bootstrap 4 was released during ASP.NET Core 3.0 timeframe. + +#### Recommended action + +You're impacted by this change if you use the default Identity UI and have added it in `Startup.ConfigureServices` as shown in the following example: + +```csharp +services.AddDefaultIdentity().AddDefaultUI(); +``` + +Take one of the following actions: + +- Migrate your app to use Bootstrap 4 using their [migration guide](https://getbootstrap.com/docs/4.0/migration). +- Update `Startup.ConfigureServices` to enforce usage of Bootstrap 3. For example: + + ```csharp + services.AddDefaultIdentity().AddDefaultUI(UIFramework.Bootstrap3); + ``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/identity-ui-static-web-assets.md b/includes/core-changes/aspnetcore/3.0/identity-ui-static-web-assets.md new file mode 100644 index 0000000000000..11a49bf39cbf7 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/identity-ui-static-web-assets.md @@ -0,0 +1,50 @@ +### Identity: UI uses static web assets feature + +ASP.NET Core 3.0 introduced a static web assets feature, and Identity UI has adopted it. + +#### Change description + +As a result of Identity UI adopting the static web assets feature: + +- Framework selection is accomplished by using the `IdentityUIFrameworkVersion` property in your project file. +- Bootstrap 4 is the default UI framework for Identity UI. Bootstrap 3 has reached end of life, and you should consider migrating to a supported version. + +#### Version introduced + +3.0 + +#### Old behavior + +The default UI framework for Identity UI was **Bootstrap 3**. The UI framework could be configured using a parameter to the `AddIdentityUI` method call in `Startup.ConfigureServices`. + +#### New behavior + +The default UI framework for Identity UI is **Bootstrap 4**. The UI framework must be configured in your project file, instead of in the `AddIdentityUI` method call. + +#### Reason for change + +Adoption of the static web assets feature required that the UI framework configuration move to MSBuild. The decision on which framework to embed is a build-time decision, not a runtime decision. + +#### Recommended action + +Review your site UI to ensure the new Bootstrap 4 components are compatible. If necessary, use the `IdentityUIFrameworkVersion` MSBuild property to revert to Bootstrap 3. Add the property to a `` element in your project file: + +```xml +Bootstrap3 +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/kestrel-connection-adapters-removed.md b/includes/core-changes/aspnetcore/3.0/kestrel-connection-adapters-removed.md new file mode 100644 index 0000000000000..2f2e01e5a7fec --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/kestrel-connection-adapters-removed.md @@ -0,0 +1,41 @@ +### Kestrel: Connection adapters removed + +As part of the move to move "pubternal" APIs to `public`, the concept of an `IConnectionAdapter` was removed from Kestrel. Connection adapters are being replaced with connection middleware (similar to HTTP middleware in the ASP.NET Core pipeline, but for lower-level connections). HTTPS and connection logging have moved from connection adapters to connection middleware. Those extension methods should continue to work seamlessly, but the implementation details have changed. + +For more information, see [aspnet/AspNetCore#11412](https://github.com/aspnet/AspNetCore/pull/11412). For discussion, see [aspnet/AspNetCore#11475](https://github.com/aspnet/AspNetCore/issues/11475). + +#### Version introduced + +3.0 + +#### Old behavior + +Kestrel extensibility components were created using `IConnectionAdapter`. + +#### New behavior + +Kestrel extensibility components are created as [middleware](https://github.com/aspnet/AspNetCore/pull/11412/files#diff-89acc06acf1b2e96bbdb811ce523619f). + +#### Reason for change + +This change is intended to provide a more flexible extensibility architecture. + +#### Recommended action + +Convert any implementations of `IConnectionAdapter` to use the new middleware pattern as shown [here](https://github.com/aspnet/AspNetCore/pull/11412/files#diff-89acc06acf1b2e96bbdb811ce523619f). + +#### Category + +ASP.NET Core + +#### Affected APIs + +`Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter` + + diff --git a/includes/core-changes/aspnetcore/3.0/kestrel-empty-assembly-removed.md b/includes/core-changes/aspnetcore/3.0/kestrel-empty-assembly-removed.md new file mode 100644 index 0000000000000..a2cb72424345f --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/kestrel-empty-assembly-removed.md @@ -0,0 +1,32 @@ +### Kestrel: Empty HTTPS assembly removed + +The assembly has been removed. + +#### Version introduced + +3.0 + +#### Reason for change + +In ASP.NET Core 2.1, the contents of `Microsoft.AspNetCore.Server.Kestrel.Https` were moved to . This change was done in a non-breaking way using `[TypeForwardedTo]` attributes. + +#### Recommended action + +- Libraries referencing `Microsoft.AspNetCore.Server.Kestrel.Https` 2.0 should update all ASP.NET Core dependencies to 2.1 or later. Otherwise, they may break when loaded into an ASP.NET Core 3.0 app. +- Apps and libraries targeting ASP.NET Core 2.1 and later should remove any direct references to the `Microsoft.AspNetCore.Server.Kestrel.Https` NuGet package. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/kestrel-request-trailer-headers.md b/includes/core-changes/aspnetcore/3.0/kestrel-request-trailer-headers.md new file mode 100644 index 0000000000000..245eb07e86fd8 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/kestrel-request-trailer-headers.md @@ -0,0 +1,52 @@ +### Kestrel: Request trailer headers moved to new collection + +In prior versions, Kestrel added HTTP/1.1 chunked trailer headers into the request headers collection when the request body was read to the end. This behavior caused concerns about ambiguity between headers and trailers. The decision was made to move the trailers to a new collection. + +HTTP/2 request trailers were unavailable in ASP.NET Core 2.2 but are now also available in this new collection in ASP.NET Core 3.0. + +New request extension methods have been added to access these trailers. + +HTTP/1.1 trailers are available once the entire request body has been read. + +HTTP/2 trailers are available once they're received from the client. The client won't send the trailers until the entire request body has been at least buffered by the server. You may need to read the request body to free up buffer space. Trailers are always available if you read the request body to the end. The trailers mark the end of the body. + +#### Version introduced + +3.0 + +#### Old behavior + +Request trailer headers would be added to the `HttpRequest.Headers` collection. + +#### New behavior + +Request trailer headers **aren't present** in the `HttpRequest.Headers` collection. Use the following extension methods on `HttpRequest` to access them: + +- `GetDeclaredTrailers()` - Gets the request "Trailer" header that lists which trailers to expect after the body. +- `SupportsTrailers()` - Indicates if the request supports receiving trailer headers. +- `CheckTrailersAvailable()` - Determines if the request supports trailers and if they're available for reading. +- `GetTrailer(string trailerName)` - Gets the requested trailing header from the response. + +#### Reason for change + +Trailers are a key feature in scenarios like gRPC. Merging the trailers in to request headers was confusing to users. + +#### Recommended action + +Use the trailer-related extension methods on `HttpRequest` to access trailers. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/kestrel-transport-abstractions.md b/includes/core-changes/aspnetcore/3.0/kestrel-transport-abstractions.md new file mode 100644 index 0000000000000..d54aa777e6984 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/kestrel-transport-abstractions.md @@ -0,0 +1,40 @@ +### Kestrel: Transport abstractions removed and made public + +As part of moving away from "pubternal" APIs, the Kestrel transport layer APIs are exposed as a public interface in the `Microsoft.AspNetCore.Connections.Abstractions` library. + +#### Version introduced + +3.0 + +#### Old behavior + +- Transport-related abstractions were available in the `Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions` library. +- The `ListenOptions.NoDelay` property was available. + +#### New behavior + +- The `IConnectionListener` interface was introduced in the `Microsoft.AspNetCore.Connections.Abstractions` library to expose the most used functionality from the `...Transport.Abstractions` library. +- The `NoDelay` is now available in transport options (`LibuvTransportOptions` and `SocketTransportOptions`). +- `SchedulingMode` is no longer available. + +#### Reason for change + +ASP.NET Core 3.0 has moved away from "pubternal" APIs. + +#### Recommended action + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/localization-apis-marked-obsolete.md b/includes/core-changes/aspnetcore/3.0/localization-apis-marked-obsolete.md new file mode 100644 index 0000000000000..e9f9e5171b82c --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/localization-apis-marked-obsolete.md @@ -0,0 +1,43 @@ +### Localization: ResourceManagerWithCultureStringLocalizer and WithCulture marked obsolete + +The [ResourceManagerWithCultureStringLocalizer](https://github.com/aspnet/Localization/blob/43b974482c7b703c92085c6f68b3b23d8fe32720/src/Microsoft.Extensions.Localization/ResourceManagerWithCultureStringLocalizer.cs#L18) class and [WithCulture](https://github.com/aspnet/Localization/blob/master/src/Microsoft.Extensions.Localization/ResourceManagerStringLocalizer.cs#L154-L170) interface member are often sources of confusion for users of localization, especially when creating their own `IStringLocalizer` implementation. These items give the user the impression that an `IStringLocalizer` instance is "per-language, per-resource". In reality, the instances should only be "per-resource". The language searched for is determined by the `CultureInfo.CurrentUICulture` at execution time. To eliminate the source of confusion, the APIs were marked as obsolete in ASP.NET Core 3.0 Preview 3. The APIs will be removed in a future release. + +For context, see [aspnet/AspNetCore#3324](https://github.com/aspnet/AspNetCore/issues/3324). For discussion, see [aspnet/AspNetCore#7756](https://github.com/aspnet/AspNetCore/issues/7756). + +#### Version introduced + +3.0 + +#### Old behavior + +Methods weren't marked as `Obsolete`. + +#### New behavior + +Methods are marked `Obsolete`. + +#### Reason for change + +The APIs represented a use case that isn't recommended. There was confusion about the design of localization. + +#### Recommended action + +The recommendation is to use `ResourceManagerStringLocalizer` instead. Let the culture be set by the `CurrentCulture`. If that isn't an option, create and use a copy of [ResourceManagerWithCultureStringLocalizer](https://github.com/aspnet/Localization/blob/43b974482c7b703c92085c6f68b3b23d8fe32720/src/Microsoft.Extensions.Localization/ResourceManagerWithCultureStringLocalizer.cs#L18). + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/logging-debuglogger-to-internal.md b/includes/core-changes/aspnetcore/3.0/logging-debuglogger-to-internal.md new file mode 100644 index 0000000000000..023c74e6d2f05 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/logging-debuglogger-to-internal.md @@ -0,0 +1,34 @@ +### Logging: DebugLogger class made internal + +Prior to ASP.NET Core 3.0, `DebugLogger`'s access modifier was `public`. In ASP.NET Core 3.0, the access modifier changed to `internal`. + +#### Version introduced + +3.0 + +#### Reason for change + +The change is being made to: + +* Enforce consistency with other logger implementations such as `ConsoleLogger`. +* Reduce the API surface. + +#### Recommended action + +Use the `ILoggingBuilder` extension method to enable debug logging. is also still `public` in the event the service needs to be registered manually. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/mvc-action-async-suffix-trimmed.md b/includes/core-changes/aspnetcore/3.0/mvc-action-async-suffix-trimmed.md new file mode 100644 index 0000000000000..f72c2462ae03e --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/mvc-action-async-suffix-trimmed.md @@ -0,0 +1,79 @@ +### MVC: Async suffix trimmed from controller action names + +As part of addressing [aspnet/AspNetCore#4849](https://github.com/aspnet/AspNetCore/issues/4849), ASP.NET Core MVC trims the suffix `Async` from action names by default. Starting with ASP.NET Core 3.0, this change affects both routing and link generation. + +#### Version introduced + +3.0 + +#### Old behavior + +Consider the following ASP.NET Core MVC controller: + +```csharp +public class ProductController : Controller +{ + public async IActionResult ListAsync() + { + var model = await DbContext.Products.ToListAsync(); + return View(model); + } +} +``` + +The action is routable via `Product/ListAsync`. Link generation requires specifying the `Async` suffix. For example: + +```cshtml +List +``` + +#### New behavior + +In ASP.NET Core 3.0, the action is routable via `Product/List`. Link generation code should omit the `Async` suffix. For example: + +```cshtml +List +``` + +This change doesn't affect names specified using the `[ActionName]` attribute. The new behavior can be disabled by setting `MvcOptions.SuppressAsyncSuffixInActionNames` to `false` in `Startup.ConfigureServices`: + +```csharp +services.AddMvc(options => +{ + options.SuppressAsyncSuffixInActionNames = false; +}); +``` + +#### Reason for change + +By convention, asynchronous .NET methods are suffixed with `Async`. However, when a method defines an MVC action, it's undesirable to use the `Async` suffix. + +#### Recommended action + +If your app depends on MVC actions preserving the name's `Async` suffix, choose one of the following mitigations: + +- Use the `[ActionName]` attribute to preserve the original name. +- Disable the renaming entirely by setting `MvcOptions.SuppressAsyncSuffixInActionNames` to `false` in `Startup.ConfigureServices`: + +```csharp +services.AddMvc(options => +{ + options.SuppressAsyncSuffixInActionNames = false; +}); +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/mvc-precompilation-tool-deprecated.md b/includes/core-changes/aspnetcore/3.0/mvc-precompilation-tool-deprecated.md new file mode 100644 index 0000000000000..c18880e7116c8 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/mvc-precompilation-tool-deprecated.md @@ -0,0 +1,41 @@ +### MVC: Precompilation tool deprecated + +In ASP.NET Core 1.1, the `Microsoft.AspNetCore.Mvc.Razor.ViewCompilation` (MVC precompilation tool) package was introduced to add support for publish-time compilation of Razor files (*.cshtml* files). In ASP.NET Core 2.1, the [Razor SDK](/aspnet/core/razor-pages/sdk?view=aspnetcore-2.1) was introduced to expand upon features of the precompilation tool. The Razor SDK added support for build- and publish-time compilation of Razor files. The SDK verifies the correctness of *.cshtml* files at build time while improving on app startup time. The Razor SDK is on by default, and no gesture is required to start using it. + +In ASP.NET Core 3.0, the ASP.NET Core 1.1-era MVC precompilation tool was removed. Earlier package versions will continue receiving important bug and security fixes in the patch release. + +#### Version introduced + +3.0 + +#### Old behavior + +The `Microsoft.AspNetCore.Mvc.Razor.ViewCompilation` package was used to pre-compile MVC Razor views. + +#### New behavior + +The Razor SDK natively supports this functionality. The `Microsoft.AspNetCore.Mvc.Razor.ViewCompilation` package is no longer updated. + +#### Reason for change + +The Razor SDK provides more functionality and verifies the correctness of *.cshtml* files at build time. The SDK also improves app startup time. + +#### Recommended action + +For users of ASP.NET Core 2.1 or later, update to use the native support for precompilation in the [Razor SDK](/aspnet/core/razor-pages/sdk?view=aspnetcore-3.0). If bugs or missing features prevent migration to the Razor SDK, open an issue at [aspnet/AspNetCore](https://github.com/aspnet/AspNetCore/issues). + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/mvc-pubternal-to-internal.md b/includes/core-changes/aspnetcore/3.0/mvc-pubternal-to-internal.md new file mode 100644 index 0000000000000..02566548084be --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/mvc-pubternal-to-internal.md @@ -0,0 +1,67 @@ +### MVC: "Pubternal" types changed to internal + +In ASP.NET Core 3.0, all "pubternal" types in MVC were updated to either be `public` in a supported namespace or `internal` as appropriate. + +#### Change description + +In ASP.NET Core, "pubternal" types are declared as `public` but reside in a `.Internal`-suffixed namespace. While these types are `public`, they have no support policy and are subject to breaking changes. Unfortunately, accidental use of these types has been common, resulting in breaking changes to these projects and limiting the ability to maintain the framework. + +#### Version introduced + +3.0 + +#### Old behavior + +Some types in MVC were `public` but in a `.Internal` namespace. These types had no support policy and were subject to breaking changes. + +#### New behavior + +All such types are updated either to be `public` in a supported namespace or marked as `internal`. + +#### Reason for change + +Accidental use of the "pubternal" types has been common, resulting in breaking changes to these projects and limiting the ability to maintain the framework. + +#### Recommended action + +If you're using types that have become truly `public` and have been moved into a new, supported namespace, update your references to match the new namespaces. + +If you're using types that have become marked as `internal`, you'll need to find an alternative. The previously "pubternal" types were never supported for public use. If there are specific types in these namespaces that are critical to your apps, file an issue at [aspnet/AspNetCore](https://github.com/aspnet/AspNetCore/issues). Considerations may be made for making the requested types `public`. + +#### Category + +ASP.NET Core + +#### Affected APIs + +This change includes types in the following namespaces: + +- `Microsoft.AspNetCore.Mvc.Cors.Internal` +- `Microsoft.AspNetCore.Mvc.DataAnnotations.Internal` +- `Microsoft.AspNetCore.Mvc.Formatters.Internal` +- `Microsoft.AspNetCore.Mvc.Formatters.Json.Internal` +- `Microsoft.AspNetCore.Mvc.Formatters.Xml.Internal` +- `Microsoft.AspNetCore.Mvc.Internal` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Internal` +- `Microsoft.AspNetCore.Mvc.Razor.Internal` +- `Microsoft.AspNetCore.Mvc.RazorPages.Internal` +- `Microsoft.AspNetCore.Mvc.TagHelpers.Internal` +- `Microsoft.AspNetCore.Mvc.ViewFeatures.Internal` + + diff --git a/includes/core-changes/aspnetcore/3.0/mvc-webapi-compat-shim-removed.md b/includes/core-changes/aspnetcore/3.0/mvc-webapi-compat-shim-removed.md new file mode 100644 index 0000000000000..2217511599205 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/mvc-webapi-compat-shim-removed.md @@ -0,0 +1,35 @@ +### MVC: Web API compatibility shim removed + +Starting with ASP.NET Core 3.0, the `Microsoft.AspNetCore.Mvc.WebApiCompatShim` package is no longer available. + +#### Change description + +The `Microsoft.AspNetCore.Mvc.WebApiCompatShim` (WebApiCompatShim) package provides partial compatibility in ASP.NET Core with ASP.NET 4.x Web API 2 to simplify migrating existing Web API implementations to ASP.NET Core. However, apps using the WebApiCompatShim don't benefit from the API-related features shipping in recent ASP.NET Core releases. Such features include improved Open API specification generation, standardized error handling, and client code generation. To better focus the API efforts in 3.0, WebApiCompatShim was removed. Existing apps using the WebApiCompatShim should migrate to the newer `[ApiController]` model. + +#### Version introduced + +3.0 + +#### Reason for change + +The Web API compatibility shim was a migration tool. It restricts user access to new functionality added in ASP.NET Core. + +#### Recommended action + +Remove usage of this shim and migrate directly to the similar functionality in ASP.NET Core itself. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md b/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md new file mode 100644 index 0000000000000..118786179088d --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md @@ -0,0 +1,198 @@ +### Obsolete Antiforgery, CORS, Diagnostics, MVC, and Routing APIs removed + +Obsolete members and compatibility switches in ASP.NET Core 2.2 were removed. + +#### Version introduced + +3.0 + +#### Reason for change + +Improvement of API surface over time. + +#### Recommended action + +While targeting .NET Core 2.2, follow the guidance in the obsolete build messages to adopt new APIs instead. + +#### Category + +ASP.NET Core + +#### Affected APIs + +The following types and members were marked as obsolete for ASP.NET Core 2.1 and 2.2: + +**Types** + +- +- +- +- +- +- +- +- +- +- + +**Constructors** + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +**Properties** + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +**Methods** + +- +- +- +- +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/razor-runtime-compilation-package.md b/includes/core-changes/aspnetcore/3.0/razor-runtime-compilation-package.md new file mode 100644 index 0000000000000..4c9738b083ee5 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/razor-runtime-compilation-package.md @@ -0,0 +1,55 @@ +### Razor: Runtime compilation moved to a package + +Support for runtime compilation of Razor views and Razor Pages has moved to a separate package. + +#### Version introduced + +3.0 + +#### Old behavior + +Runtime compilation is available without needing additional packages. + +#### New behavior + +The functionality has been moved to the `Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation` package. + +The following APIs were previously available in `Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions` to support runtime compilation. The APIs are now available via +`Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.MvcRazorRuntimeCompilationOptions`. + +- `RazorViewEngineOptions.FileProviders` -> `MvcRazorRuntimeCompilationOptions.FileProviders` +- `RazorViewEngineOptions.AdditionalCompilationReferences` -> `MvcRazorRuntimeCompilationOptions.AdditionalReferencePaths` + +In addition, `Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions.AllowRecompilingViewsOnFileChange` has been removed. Recompilation on file changes is enabled by default by referencing the `Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation` package. + +#### Reason for change + +This change was necessary to remove the ASP.NET Core shared framework dependency on Roslyn. + +#### Recommended action + +Apps that require runtime compilation or recompilation of Razor files should take the following steps: + +1. Add a reference to the `Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation` package. +1. Update the project's `Startup.ConfigureServices` method to include a call to `AddMvcRazorRuntimeCompilation`. For example, in `Startup.ConfigureServices`: + + ```csharp + services.AddMvc() + .AddMvcRazorRuntimeCompilation(); + ``` + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/session-obsolete-apis-removed.md b/includes/core-changes/aspnetcore/3.0/session-obsolete-apis-removed.md new file mode 100644 index 0000000000000..d303bacfa490d --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/session-obsolete-apis-removed.md @@ -0,0 +1,61 @@ +### Session state: Obsolete APIs removed + +Obsolete APIs for configuring session cookies were removed. For more information, see [aspnet/Announcements#257](https://github.com/aspnet/Announcements/issues/257). + +#### Version introduced + +3.0 + +#### Reason for change + +This change enforces consistency across APIs for configuring features that use cookies. + +#### Recommended action + +Migrate usage of the removed APIs to their newer replacements. Consider the following example in `Startup.ConfigureServices`: + +```csharp +public void ConfigureServices(ServiceCollection services) +{ + services.AddSession(options => + { + // Removed obsolete APIs + options.CookieName = "SessionCookie"; + options.CookieDomain = "contoso.com"; + options.CookiePath = "/"; + options.CookieHttpOnly = true; + options.CookieSecure = CookieSecurePolicy.Always; + + // new API + options.Cookie.Name = "SessionCookie"; + options.Cookie.Domain = "contoso.com"; + options.Cookie.Path = "/"; + options.Cookie.HttpOnly = true; + options.Cookie.SecurePolicy = CookieSecurePolicy.Always; + }); +} +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/sharedfx-all-framework-removed.md b/includes/core-changes/aspnetcore/3.0/sharedfx-all-framework-removed.md new file mode 100644 index 0000000000000..5c88be38a6e66 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/sharedfx-all-framework-removed.md @@ -0,0 +1,39 @@ +### Shared framework: Removed Microsoft.AspNetCore.All + +Starting in ASP.NET Core 3.0, the `Microsoft.AspNetCore.All` metapackage and the matching `Microsoft.AspNetCore.All` shared framework are no longer produced. This package is available in ASP.NET Core 2.2 and will continue to receive servicing updates in ASP.NET Core 2.1. + +#### Version introduced + +3.0 + +#### Old behavior + +Apps could use the `Microsoft.AspNetCore.All` metapackage to target the `Microsoft.AspNetCore.All` shared framework on .NET Core. + +#### New behavior + +.NET Core 3.0 doesn't include a `Microsoft.AspNetCore.All` shared framework. + +#### Reason for change + +The `Microsoft.AspNetCore.All` metapackage included a large number of external dependencies. + +#### Recommended action + +Migrate your project to use the `Microsoft.AspNetCore.App` framework. Components that were previously available in `Microsoft.AspNetCore.All` are still available on NuGet. Those components are now deployed with your app instead of being included in the shared framework. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/sharedfx-app-shared-framework-assemblies.md b/includes/core-changes/aspnetcore/3.0/sharedfx-app-shared-framework-assemblies.md new file mode 100644 index 0000000000000..b6706787d4324 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/sharedfx-app-shared-framework-assemblies.md @@ -0,0 +1,77 @@ +### Shared framework: Assemblies removed from Microsoft.AspNetCore.App + +Starting in ASP.NET Core 3.0, the ASP.NET Core shared framework (`Microsoft.AspNetCore.App`) only contains first-party assemblies that are fully developed, supported, and serviceable by Microsoft. + +#### Change description + +Think of the change as the redefining of boundaries for the ASP.NET Core "platform." The shared framework will be [source-buildable by anybody via GitHub](https://github.com/dotnet/source-build) and will continue to offer the existing benefits of .NET Core shared frameworks to your apps. Some benefits include smaller deployment size, centralized patching, and faster startup time. + +As part of the change, some notable breaking changes are introduced in `Microsoft.AspNetCore.App`. + +#### Version introduced + +3.0 + +#### Old behavior + +Projects referenced `Microsoft.AspNetCore.App` via a `` element in the project file. + +Additionally, `Microsoft.AspNetCore.App` contained the following subcomponents: + +- Json.NET (`Newtonsoft.Json`) +- Entity Framework Core (assemblies prefixed with `Microsoft.EntityFrameworkCore.`) +- Roslyn (`Microsoft.CodeAnalysis`) + +#### New behavior + +A reference to `Microsoft.AspNetCore.App` no longer requires a `` element in the project file. The .NET Core SDK supports a new element called +``, which replaces the use of ``. + +For more information, see [aspnet/AspNetCore#3612](https://github.com/aspnet/AspNetCore/issues/3612). + +Entity Framework Core ships as NuGet packages. This change aligns the shipping model with all other data access libraries on .NET. It provides Entity Framework Core the simplest path to continue innovating while supporting the various .NET platforms. The move of Entity Framework Core out of the shared framework has no impact on its status as a Microsoft-developed, supported, and serviceable library. The [.NET Core support policy](https://www.microsoft.com/net/platform/support-policy) continues to cover it. + +Json.NET and Entity Framework Core continue to work with ASP.NET Core. They won't, however, be included in the shared framework. + +For more information, see [The future of JSON in .NET Core 3.0](https://github.com/dotnet/announcements/issues/90). Also see [the complete list of binaries](https://github.com/aspnet/AspNetCore/issues/3755) removed from the shared framework. + +#### Reason for change + +This change simplifies the consumption of `Microsoft.AspNetCore.App` and reduces the duplication between NuGet packages and shared frameworks. + +For more information on the motivation for this change, see [this blog post](https://blogs.msdn.microsoft.com/webdev/2018/10/29/a-first-look-at-changes-coming-in-asp-net-core-3-0). + +#### Recommended action + +It won't be necessary for projects to consume assemblies in `Microsoft.AspNetCore.App` as NuGet packages. To simplify the targeting and usage of the ASP.NET Core shared framework, many NuGet packages shipped since ASP.NET Core 1.0 are no longer produced. The APIs those packages provide are still available to apps by using a `` to `Microsoft.AspNetCore.App`. Common API examples include Kestrel, MVC, and Razor. + +This change doesn't apply to all binaries referenced via `Microsoft.AspNetCore.App` in ASP.NET Core 2.x. Notable exceptions include: + +- `Microsoft.Extensions` libraries that continue to target .NET Standard will be available as NuGet packages (see https://github.com/aspnet/Extensions). +- APIs produced by the ASP.NET Core team that aren't part of `Microsoft.AspNetCore.App`. For example, the following components are available as NuGet packages: + - Entity Framework Core + - APIs that provide third-party integration + - Experimental features + - APIs with dependencies that couldn't [fulfill the requirements to be in the shared framework](https://github.com/aspnet/AspNetCore/blob/4e44e5bcbedd961cc0d4f6b846699c7c494f5597/docs/SharedFramework.md) +- Extensions to MVC that maintain support for Json.NET. An API will be provided as a NuGet package to support using Json.NET and MVC. +- The SignalR .NET client will continue to support .NET Standard and ship as a NuGet package. It's intended for use on many .NET runtimes, such as Xamarin and UWP. + +For more information, see [Stop producing packages for shared framework assemblies in 3.0](https://github.com/aspnet/AspNetCore/issues/3756). For discussion, see [aspnet/AspNetCore#3757](https://github.com/aspnet/AspNetCore/issues/3757). + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/signalr-hubconnection-methods-removed.md b/includes/core-changes/aspnetcore/3.0/signalr-hubconnection-methods-removed.md new file mode 100644 index 0000000000000..d942148847a0d --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/signalr-hubconnection-methods-removed.md @@ -0,0 +1,41 @@ +### SignalR: HubConnection ResetSendPing and ResetTimeout methods removed + +The `ResetSendPing` and `ResetTimeout` methods were removed from the SignalR `HubConnection` API. These methods were originally intended only for internal use but were made public in ASP.NET Core 2.2. These methods won't be available starting in the ASP.NET Core 3.0 Preview 4 release. For discussion, see [aspnet/AspNetCore#8543](https://github.com/aspnet/AspNetCore/issues/8543). + +#### Version introduced + +3.0 + +#### Old behavior + +APIs were available. + +#### New behavior + +APIs are removed. + +#### Reason for change + +These methods were originally intended only for internal use but were made public in ASP.NET Core 2.2. + +#### Recommended action + +Don't use these methods. + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/signalr-hubconnectioncontext-ctors.md b/includes/core-changes/aspnetcore/3.0/signalr-hubconnectioncontext-ctors.md new file mode 100644 index 0000000000000..3612bc85e7621 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/signalr-hubconnectioncontext-ctors.md @@ -0,0 +1,69 @@ +### SignalR: HubConnectionContext constructors changed + +SignalR's `HubConnectionContext` constructors changed to accept an options type, rather than multiple parameters, to future-proof adding options. This change replaces two constructors with a single constructor that accepts an options type. + +#### Version introduced + +3.0 + +#### Old behavior + +`HubConnectionContext` has two constructors: + +```csharp +public HubConnectionContext(ConnectionContext connectionContext, TimeSpan keepAliveInterval, ILoggerFactory loggerFactory); +public HubConnectionContext(ConnectionContext connectionContext, TimeSpan keepAliveInterval, ILoggerFactory loggerFactory, TimeSpan clientTimeoutInterval); +``` + +#### New behavior + +The two constructors were removed and replaced with one constructor: + +```csharp +public HubConnectionContext(ConnectionContext connectionContext, HubConnectionContextOptions contextOptions, ILoggerFactory loggerFactory) +``` + +#### Reason for change + +The new constructor uses a new options object. Consequently, the features of `HubConnectionContext` can be expanded in the future without making more constructors and breaking changes. + +#### Recommended action + +Instead of using the following constructor: + +```csharp +HubConnectionContext connectionContext = new HubConnectionContext( + connectionContext, + keepAliveInterval: TimeSpan.FromSeconds(15), + loggerFactory, + clientTimeoutInterval: TimeSpan.FromSeconds(15)); +``` + +Use the following constructor: + +```csharp +HubConnectionContextOptions contextOptions = new HubConnectionContextOptions() +{ + KeepAliveInterval = TimeSpan.FromSeconds(15), + ClientTimeoutInterval = TimeSpan.FromSeconds(15) +}; +HubConnectionContext connectionContext = new HubConnectionContext(connectionContext, contextOptions, loggerFactory); +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/signalr-js-client-package-name.md b/includes/core-changes/aspnetcore/3.0/signalr-js-client-package-name.md new file mode 100644 index 0000000000000..44e913b091187 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/signalr-js-client-package-name.md @@ -0,0 +1,43 @@ +### SignalR: JavaScript client package name changed + +In ASP.NET Core 3.0 Preview 7, the SignalR JavaScript client package name changed from `@aspnet/signalr` to `@microsoft/signalr`. The name change reflects the fact that SignalR is useful in more than just ASP.NET Core apps, thanks to the Azure SignalR Service. + +To react to this change, change references in your *package.json* files, `require` statements, and ECMAScript `import` statements. No API will change as part of this rename. + +For discussion, see [aspnet/AspNetCore#11637](https://github.com/aspnet/AspNetCore/issues/11637). + +#### Version introduced + +3.0 + +#### Old behavior + +The client package was named `@aspnet/signalr`. + +#### New behavior + +The client package is named `@microsoft/signalr`. + +#### Reason for change + +The name change clarifies that SignalR is useful beyond ASP.NET Core apps, thanks to the Azure SignalR Service. + +#### Recommended action + +Switch to the new package `@microsoft/signalr`. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/signalr-obsolete-apis.md b/includes/core-changes/aspnetcore/3.0/signalr-obsolete-apis.md new file mode 100644 index 0000000000000..76d5425395e4e --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/signalr-obsolete-apis.md @@ -0,0 +1,63 @@ +### SignalR: UseSignalR and UseConnections methods marked obsolete + +The methods `UseConnections` and `UseSignalR` and the classes `ConnectionsRouteBuilder` and `HubRouteBuilder` are marked as obsolete in ASP.NET Core 3.0. + +#### Version introduced + +3.0 + +#### Old behavior + +SignalR hub routing was configured using `UseSignalR` or `UseConnections`. + +#### New behavior + +The old way of configuring routing has been obsoleted and replaced with endpoint routing. + +#### Reason for change + +Middleware is being moved to the new endpoint routing system. The old way of adding middleware is being obsoleted. + +#### Recommended action + +Replace `UseSignalR` with `UseEndpoints`: + +**Old code:** + +```csharp +app.UseSignalR(routes => +{ + routes.MapHub("/path"); +}); +``` + +**New code:** + +```csharp +app.UseEndpoints(endpoints => +{ + endpoints.MapHub("/path"); +}); +``` + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/signalr-successhandshakedata-replaced.md b/includes/core-changes/aspnetcore/3.0/signalr-successhandshakedata-replaced.md new file mode 100644 index 0000000000000..6d809731e24b9 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/signalr-successhandshakedata-replaced.md @@ -0,0 +1,39 @@ +### SignalR: HandshakeProtocol.SuccessHandshakeData replaced + +The [HandshakeProtocol.SuccessHandshakeData](https://github.com/aspnet/AspNetCore/blob/c5b2bc0df2a0027832bf7d01dfb19ca39cd08ae6/src/SignalR/common/SignalR.Common/src/Protocol/HandshakeProtocol.cs#L27) field was removed and replaced with a helper method that generates a successful handshake response given a specific `IHubProtocol`. + +#### Version introduced + +3.0 + +#### Old behavior + +`HandshakeProtocol.SuccessHandshakeData` was a `public static ReadOnlyMemory` field. + +#### New behavior + +`HandshakeProtocol.SuccessHandshakeData` has been replaced by a `static` `GetSuccessfulHandshake(IHubProtocol protocol)` method that returns a `ReadOnlyMemory` based on the specified protocol. + +#### Reason for change + +Additional fields were added to the handshake _response_ that are non-constant and change depending on the selected protocol. + +#### Recommended action + +None. This type isn't designed for use from user code. It's `public`, so it can be shared between the SignalR server and client. It may also be used by customer SignalR clients written in .NET. **Users** of SignalR shouldn't be affected by this change. + +#### Category + +ASP.NET Core + +#### Affected APIs + + + + diff --git a/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-fallback.md b/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-fallback.md new file mode 100644 index 0000000000000..9a823b8f44883 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-fallback.md @@ -0,0 +1,39 @@ +### SPAs: SpaServices and NodeServices no longer fall back to console logger + + and won't display console logs unless logging is configured. + +#### Version introduced + +3.0 + +#### Old behavior + +`Microsoft.AspNetCore.SpaServices` and `Microsoft.AspNetCore.NodeServices` used to automatically create a console logger when logging isn't configured. + +#### New behavior + +`Microsoft.AspNetCore.SpaServices` and `Microsoft.AspNetCore.NodeServices` won't display console logs unless logging is configured. + +#### Reason for change + +There's a need to align with how other ASP.NET Core packages implement logging. + +#### Recommended action + +If the old behavior is required, to configure console logging, add `services.AddLogging(builder => builder.AddConsole())` to your `Setup.ConfigureServices` method. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-obsolete.md b/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-obsolete.md new file mode 100644 index 0000000000000..8c8e1f54e56db --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/spas-spaservices-nodeservices-obsolete.md @@ -0,0 +1,110 @@ +### SPAs: SpaServices and NodeServices marked obsolete + +The contents of the following NuGet packages have all been unnecessary since ASP.NET Core 2.1. Consequently, the following packages are being marked as obsolete: + +- [Microsoft.AspNetCore.SpaServices](https://www.nuget.org/packages/Microsoft.AspNetCore.SpaServices/) +- [Microsoft.AspNetCore.NodeServices](https://www.nuget.org/packages/Microsoft.AspNetCore.NodeServices/) + +For the same reason, the following npm modules are being marked as deprecated: + +- [aspnet-angular](https://www.npmjs.com/package/aspnet-angular) +- [aspnet-prerendering](https://www.npmjs.com/package/aspnet-prerendering) +- [aspnet-webpack](https://www.npmjs.com/package/aspnet-webpack) +- [aspnet-webpack-react](https://www.npmjs.com/package/aspnet-webpack-react) +- [domain-task](https://www.npmjs.com/package/domain-task) + +The preceding packages and npm modules will later be removed in .NET 5. + +#### Version introduced + +3.0 + +#### Old behavior + +The deprecated packages and npm modules were intended to integrate ASP.NET Core with various Single-Page App (SPA) frameworks. Such frameworks include Angular, React, and React with Redux. + +#### New behavior + +A new integration mechanism exists in the [Microsoft.AspNetCore.SpaServices.Extensions](https://www.nuget.org/packages/Microsoft.AspNetCore.SpaServices.Extensions/) NuGet package. The package remains the basis of the Angular and React project templates since ASP.NET Core 2.1. + +#### Reason for change + +ASP.NET Core supports integration with various Single-Page App (SPA) frameworks, including Angular, React, and React with Redux. Initially, integration with these frameworks was accomplished with ASP.NET Core-specific components that handled scenarios like server-side prerendering and integration with Webpack. As time went on, industry standards changed. Each of the SPA frameworks released their own standard command-line interfaces. For example, Angular CLI and create-react-app. + +When ASP.NET Core 2.1 was released in May 2018, the team responded to the change in standards. A newer and simpler way to integrate with the SPA frameworks' own toolchains was provided. The new integration mechanism exists in the package `Microsoft.AspNetCore.SpaServices.Extensions` and remains the basis of the Angular and React project templates since ASP.NET Core 2.1. + +To clarify that the older ASP.NET Core-specific components are irrelevant and not recommended: + +- The pre-2.1 integration mechanism is marked as obsolete. +- The supporting npm packages are marked as deprecated. + +#### Recommended action + +If you're using these packages, update your apps to use the functionality: + +- In the `Microsoft.AspNetCore.SpaServices.Extensions` package. +- Provided by the SPA frameworks you're using + +To enable features like server-side prerendering and hot module reload, see the documentation for the corresponding SPA framework. The functionality in `Microsoft.AspNetCore.SpaServices.Extensions` is *not* obsolete and will continue to be supported. + +#### Category + +ASP.NET Core + +#### Affected APIs + +- +- + +- +- +- +- +- +- +- +- +- +- + +- +- +- +- +- +- +- + +- +- + + diff --git a/includes/core-changes/aspnetcore/3.0/targetfx-netfx-tfm-support.md b/includes/core-changes/aspnetcore/3.0/targetfx-netfx-tfm-support.md new file mode 100644 index 0000000000000..4ae40564ca019 --- /dev/null +++ b/includes/core-changes/aspnetcore/3.0/targetfx-netfx-tfm-support.md @@ -0,0 +1,50 @@ +### Target framework: .NET Framework support dropped + +Starting with ASP.NET Core 3.0, .NET Framework is an unsupported target framework. + +#### Change description + +.NET Framework 4.8 is the last major version of .NET Framework. New ASP.NET Core apps should be built on .NET Core. Starting with the .NET Core 3.0 release, you can think of ASP.NET Core 3.0 as being part of .NET Core. + +Customers using ASP.NET Core with .NET Framework can continue in a fully supported fashion using the [2.1 LTS release](https://www.microsoft.com/net/download/dotnet-core/2.1). Support and servicing for 2.1 continues until at least August 21, 2021. This date is three years after declaration of the LTS release per the [.NET Support Policy](https://www.microsoft.com/net/platform/support-policy). Support for ASP.NET Core 2.1 packages **on .NET Framework** will extend indefinitely, similar to the [servicing policy for other package-based ASP.NET frameworks](https://dotnet.microsoft.com/platform/support/policy/aspnet). + +For more information about porting from .NET Framework to .NET Core, see [Porting to .NET Core](~/docs/core/porting/index.md). + +`Microsoft.Extensions` packages (such as logging, dependency injection, and configuration) and Entity Framework Core aren't affected. They'll continue to support .NET Standard. + +For more information on the motivation for this change, see [the original blog post](https://blogs.msdn.microsoft.com/webdev/2018/10/29/a-first-look-at-changes-coming-in-asp-net-core-3-0). + +#### Version introduced + +3.0 + +#### Old behavior + +ASP.NET Core apps could run on either .NET Core or .NET Framework. + +#### New behavior + +ASP.NET Core apps can only be run on .NET Core. + +#### Recommended action + +Take one of the following actions: + +- Keep your app on ASP.NET Core 2.1. +- Migrate your app and dependencies to .NET Core. + +#### Category + +ASP.NET Core + +#### Affected APIs + +None + + diff --git a/includes/core-changes/categoryselector.md b/includes/core-changes/categoryselector.md index 7228dfc1450f7..c2068a1fc209f 100644 --- a/includes/core-changes/categoryselector.md +++ b/includes/core-changes/categoryselector.md @@ -1,13 +1,13 @@ > [!div class="op_single_selector"] > +> - [ASP.NET Core](~/docs/core/compatibility/aspnetcore.md) > - [CoreFx](~/docs/core/compatibility/corefx.md) > - [Cryptography](~/docs/core/compatibility/cryptography.md) +> - [EF Core](/ef/core/what-is-new/ef-core-3.0/breaking-changes) > - [Globalization](~/docs/core/compatibility/globalization.md) > - [Networking](~/docs/core/compatibility/networking.md) > - [Visual Basic](~/docs/core/compatibility/visualbasic.md) > - [Windows Forms](~/docs/core/compatibility/winforms.md) -> - [ASP.NET Core (on GitHub)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+is%3Aopen+label%3A%22Breaking+change%22+label%3A3.0.0) -> - [EF Core](/ef/core/what-is-new/ef-core-3.0/breaking-changes)