Sdk: Runtime Package Store

Created on 15 Jun 2017 · 14Comments · Source: dotnet/sdk

Runtime Package Store

Starting with .NET Core 2.0, it's possible to package and deploy applications against a known set of packages that exist on the target environment. The benefits in doing so are smaller deployments, lower disk space usage, and in some cases improved startup performance.

This feature is implemented by a runtime package store, which is a location on disk where packages are stored, and that the runtime can find, access, and use. That location is a store directory, next to the dotnet host. Under this directory, there are subdirectories for target frameworks, under which the package store follows a NuGet layout.

The second part of the implementation is a "target manifest", which is a list of packages that compose a runtime package store, and that developers can target when publishing their application. The target manifest is typically provided by the owner of the targeted production environment.

The feature is also used implicitly by ASP.NET applications: the set of packages composing the ASP.NET Web framework is installed as part of the setup packages authored by Microsoft. When publishing an ASP.NET application, the published application is trimmed to only include the application's packages, and not the framework's packages.

Goals

Smaller deployments
Lower disk space usage
Faster startup times

Publishing an application against a target manifest

If you have a target manifest file on disk, you can specify it when publishing your app with the dotnet publish command:

dotnet publish --manifest path/to/the/target-manifest.xml

The resulting published application should only be deployed to an environment that has the packages described in the target manifest. Failing to do so would result in the application not starting.

It's possible to specify multiple target manifests when publishing an application. The application will then be trimmed for the union of packages specified in those target manifests.

Specifying a target manifest in the project file

Instead of specifying a target manifest in a dotnet publish command, it's possible to specify the manifest or manifests to use in the project file as a semicolon-separated list of paths under a TargetManifestFiles tag.

<PropertyGroup>
  <TargetManifestFiles>path/to/the/target-manifest.xml</TargetManifestFiles>
</PropertyGroup>

This should only be done when the target environment for the application is well-known.

A different case would be an open-source project: the users of the project will likely deploy to a variety of different production environments, which may have different sets of packages pre-installed. Maintainers of the project can't make assumptions about the target manifest, and users should instead rely on the --manifest option of dotnet publish instead.

ASP.NET implicit store

The default ASP.NET targets included with the Microsoft.AspNetCore.All meta-package include target manifests. As a consequence, dotnet publish of an ASP.NET application when it references this package 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.

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>

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.

Preparing a runtime environment

The administrator of a runtime environment can optimize for certain types of applications by building a runtime package store and the corresponding target manifest.

The first step is to create an XML file that describes the packages that must compose the runtime package store. The format of this file is compatible with the csproj format. Here's an example of such a file that adds Newtonsoft.Json and System.Runtime.Serialization.Primitives to the package store:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="System.Runtime.Serialization.Primitives" Version="4.1.1" />
  </ItemGroup>
</Project>

The runtime package store can then be provisioned by running a dotnet store --manifest [target-manifest.xml] --runtime [runtime id] --framework [target framework] command. Multiple file paths can be passed to a single dotnet store command.

The output of the command is a package store under the .dotnet/store subdirectory of the user profile, unless a specific location has been specified using the --output option. The root directory of the store contains a target manifest artifact.xml file, that can be made available to be downloaded by application authors who want to target this store when publishing.

Feedback

Please share your feedback.

Source

bleroy

Most helpful comment

@alexwiese "So it's kind of a global assembly cache?"

That's a good question, and what most seasoned .NET devs think about first ;) There are some significant differences however...

app-local always wins over it (GAC was always winning)
it's a runtime only feature
it's not strictly speaking machine-global
there are some additional features, such as the ability to target specific profiles using a manifest
and more...

bleroy on 15 Jun 2017

👍4

All 14 comments

So it's kind of a global assembly cache?

alexwiese on 15 Jun 2017

:eyes:

muratg on 15 Jun 2017

@alexwiese "So it's kind of a global assembly cache?"

That's a good question, and what most seasoned .NET devs think about first ;) There are some significant differences however...

app-local always wins over it (GAC was always winning)
it's a runtime only feature
it's not strictly speaking machine-global
there are some additional features, such as the ability to target specific profiles using a manifest
and more...

bleroy on 15 Jun 2017

👍4

What optimization is applied to the assemblies?

Is this optimization something we could apply to an entire app, like build a manifest to put the entire app into the runtime store? I kid, I assume this is only for packages (hence the PacakageReferences) so we'd have to package an app to do this which is odd, but hey might be worthwhile if performance is substantially boosted :)

g0t4 on 15 Jun 2017

@g0t4 the assemblies are cross-gen'd. This reduces the JIT time, hence improves startup time.

muratg on 15 Jun 2017

Will there also be an implicit store for regular Microsoft.NET.Sdk projects (e.g. a simple console app) that contains the .NET core assemblies like System.Runtime etc? If so, will this cover all NETStandard.Library assemblies?

cwe1ss on 21 Jun 2017

Would it make sense to pack stores as NuGet packages and allow them to be installed from a NuGet server?

tmds on 27 Jun 2017

@cwe1ss this scenario is already covered by the shared framework, i.e. Microsoft.NETCore.App. This is installed into [install-location]/dotnet/shared/Microsoft.NETCore.App and is used when you target netcoreapp. It includes everything in the related .NET Standard Library version and the APIs in .NET Core over and above .NET Standard. No need for anything else in the store.

DamianEdwards on 28 Jul 2017

👍1

@tmds it certainly could. We discussed packaging, naming, versioning, and acquisition of runtime stores (and their related target manifests for publishing) during design in 2.0 but ultimately haven't settled on a design yet that's integrated into the CLI experience. For now, one needs to call the dotnet store command to add packages to the store and then specify them in a target manifest during publish. ASP.NET Core's runtime store is included in the .NET Core installers and the target manifest is included in and automatically used during publish via way of the referenced Microsoft.AspNetCore.All package.

DamianEdwards on 28 Jul 2017

Will dotnet publish -r ... still produce a completely self-contained application? Maybe this info needs to get added to the above document.

leastprivilege on 28 Jul 2017

@leastprivilege yes. The Runtime Store only applies to applications running on the shared framework ("Portable Apps").

DamianEdwards on 28 Jul 2017

I'm wondering. Does it make sense to make use of the RPS in a asp dotnet core app targeting the full dotnet framework ? I guess not since it already makes use of the gac and it's kind of the same thing? Working with GAC gives one the possibility of working with assembly redirects which is ot available in the Runtime Package Store?

Aardvark71 on 23 Oct 2017

This feature was implemented in .NET Core 2.0. We have moved to a new scheme called "frameworks" that needs to be documented as part of .NET Core 3.0.