Muokkaa

Jaa


Tutorial: Install and use a .NET global tool using the .NET CLI

This article applies to: ✔️ .NET Core 2.1 SDK and later versions

This tutorial teaches you how to install and use a global tool. You use a tool that you create in the first tutorial of this series.

Prerequisites

Use the tool as a global tool

  1. Install the tool from the package by running the dotnet tool install command in the microsoft.botsay project folder:

    dotnet tool install --global --add-source ./nupkg microsoft.botsay
    

    The --global parameter tells the .NET CLI to install the tool binaries in a default location that is automatically added to the PATH environment variable.

    The --add-source parameter tells the .NET CLI to temporarily use the ./nupkg directory as an additional source feed for NuGet packages. You gave your package a unique name to make sure that it will only be found in the ./nupkg directory, not on the Nuget.org site.

    The output shows the command used to call the tool and the version installed:

    You can invoke the tool using the following command: botsay
    Tool 'microsoft.botsay' (version '1.0.0') was successfully installed.
    

    Note

    By default the architecture of the .NET binaries to install represents the currently running OS architecture. To specify a different OS architecture, see dotnet tool install, --arch option.

  2. Invoke the tool:

    botsay hello from the bot
    

    Note

    If this command fails, you may need to open a new terminal to refresh the PATH.

  3. Remove the tool by running the dotnet tool uninstall command:

    dotnet tool uninstall -g microsoft.botsay
    

Use the tool as a global tool installed in a custom location

  1. Install the tool from the package.

    On Windows:

    dotnet tool install --tool-path c:\dotnet-tools --add-source ./nupkg microsoft.botsay
    

    On Linux or macOS:

    dotnet tool install --tool-path ~/bin --add-source ./nupkg microsoft.botsay
    

    The --tool-path parameter tells the .NET CLI to install the tool binaries in the specified location. If the directory doesn't exist, it is created. This directory is not automatically added to the PATH environment variable.

    The output shows the command used to call the tool and the version installed:

    You can invoke the tool using the following command: botsay
    Tool 'microsoft.botsay' (version '1.0.0') was successfully installed.
    
  2. Invoke the tool:

    On Windows:

    c:\dotnet-tools\botsay hello from the bot
    

    On Linux or macOS:

    ~/bin/botsay hello from the bot
    
  3. Remove the tool by running the dotnet tool uninstall command:

    On Windows:

    dotnet tool uninstall --tool-path c:\dotnet-tools microsoft.botsay
    

    On Linux or macOS:

    dotnet tool uninstall --tool-path ~/bin microsoft.botsay
    

Troubleshoot

If you get an error message while following the tutorial, see Troubleshoot .NET tool usage issues.

Next steps

In this tutorial, you installed and used a tool as a global tool. For more information about how to install and use global tools, see Managing global tools. To install and use the same tool as a local tool, advance to the next tutorial.