Global Tools NuGet Implementation

Status: Reviewing

Issue

This specification is the NuGet side of a new dotnet cli experience, tentatively called "Global Tools". Related specifications are here:

• .NET Core SDK - Global Tools

• Global tools implementation design

Each of these design spec are still evolving.

NuGet Github Collector issue #6200

Motivation

NuGet currently helps provide tools per dotnet cli requirements through the DotnetCLIToolReference feature. The reasoning for adding a new feature is described in the above linked specs.

Solution

We will introduce a new "PackageType" and a well-defined format how to create such tools.

NuGet will provide APIs for the CLI to be able to install mentioned global tools to a pre-determined location. To do this, they will create a temporary project that will indicate that it's a global tool restore project, and will contain a global tool reference as a "PackageReference". Then the CLI will call NuGet restore with these parameters, which NuGet needs to respect and interpret correctly. NuGet will block adding tool packages into standard package reference project. Additionally, only 1 global tool package reference per fake project is allowed.

Creating a global tool - Pack Experience

Since pack is very extensible, the pack experience, is almost completely in the hands of the CLI team. From NuGet side, we want authors to mark their packages with a PackageType metadata, as described in here.

Problem - What should the package type be? Proposal - The package type should simply be named Tool. Because the concepts of global and locals tools are discussed, I think this name minimizes confusion. In addition, packages with this package type, can only have 1 package type! Open Questions

• Double check nuget.org for custom package types named Tool
• Do we want to add extra validation on pack side to warn against creating packages with 2 packages if 1 of those package types is Tool

Installing a global tool

Dotnet CLI will create a temporary project and provide all details regarding restore there, including

• Install directory
• Target Framework
• Runtime Identifier In addition, this project should contain a restore project style property, named ToolReference. I am proposing that because we already have a DotnetCLiTool restore style type. An example temporary project would be:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <RestoreProjectStyle>ToolReference</RestoreProjectStyle>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <RestorePackagesPath>C:\Users\username\.dotnet\tools\my.tool\1.2</RestorePackagesPath>
    <RestoreSolutionDirectory>C:\Users\username\code\Library</RestoreSolutionDirectory>
    <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="my.tool" Version="1.2" />
  </ItemGroup>
</Project>

The install directory will be a V3 style directory, where the project.assets.json file will be in the root of the package folder.

The assets file will need to be extended to include the tools folder when packages are marked with the Tools PackageType. CLI will read the assets once restore is done to find the correct tool path.

Example:

C:\Users\username\.dotnet\tools\my.tool\1.2\project.assets.json

Open Questions

• NuGet will persist a cache file by default in the same directory as the assets file. Does this cause any problems? Potentially CLI should remove if so.
• How is the tools restore directory provided, and what is this default directory? Should CLI be the one that provides the directory? If NuGet provides, is it part of a config, and I think this compromises the long-term maintainability of the tools.

Non-Goals

Currently there is no plans to block users from being able to use DotnetCLIToolReference.