Runtime Package Store guidance where not available by default

[leecow]

Overview

.NET Core 2.0 includes a new package cache feature, called the Runtime Package Store (RPS), which is installed by the .NET Core 2.0 SDK. The Runtime Package Store enables creating a precompiled cache of common libraries which can be centrally provisioned and not deployed to every application reducing deployment size and startup times. Currently, the RPS that ships with the .NET Core 2.0 SDK contains packages common to ASP.NET Core applications. Design details can be seen in dotnet/designs/issues/8.

Goal

Provide clear, and clean, guidance for Red Hat customers to understand the Runtime Package Store (RPS) and easily executable steps needed for applicable scenarios to enable ASP.NET Core application deployment.

The long term solution is to enable clean build-from-source behavior from the applicable components obviating the need for these additional steps.

Issue

The default ASP.NET targets included with the Microsoft.NET.Sdk.Web SDK include target manifests. As a consequence, dotnet publish of an ASP.NET application will result in a published application that contains only the application and its assets, and not ASP.NET itself. When an ASP.NET published application gets deployed, one should make sure that the target environment has ASP.NET installed, as the presence of .NET Core alone will not be sufficient.

The primary issue is the required ASP.NET packages that are contained in the Runtime Package Store cannot be built from source at this time and therefore cannot be distributed by Red Hat. The default .NET Core 2.0 installation on RHEL will not include the RPS adn deployment of ASP.NET Core applications will fail.

The issue and proposed solution described below are discussed in detail at dotnet/aspnetcore#2033 (comment). Additional background available in the following issues.

• aspnet/Coherence-Signed/issues/428
• aspnet/MetaPackages/issues/149

Work Around 1

**Configure the application to not rely on the Runtime Package Store

This is the recommended approach on RHEL.

If the application needs to be published to such an environment that doesn't include ASP.NET, it is possible to opt out of the implicit store by specifying a PublishWithAspNetCoreTargetManifest flag set to false in the project file, as you can see in the following example.

  <PropertyGroup>
    <PublishWithAspNetCoreTargetManifest>false</PublishWithAspNetCoreTargetManifest>
  </PropertyGroup>

Utilizing this setting will increase the size of the application deployment as all files referenced by the AspNetCore Manifest will included.

The ASP.NET runtime package store will be installed as part of the SDK packages distributed by Microsoft, and will also be available as a separate download so that any deployment environment can be prepared to receive published ASP.NET applications.

Work Around 2

Install the Runtime Package Store on target environments

Microsoft builds RPMs for the Runtime Package Store. These packages will be published on a Microsoft product feed (https://packages.microsoft.com/) and accessible via yum install (dotnet/aspnetcore#2033).

The proposed solution can be tested now using the Preview 2 release though Preview 2 will need to be manually downloaded and installed as it is not available through the SCL.

Download the rpm and install the Runtime Package Store

Running the following script will download and install the Runtime Package Store to /opt/rh/rh-dotnet20/root/usr/lib64/dotnet.

curl -sSL -o aspnetcore-store-2.0.0-rh.rhel.7-x64.rpm https://dotnetcli.blob.core.windows.net/dotnet/Sdk/2.0.0/gpg-signed/aspnetcore-store-2.0.0-rh.rhel.7-x64.rpm
sudo yum -ivh aspnetcore-store-2.0.0-rh.rhel-x64.rpm

/cc @richlander @DamianEdwards @omajid @tmds @Petermarcu

[omajid]

/cc @DonSchenck

[omajid]

Currently, the store that ships with the .NET Core 2.0 SDK contains ASP.NET Core packages

I believe it also includes EF Core packages as well as many other packages.

[leecow]

Updates based on comments:

• PublishWithAspNetCoreTargetManifest details included as an option
• Made reference to RPS contents more generic: "... packages common to ASP.NET Core applications ..."
• Fixed package name in yum steps

[natemcmaster]

Even with the improvements to the error message that we made for 2.0.0 RTM, I'm still seeing users frequently hitting this issue. Do we have plans to further address this?

Linked issues

• Microsoft.ApplicationInsights.AspNetCore.dll is missing  aspnet/aspnet-docker#286
• Application runs in microsoft/dotnet:2.0-sdk container crashes in microsoft/dotnet:2.0-runtime dotnet-docker#283
• Cannot run dotnet 2.0.0 project with runtime docker image. dotnet-docker#279
• https://github.com/dotnet/cli/issues/7680
• https://github.com/dotnet/cli/issues/6516
• https://stackoverflow.com/questions/45377365/an-assembly-specified-in-the-application-dependencies-manifest-was-not-found
• https://stackoverflow.com/questions/45272458/self-contained-deployment-net-core-app-in-ubuntu
• https://stackoverflow.com/questions/45720022/missing-runtime-store-error-on-linux-with-net-core-2-0-runtime-only

[Petermarcu]

I wouldn't find that error message very helpful. What it really needs to say is, "You've targeted ASP.NET and ASP.NET isn't installed. Go here to install it."

Here is the example of what it is today. How would I translate that into, I'm missing the asp.net platform that I targeted?

Error:
An assembly specified in the application dependencies manifest (*****.Web.deps.json) was not found:
package: 'Microsoft.ApplicationInsights.AspNetCore', version: '2.1.1'
path: 'lib/netstandard1.6/Microsoft.ApplicationInsights.AspNetCore.dll'
This assembly was expected to be in the local runtime store as the application was published using the following target manifest files:
aspnetcore-store-2.0.0-linux-x64.xml;aspnetcore-store-2.0.0-osx-x64.xml;aspnetcore-store-2.0.0-win7-x64.xml;aspnetcore-store-2.0.0-win7-x86.xml

[natemcmaster]

@Petermarcu so, assuming we want this improvement, who do we make responsible to fix this? The error itself is issued by corehost (cc @steveharter @ramarag), but the instructions for installing the runtime store are owned by aspnetcore (cc @JunTaoLuo @Eilon). Today, I don't think there is a way for a runtime store author to set a fwlink or message at build-time that would appear at runtime-time on a different box.

[Petermarcu]

We should work together to make sure enough information is persisted in the resulting application to give a good message. I think that will be a combination of more information being provided in the xml that is used to trim the application that then gets written to the deps file and then read.

Honestly, though I think we need to finish some higher level conversations about the future of the runtime store before we optimize this. It would be wasted investment if we start representing asp.net as something other than an optimzed collection of nuget packages.

[Petermarcu]

@steveharter as FYI

[JunTaoLuo]

Improving the error is one thing but can we also add some documentation and links for this as well, especially for acquisition?

The most common questions I see arise out of people bypassing the sdk and trying to install just the runtime. That will no longer work. However the documentation at https://www.microsoft.com/net/download/core#/runtime do not reflect this. The link for the runtime installer does not make it clear that the runtime store is required for aspnet apps and it does not tell users where to get it. We should also add links to the (temporarily missing) dotnet-hosting-2.0.0 linux server hosting installers which include the runtime and the runtime store.

[JunTaoLuo]

Filed https://github.com/dotnet/core-setup/issues/3276 to track work to improve error message.