Local Tools Early Preview Documentation

Local Tools Early Preview Documentation

The feature is shipped in 3.0.100 SDK. We are working to convert this documentation to an official one.

Motivation

Enable high cohesion between tools and corresponding code repositories. The repository maintainer could check-in a list of dotnet tools with certain version. And other contributor can use these tools within the repository with certain gestures. Local tools use the same package as global tools.

Walk through

Install the latest dotnet SDK “checkin build”

1. You can find the installer at here under the Master (3.0.x Runtime) column.
2. Most of the existing dotnet tools package(global tools) are targeting runtime netcoreapp2.1. You need to install it in order to run the existing command. You can find it at here under Run apps - Runtime column.

Create tool manifest file

Run dotnet new tool-manifest command. It will create a tool manifest file dotnet-tools.json under the directory .config.

Restore command

In order to use the command specified in tool manifest file. You need to run command dotnet tool restore and you should see the following success message:

Tool 'dotnetsay' (version '2.1.4') was restored. Available commands: dotnetsay


Restore was successful.

Run the command

Run local tool would require prefix dotnet. So it will not be ambiguous most of the time. And when there is a global tools with the pattern “dotnet-*” CLI will find the tool with the following rule

global tools command invoke	local tools command invoke
dotnetsay	dotnet dotnetsay
dotnet say (aka dotnet-say)	dotnet say
dotnetsay and dotnet say both exist	dotnet dotnetsay and dotnet dotnet-say

You could also call it by dotnet tool run dotnetsay hi. “dotnet tool run” is not ambiguous.

If you see the following error, please install netcoreapp2.1 runtime. At https://www.microsoft.com/net/download/dotnet-core/2.1. Since dotnetsay and most of the global tools are targeting 2.1 runtime while preview dotnet SDK only contains preview netcoreapp3.0 runtime.

It was not possible to find any compatible framework version
The specified framework 'Microsoft.NETCore.App', version '2.1.0' was not found.
  - Check application dependencies and target a framework version installed at:
      C:\Users\name\Downloads\dotnet-sdk-latest-win-x64-localtools\
  - Installing .NET Core prerequisites might help resolve this problem:
      https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409
  - The .NET Core framework and SDK can be installed from:
      https://aka.ms/dotnet-download
  - The following versions are installed:
      3.0.0-preview1-27017-04 at [C:\Users\name\dotnet-sdk-latest-win-x64\shared\Microsoft.NETCore.App]

Manage local tools

Install new local tool

Run dotnet tool install <PACKAGE_ID> (dotnet tool install dotnetsay) to install new command. It will add the tool entry to your manifest file. And at the same time it will restore the tool so you can invoke it right away.

The message will show which manifest file it added to

You can invoke the tool from this directory using the following command: dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed. Entry is added to the manifest file /Users/name/tools/sub/dotnet-tools.json

Uninstall local tool

Run dotnet tool uninstall <PACKAGE_ID>

Update local tool

Run dotnet tool update <PACKAGE_ID>. If the new package version is higher. SDK will find the first manifest file that contains the package id and update it. If there is no such package id in any manifest file (that is in the scope), SDK will add a new entry to the closest manifest file.

List local tool

Run dotnet tool list to list all available tools in the current directory. It will also list the origin manifest of the tool. It can be used to diagnose unexpected tools in the current directory

$ dotnet tool list
Package Id            Version      Commands             Manifest
----------------------------------------------------------------------------------------------------------------------
dotnet-dbinfo         1.3.1        dotnet-dbinfo        /Users/name/tools/sub/dotnet-tools.json
dotnet-depends        0.2.0        dotnet-depends       /Users/name/tools/sub/dotnet-tools.json
amazon.ecs.tools      3.0.0        dotnet-ecs           /Users/name/tools/sub/dotnet-tools.json
dotnet-encrypto       1.0.5        dotnet-encrypto      /Users/name/tools/sub/dotnet-tools.json
t-rex                 1.0.53       t-rex                /Users/name/tools/.config/dotnet-tools.json

Feature Detail

The scope of the tool manifest file

If there is a tool manifest file or a tool manifest file under folder .config in the parent/current directory of the current directory. The current directory has the access to the tools specified in the tool manifest file. For example. If there is a tool manifest with a tool dotnetsay in the root of the repository, the user could run dotnet tool run dotnetsay hi in any sub directory of the repository.

isRoot flag

The flag in the manifest file means “stop looking up parent directories for manifest file when the first one is found”. This entry in manifest file is required.

Invoke local tools

Global tools use $PATH and shell to resolve command via shim. However we could not use the same mechanism due to the limitation of the operation system shell.

Example of multiple tools

{
    "version": "1",
    "isRoot": true,
    "tools": {
        "t-rex": {
            "version": "1.0.53",
            "commands": ["t-rex"],
        },
        "dotnetsay": {
            "version": "2.1.4",
            "commands": ["dotnetsay"]
        }
    }
}

Requirement of commands

We require listing out the command in the tool package. Note many dotnet tool packages do not have matching package id and the command.

Term

Local tool scope: the working directory that has the access to the tool specified in the dotnet-tools.json stored in current or parent directory.

Tool manifest file: dotnet-tools.json

Repository maintainer: A dotnet tool consumer. Programmers have the write access to the repository and decide which dotnet tools should be used in this repository.

Repository contributor: A dotnet tool consumer. Programmers have the read access to the repository and use dotnet tools decided by repository maintainer.

Local tools restore: Restore all tools that is possible to be accessed by current directory and generate cache.

Resolver cache: Technical, not customer facing. Cache to speed up the local tool resolution.

[wli3]

The official doc is here https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-local-tool

[wli3]

@stijnherreman only the documentation is in preview. It is shipped in 3.0.100 SDK.

We are working to convert this documentation to an official one