Breaking changes to Microsoft.AspNetCore.App in 3.0

[SteveSandersonMS]

Breaking changes to Microsoft.AspNetCore.App in 3.0

Starting in 3.0, the ASP.NET Core shared framework (Microsoft.AspNetCore.App) will only contain first-party assemblies that are fully developed, supported, and serviceable by Microsoft. You can think of this as constituting the ASP.NET Core “platform.” It will be fully source buildable by anybody via GitHub and will continue to bring all the existing benefits of .NET Core shared frameworks to your applications moving forward (smaller deployment size, centralized patching, faster startup time, etc.).

As part of this change, some notable breaking changes will be made in Microsoft.AspNetCore.App 3.0.

Version introduced

3.0

Old behavior

Prior to 3.0, projects referenced Microsoft.AspNetCore.App via a <PackageReference> in their project file.

Additionally, Microsoft.AspNetCore.App contained the following sub-components:

• Json.NET (Newtonsoft.Json)
• Entity Framework Core (Microsoft.EntityFrameworkCore.*)
• Microsoft.CodeAnalysis (Roslyn)

New behavior

Starting in ASP.NET Core 3.0, references to Microsoft.AspNetCore.App will no longer be a <PackageReference> element in the project file. The .NET Core SDK will support a new item called
<FrameworkReference> which will replace the use of PackageReference. Changes to support this new item type are already under way.

See aspnet/AspNetCore#3612 for more details.

Entity Framework Core will ship as “pure” NuGet packages in 3.0. This makes its shipping model the same as all other data access libraries on .NET, and allows it the simplest path to continue innovation while providing support for all the various .NET platforms customers enjoy it on today. Note, Entity Framework Core moving out of the shared framework has no impact on its status as a Microsoft developed, supported, and serviceable library, and it will continue to be covered by the .NET Core support policy.

Json.NET or Entity Framework Core will continue to work with ASP.NET Core, but they will not be "in the box" with the shared framework.

See "The future of JSON in .NET Core 3.0" for details on our plans to remove the dependency from ASP.NET Core to Json.NET and replace it with high-performance JSON APIs.

We have separately posted a complete list of exact binaries that are being removed. This list may fluctuate as we continue to work on ASP.NET Core 3.0.

Reason for change

This change simplifies the consumption of Microsoft.AspNetCore.App and reduces the duplication between NuGet packages and shared frameworks.

See the blog post from earlier today for more details on the motivation for this change.

Recommended action

As result these changes, it will not be necessary for projects to consume assemblies in Microsoft.AspNetCore.App as NuGet packages. To simplify the way in which consumers target and use the ASP.NET Core shared framework, we will stop producing many of the NuGet packages that we have been shipping since ASP.NET Core 1.0. The API those packages provide are still available to apps by using a <FrameworkReference> to Microsoft.AspNetCore.App. This includes commonly referenced API, such as Kestrel, Mvc, Razor, and others.

This will not apply to all binaries that are pulled in via Microsoft.AspNetCore.App in 2.x. Notable exceptions include:

• Microsoft.Extensions libraries which continue to target .NET Standard will be available as NuGet packages (see https://github.com/aspnet/Extensions)
• API produced by the ASP.NET Core team which is not part of Microsoft.AspNetCore.App. For example, Entity Framework Core, API which provides 3rd party integration, experimental features, or API which has dependencies that could not satisy the requirements to be in the shared framework will ship as NuGet packages and not in the shared framework.
• Extensions to MVC that maintain support for Json.NET. We intend to provide API as a NuGet package to support using Json.NET and MVC.
• The SignalR .NET client will continue to support .NET Standard and ship as NuGet package because it is intended for use on many .NET runtimes, like Xamarin and UWP.

For more details, see the complete list of packages that will only be obsolete in favor of <FrameworkReference>. This list may fluctuate as we continue to work on ASP.NET Core 3.0.

You can use aspnet/AspNetCore#3757 for discussion.

Category

• ASP.NET Core

Affected APIs

• Json.NET (Newtonsoft.Json)
• Entity Framework Core (Microsoft.EntityFrameworkCore.*)
• Microsoft.CodeAnalysis (Roslyn)

---

Issue metadata

• Issue type: breaking-change