Edit

Share via

Microsoft.AspNetCore.App for ASP.NET Core

  • Article

Note

This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.

Warning

This version of ASP.NET Core is no longer supported. For more information, see the .NET and .NET Core Support Policy. For the current release, see the .NET 9 version of this article.

Important

This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

For the current release, see the .NET 9 version of this article.

The ASP.NET Core shared framework (Microsoft.AspNetCore.App) contains assemblies that are developed and supported by Microsoft. Microsoft.AspNetCore.App is installed when the .NET Core 3.0 or later SDK is installed. The shared framework is the set of assemblies (.dll files) that are installed on the machine and includes a runtime component and a targeting pack. For more information, see The shared framework.

  • Projects that target the Microsoft.NET.Sdk.Web SDK implicitly reference the Microsoft.AspNetCore.App framework.

No additional references are required for these projects:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>
    ...
</Project>

The ASP.NET Core shared framework:

  • Doesn't include third-party dependencies.
  • Includes all supported packages by the ASP.NET Core team.

This feature requires ASP.NET Core 2.x targeting .NET Core 2.x.

The Microsoft.AspNetCore.App metapackage for ASP.NET Core:

  • Does not include third-party dependencies except for Json.NET, Remotion.Linq, and IX-Async. These 3rd-party dependencies are deemed necessary to ensure the major frameworks features function.
  • Includes all supported packages by the ASP.NET Core team except those that contain third-party dependencies (other than those previously mentioned).
  • Includes all supported packages by the Entity Framework Core team except those that contain third-party dependencies (other than those previously mentioned).

All the features of ASP.NET Core 2.x and Entity Framework Core 2.x are included in the Microsoft.AspNetCore.App package. The default project templates targeting ASP.NET Core 2.x use this package. We recommend applications targeting ASP.NET Core 2.x and Entity Framework Core 2.x use the Microsoft.AspNetCore.App package.

The version number of the Microsoft.AspNetCore.App metapackage represents the minimum ASP.NET Core version and Entity Framework Core version.

Using the Microsoft.AspNetCore.App metapackage provides version restrictions that protect your app:

  • If a package is included that has a transitive (not direct) dependency on a package in Microsoft.AspNetCore.App, and those version numbers differ, NuGet will generate an error.
  • Other packages added to your app cannot change the version of packages included in Microsoft.AspNetCore.App.
  • Version consistency ensures a reliable experience. Microsoft.AspNetCore.App was designed to prevent untested version combinations of related bits being used together in the same app.

Applications that use the Microsoft.AspNetCore.App metapackage automatically take advantage of the ASP.NET Core shared framework. When you use the Microsoft.AspNetCore.App metapackage, no assets from the referenced ASP.NET Core NuGet packages are deployed with the application—the ASP.NET Core shared framework contains these assets. The assets in the shared framework are precompiled to improve application startup time. For more information, see The shared framework.

The following project file references the Microsoft.AspNetCore.App metapackage for ASP.NET Core and represents a typical ASP.NET Core 2.2 template:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

The preceding markup represents a typical ASP.NET Core 2.x template. It doesn't specify a version number for the Microsoft.AspNetCore.App package reference. When the version is not specified, an implicit version is specified by the SDK, that is, Microsoft.NET.Sdk.Web. We recommend relying on the implicit version specified by the SDK and not explicitly setting the version number on the package reference. If you have questions on this approach, leave a GitHub comment at the Discussion for the Microsoft.AspNetCore.App implicit version.

The implicit version is set to major.minor.0 for portable apps. The shared framework roll-forward mechanism will run the app on the latest compatible version among the installed shared frameworks. To guarantee the same version is used in development, test, and production, ensure the same version of the shared framework is installed in all environments. For self contained apps, the implicit version number is set to the major.minor.patch of the shared framework bundled in the installed SDK.

Specifying a version number on the Microsoft.AspNetCore.App reference does not guarantee that version of the shared framework will be chosen. For example, suppose version "2.2.1" is specified, but "2.2.3" is installed. In that case, the app will use "2.2.3". Although not recommended, you can disable roll forward (patch and/or minor). For more information regarding dotnet host roll-forward and how to configure its behavior, see dotnet host roll forward.

<Project Sdk must be set to Microsoft.NET.Sdk.Web to use the implicit version Microsoft.AspNetCore.App. When <Project Sdk="Microsoft.NET.Sdk"> (without the trailing .Web) is used:

  • The following warning is generated:

    Warning NU1604: Project dependency Microsoft.AspNetCore.App does not contain an inclusive lower bound. Include a lower bound in the dependency version to ensure consistent restore results.

  • This is a known issue with the .NET Core 2.1 SDK.

Update ASP.NET Core

The Microsoft.AspNetCore.App metapackage isn't a traditional package that's updated from NuGet. Similar to Microsoft.NETCore.App, Microsoft.AspNetCore.App represents a shared runtime, which has special versioning semantics handled outside of NuGet. For more information, see Packages, metapackages and frameworks.

To update ASP.NET Core:

  • On development machines and build servers: Download and install the .NET Core SDK.
  • On deployment servers: Download and install the .NET Core runtime.

Applications will roll forward to the latest installed version on application restart. It's not necessary to update the Microsoft.AspNetCore.App version number in the project file. For more information, see Framework-dependent apps roll forward.

If your application previously used Microsoft.AspNetCore.All, see Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App.