ASP.NET Core Shared Framework ("runtime")

[glennc]

This is a tracking issue for delivering ASP.NET Core and related libraries as a cohesive set that are consumed and behave like a .NET platform, as opposed to standard NuGet packages.

Packages (state of the world as of 2.0)

ASP.NET Core (and by extension, Entity Framework Core and the Microsoft.Extensions.* libraries) is designed, built, and deployed as a series of .NET Standard NuGet package libraries that together form the larger framework. The framework, in turn, runs on various .NET platforms, including .NET Framework, .NET Core, and Mono. Entity Framework Core and the various Microsoft.Extensions.* libraries also run and are supported on other .NET platforms like UWP and Xamarin.

There are aspects of working with such a large set of packages however that are less than desirable to the developer experience. As such, some features were built for 2.0 to mitigate some of the issues.

This applies to all packages with the Microsoft.AspNetCore, Microsoft.EntityFrameworkCore, and Microsoft.Extensions prefixes, as well as their dependencies, which include both first-party (Microsoft) and third-party libraries.

Benefits of packages

• Can be consumed on any .NET Standard compliant platform
• Enforcing clear layering of dependencies
• Enables "pay as you go" by only having to depend on APIs used
• Reduces dependency graph for library authors, as they can depend only on what they need.
• Enables simple delivery of updates to individual framework components when necessary, e.g. early flighting of upcoming fixes

Issues with packages

• Runtime assets are deployed with the application resulting in large application size, slower build time, and duplication on servers running multiple apps using same ASP.NET Core version
• Can be difficult to know which API is in which package when using a large framework like ASP.NET Core
• Requires rebuild and deployment of application to stay supported after patches released (no machine-wide roll forward)
• Runtime assets are not optimized for the target platform, e.g. CrossGen, resulting in slower application startup time
• Packages must first be "restored" to the configured package install location, which can be slow and error prone on high-latency/low-bandwidth connections
• Package layout for first-time restore, design/build time, and runtime can result in duplication on developer machines
• Individual framework components can be silently lifted to new versions via transitive dependencies, resulting in the user using a non-supported combination without any indication

Runtime Store

.NET Core 2.0 introduced the Runtime Store as a way to install runtime assets from NuGet packages into a global location. The assets are optimized for the current platform (via CrossGen), and at runtime the host will load assets from the runtime store in the case that application requires the asset but doesn't have it in its bin folder. Assets expected to be in the runtime store of the machine an application is being published to can be excluded from the publish output of the application (its bin) by passing a manifest to the publish command.

ASP.NET Core 2.0 shipped the entire closure of its libraries, up to and including third-party dependencies, in the runtime store, and the meta-package used by ASP.NET Core 2.0 applications by default (Microsoft.AspNetCore.All) configures the publish command to exclude these assets by default. Thus, all ASP.NET Core 2.0 projects are published without the ASP.NET Core libraries by default, meaning they will only run on a server where the runtime store has previously been installed.

Benefits of the runtime store

• Runtime assets are optimized for current platform (in both developer and production) resulting in improved application startup time
• Framework libraries are not deployed with ASP.NET Core applications (when targeting .NET Core), drastically reducing their size on disk
• Libraries that need to be loaded as part of environmental "light-up" features (like Application Insights) can be installed in the runtime store and loaded using the hosts's "Additional deps" feature

Issues with the runtime store

• The exact versions of libraries in the runtime store must be present for applications depending on them to run. This means patches to libraries in the store can't be applied globally, apps must be updated manually and redployed.
• Because of the above, the runtime store will grow larger over time (2.0.1, 2.0.2, 2.0.3, etc.), as more patches and updates to the libraries it contains are added. Previous versions can't be removed as applications requiring the earlier versions would not run without them.
• Removing items from the runtime store is difficult on servers where it isn't clear what dependencies and versions are used by the applications on that server, e.g. hosting providers, including Azure App Service.
• The folder layout of the runtime store makes updating it with new versions while applications are running difficult, as a specific delta (additive) layout must be produced so that it can be copied to the store root directory. This affects platforms like Azure App Service. Producing such a layout is somewhat inconvenient.

ASP.NET Core Shared Framework

To address the issues of using the runtime store to deliver the framework assets, the .NET Core host & SDK will be updated to support ASP.NET Core being a "shared framework" with similar semantics to the existing shared framework, Microsoft.NETCore.App.

Note that the .NET Core host will continue to support resolution of other libraries from the runtime store and the SDK will continue to support trimming on publish by way of a target manifest, but ASP.NET Core will not use these mechanisms moving forward.

Requirements

• Existing ASP.NET Core 2.0 projects should require no updates (other than increasing the version of the referenced Microsoft.AspNetCore.All package) to run from the new shared framework instead of the runtime store
• Existing published ASP.NET Core 2.0.x applications must be able to run on machines that only have a compatible shared framework installed (no runtime store), aka roll forward from runtime store to shared framework
  • This will enable us to deprecate our use of the runtime store and thus remove it from our installers and environments like Azure App Service
  • This requirements is gated on a 2.0.x release being named LTS for the 2.x lifecycle
• Shared frameworks can inherit from each other, e.g. Microsoft.AspNetCore.All inherits from Microsoft.NETCore.App, such that duplicate assets can be avoided and not require servicing in multiple shared frameworks

Benefits of a shared framework

• Single, flat folder per version allowing for easy construction and side-by-side deployment
• Auto roll-forward semantics for patch releases allowing for easy global updates
• Fallback roll-forward semantics for minor releases (roll onto 2.3 if app targets 2.0, 2.1, or 2.2 and the exact version is not present) allowing for removal of older, unsupported versions with minimal impact

Version "train" locking

To address the issue of framework components delivered in packages being silently lifted to newer versions, out of step with the rest of the framework and thus untested and unsupported, the Microsoft.AspNetCore.All meta-package will be changed to specify package dependency ranges, that ensure that only the excact version specified for each dependency is allowed. Any other dependency that attempts to lift a version for a component beyond what is specified in the meta-package will result in a NuGet warning, which the Microsoft.NET.Sdk will elevate to an error by default. Users will be able to suppress the error manually if they wish to lift the dependency anyway, but at that point they would be considered unsupported.

[guardrex]

Regarding the runtime store feature whereby additional packages (outside of those in Microsoft.AspNetCore.All) can be deployed in advance and apps published against a manifest of those additional packages: Is that feature going to survive?

[EDIT] Just found out that [@]DamianEdwards provided an overview of the changes on the Standup :point_right: https://youtu.be/rnFrOauYrkY?t=47m44s

[DamianEdwards]

@guardrex yes, there is no plan to remove the runtime store functionality from the dotnet host or CLI, just its use by ASP.NET Core to deliver the entire framework.

[johnkors]

Maybe a https://github.com/dotnet/announcements is in order..?

I was considering creating scripts for installing aspnet core (all) into the runtime store on our frontend servers, but after acceidentally finding this issue, it looks like that would be a waste of time?

Looks like the install scripts already support the new AspNet Core Shared Runtime : https://github.com/dotnet/cli/pull/8333

[DamianEdwards]

@johnkors I'll add an announcement for this as it pertains to the upcoming 2.1 releases

[dasMulli]

Is there any plan to make the .app package a flat package like microsoft.netcore.app? That would have the benefit of making the build really fast and existing conflict resolution infrastructure of the SDK should already contain the means to trim otherwise acquired individual packages out of the dependency tree (provided the necessary conflict resolution info is provided by the metapackage).

[DamianEdwards]

Closing this as feature work for this is complete.