Runtime Package Store

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.

[bleroy]

@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…

[DamianEdwards]

@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.