Jak zarządzać narzędziami .NETHow to manage .NET tools

  • Czas czytania: 6 min

Ten artykuł ma zastosowanie do: ✔️ .net Core 2,1 SDK i nowszych wersjachThis article applies to: ✔️ .NET Core 2.1 SDK and later versions

Narzędzie .NET jest specjalnym pakietem NuGet, który zawiera aplikację konsolową.A .NET tool is a special NuGet package that contains a console application. Narzędzie można zainstalować na maszynie w następujący sposób:A tool can be installed on your machine in the following ways:

  • Jako narzędzie globalne.As a global tool.

    Pliki binarne narzędzia są instalowane w katalogu domyślnym, który jest dodawany do zmiennej środowiskowej PATH.The tool binaries are installed in a default directory that is added to the PATH environment variable. Można wywołać narzędzie z dowolnego katalogu na maszynie bez określania jego lokalizacji.You can invoke the tool from any directory on the machine without specifying its location. Jedna wersja narzędzia jest używana dla wszystkich katalogów na komputerze.One version of a tool is used for all directories on the machine.

  • Jako narzędzie globalne w niestandardowej lokalizacji (nazywanej również narzędziem ścieżki narzędzia).As a global tool in a custom location (also known as a tool-path tool).

    Pliki binarne narzędzia są instalowane w określonej lokalizacji.The tool binaries are installed in a location that you specify. Możesz wywołać narzędzie z katalogu instalacyjnego lub podając katalog z nazwą polecenia lub dodając katalog do zmiennej środowiskowej PATH.You can invoke the tool from the installation directory or by providing the directory with the command name or by adding the directory to the PATH environment variable. Jedna wersja narzędzia jest używana dla wszystkich katalogów na komputerze.One version of a tool is used for all directories on the machine.

  • Jako narzędzie lokalne (dotyczy zestaw .NET Core SDK 3,0 i nowszych).As a local tool (applies to .NET Core SDK 3.0 and later).

    Pliki binarne narzędzia są instalowane w katalogu domyślnym.The tool binaries are installed in a default directory. Należy wywołać narzędzie z katalogu instalacyjnego lub któregokolwiek z jego podkatalogów.You invoke the tool from the installation directory or any of its subdirectories. Różne katalogi mogą korzystać z różnych wersji tego samego narzędzia.Different directories can use different versions of the same tool.

    Interfejs wiersza polecenia platformy .NET używa plików manifestu do śledzenia, które narzędzia są instalowane jako lokalne w katalogu.The .NET CLI uses manifest files to keep track of which tools are installed as local to a directory. Gdy plik manifestu jest zapisywany w katalogu głównym repozytorium kodu źródłowego, współautor może sklonować repozytorium i wywoływać pojedyncze polecenie interfejsu wiersza polecenia platformy .NET, które instaluje wszystkie narzędzia wymienione w plikach manifestu.When the manifest file is saved in the root directory of a source code repository, a contributor can clone the repository and invoke a single .NET CLI command that installs all of the tools listed in the manifest files.

Ważne

Narzędzia platformy .NET działają w trybie pełnego zaufania..NET tools run in full trust. Nie instaluj narzędzia platformy .NET, chyba że ufasz autorowi.Do not install a .NET tool unless you trust the author.

Znajdź narzędzieFind a tool

Oto kilka sposobów znajdowania narzędzi:Here are some ways to find tools:

Sprawdź autora i statystykiCheck the author and statistics

Ponieważ narzędzia platformy .NET działają w trybie pełnego zaufania, a narzędzia globalne są dodawane do zmiennej środowiskowej PATH, mogą być bardzo wydajne.Since .NET tools run in full trust, and global tools are added to the PATH environment variable, they can be very powerful. Nie pobieraj narzędzi z osób, które nie są zaufane.Don't download tools from people you don't trust.

Jeśli narzędzie jest hostowane w usłudze NuGet, można sprawdzić autora i statystyk, wyszukując narzędzie.If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool.

Instalowanie narzędzia globalnegoInstall a global tool

Aby zainstalować narzędzie jako narzędzie globalne, użyj -g lub --global opcji instalacji narzędzia dotnet, jak pokazano w następującym przykładzie:To install a tool as a global tool, use the -g or --global option of dotnet tool install, as shown in the following example:

dotnet tool install -g dotnetsay

Dane wyjściowe przedstawiają polecenie używane do wywołania narzędzia i zainstalowanej wersji, podobnie jak w poniższym przykładzie:The output shows the command used to invoke the tool and the version installed, similar to the following example:

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

Domyślna lokalizacja plików binarnych narzędzia zależy od systemu operacyjnego:The default location for a tool's binaries depends on the operating system:

System operacyjnyOS ŚcieżkaPath
Linux/macOSLinux/macOS $HOME/.dotnet/tools
WindowsWindows %USERPROFILE%\.dotnet\tools

Ta lokalizacja jest dodawana do ścieżki użytkownika podczas pierwszego uruchomienia zestawu SDK, dzięki czemu narzędzia globalne mogą być wywoływane z dowolnego katalogu bez określania lokalizacji narzędzia.This location is added to the user's path when the SDK is first run, so global tools can be invoked from any directory without specifying the tool location.

Dostęp do narzędzi to specyficzne dla użytkownika, a nie globalne maszyny.Tool access is user-specific, not machine global. Narzędzie globalne jest dostępne tylko dla użytkownika, który zainstalował narzędzie.A global tool is only available to the user that installed the tool.

Instalowanie narzędzia globalnego w niestandardowej lokalizacjiInstall a global tool in a custom location

Aby zainstalować narzędzie jako narzędzie globalne w niestandardowej lokalizacji, użyj --tool-path opcji Instalacja narzędzia dotnet, jak pokazano w poniższych przykładach.To install a tool as a global tool in a custom location, use the --tool-path option of dotnet tool install, as shown in the following examples.

W systemie Windows:On Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

W systemie Linux lub macOS:On Linux or macOS:

dotnet tool install dotnetsay --tool-path ~/bin

Zestaw SDK platformy .NET nie dodaje automatycznie tej lokalizacji do zmiennej środowiskowej PATH.The .NET SDK doesn't add this location automatically to the PATH environment variable. Aby wywołać narzędzie ścieżki narzędzi, należy upewnić się, że polecenie jest dostępne za pomocą jednej z następujących metod:To invoke a tool-path tool, you have to make sure the command is available by using one of the following methods:

  • Dodaj katalog instalacyjny do zmiennej środowiskowej PATH.Add the installation directory to the PATH environment variable.
  • Określ pełną ścieżkę do narzędzia podczas jego wywoływania.Specify the full path to the tool when you invoke it.
  • Wywołaj narzędzie z katalogu instalacyjnego.Invoke the tool from within the installation directory.

Instalowanie narzędzia lokalnegoInstall a local tool

Dotyczy zestawu .NET Core 3,0 SDK i nowszych wersji.Applies to .NET Core 3.0 SDK and later.

Aby zainstalować narzędzie tylko do dostępu lokalnego (dla bieżącego katalogu i podkatalogów), należy dodać je do pliku manifestu narzędzia.To install a tool for local access only (for the current directory and subdirectories), it has to be added to a tool manifest file. Aby utworzyć plik manifestu narzędzia, uruchom dotnet new tool-manifest polecenie:To create a tool manifest file, run the dotnet new tool-manifest command:

dotnet new tool-manifest

To polecenie tworzy plik manifestu o nazwie dotnet-tools.jsw katalogu . config .This command creates a manifest file named dotnet-tools.json under the .config directory. Aby dodać narzędzie lokalne do pliku manifestu, należy użyć polecenia Zainstaluj narzędzie dotnet i pominąć --global --tool-path Opcje i, jak pokazano w następującym przykładzie:To add a local tool to the manifest file, use the dotnet tool install command and omit the --global and --tool-path options, as shown in the following example:

dotnet tool install dotnetsay

Dane wyjściowe polecenia pokazują plik manifestu, w którym znajduje się nowo zainstalowane narzędzie, podobnie jak w poniższym przykładzie:The command output shows which manifest file the newly installed tool is in, similar to the following example:

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 /home/name/botsay/.config/dotnet-tools.json.

W poniższym przykładzie przedstawiono plik manifestu z zainstalowanymi dwoma lokalnymi narzędziami:The following example shows a manifest file with two local tools installed:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Zazwyczaj można dodać lokalne narzędzie do katalogu głównego repozytorium.You typically add a local tool to the root directory of the repository. Po zaewidencjonowaniu pliku manifestu do repozytorium, deweloperzy, którzy ewidencjonują kod z repozytorium, pobierają najnowszy plik manifestu.After you check in the manifest file to the repository, developers who check out code from the repository get the latest manifest file. Aby zainstalować wszystkie narzędzia wymienione w pliku manifestu, uruchom dotnet tool restore polecenie:To install all of the tools listed in the manifest file, they run the dotnet tool restore command:

dotnet tool restore

Dane wyjściowe wskazują, które narzędzia zostały przywrócone:The output indicates which tools were restored:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Zainstaluj określoną wersję narzędziaInstall a specific tool version

Aby zainstalować wersję wstępną lub określoną wersję narzędzia, należy określić numer wersji przy użyciu --version opcji, jak pokazano w następującym przykładzie:To install a pre-release version or a specific version of a tool, specify the version number by using the --version option, as shown in the following example:

dotnet tool install dotnetsay --version 2.1.3

Korzystanie z narzędziaUse a tool

Polecenie używane do wywoływania narzędzia może różnić się od nazwy instalowanego pakietu.The command that you use to invoke a tool may be different from the name of the package that you install. Aby wyświetlić wszystkie narzędzia aktualnie zainstalowane na komputerze dla bieżącego użytkownika, użyj polecenia z listy narzędzi dotnet :To display all of the tools currently installed on the machine for the current user, use the dotnet tool list command:

dotnet tool list

Dane wyjściowe wyświetlają wersję i polecenie każdego narzędzia, podobnie jak w poniższym przykładzie:The output shows each tool's version and command, similar to the following example:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Jak pokazano w tym przykładzie, lista zawiera narzędzia lokalne.As shown in this example, the list shows local tools. Aby wyświetlić narzędzia globalne, użyj --global opcji i, aby zobaczyć narzędzia ścieżki narzędzi, użyj --tool-path opcji.To see global tools, use the --global option, and to see tool-path tools, use the --tool-path option.

Wywołaj narzędzie globalneInvoke a global tool

W przypadku narzędzi globalnych Użyj narzędzia.For global tools, use the tool command by itself. Na przykład jeśli polecenie jest dotnetsay lub, to jest dotnet-doc używane do wywołania polecenia:For example, if the command is dotnetsay or dotnet-doc, that's what you use to invoke the command:

dotnetsay
dotnet-doc

Jeśli polecenie zaczyna się od prefiksu dotnet- , alternatywnym sposobem wywołania narzędzia jest użycie dotnet polecenia i pominięcie prefiksu polecenia narzędzia.If the command begins with the prefix dotnet-, an alternative way to invoke the tool is to use the dotnet command and omit the tool command prefix. Na przykład, jeśli polecenie ma wartość dotnet-doc , następujące polecenie wywołuje narzędzie:For example, if the command is dotnet-doc, the following command invokes the tool:

dotnet doc

Jednak w poniższym scenariuszu nie można użyć dotnet polecenia do wywołania narzędzia globalnego:However, in the following scenario you can't use the dotnet command to invoke a global tool:

  • Narzędzie globalne i narzędzie lokalne mają to samo polecenie poprzedzone przez program dotnet- .A global tool and a local tool have the same command prefixed by dotnet-.
  • Chcesz wywołać narzędzie globalne z katalogu, który znajduje się w zakresie dla narzędzia lokalnego.You want to invoke the global tool from a directory that is in scope for the local tool.

W tym scenariuszu dotnet doc i dotnet dotnet-doc Wywołaj narzędzie lokalne.In this scenario, dotnet doc and dotnet dotnet-doc invoke the local tool. Aby wywołać narzędzie globalne, użyj polecenia przez samego siebie:To invoke the global tool, use the command by itself:

dotnet-doc

Wywołaj narzędzie ścieżki narzędziowejInvoke a tool-path tool

Aby wywołać narzędzie globalne, które jest instalowane przy użyciu tool-path opcji, upewnij się, że polecenie jest dostępne, zgodnie z opisem we wcześniejszej części tego artykułu.To invoke a global tool that is installed by using the tool-path option, make sure the command is available, as explained earlier in this article.

Wywoływanie narzędzia lokalnegoInvoke a local tool

Aby wywołać narzędzie lokalne, należy użyć dotnet polecenia z katalogu instalacyjnego.To invoke a local tool, you have to use the dotnet command from within the installation directory. Możesz użyć długiej formy ( dotnet tool run <COMMAND_NAME> ) lub krótkiej formy ( dotnet <COMMAND_NAME> ), jak pokazano w następujących przykładach:You can use the long form (dotnet tool run <COMMAND_NAME>) or the short form (dotnet <COMMAND_NAME>), as shown in the following examples:

dotnet tool run dotnetsay
dotnet dotnetsay

Jeśli polecenie jest poprzedzone przez dotnet- , można dołączyć lub pominąć prefiks po wywołaniu narzędzia.If the command is prefixed by dotnet-, you can include or omit the prefix when you invoke the tool. Na przykład, jeśli polecenie jest dotnet-doc , każdy z poniższych przykładów wywoła narzędzie lokalne:For example, if the command is dotnet-doc, any of the following examples invokes the local tool:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Aktualizowanie narzędziaUpdate a tool

Aktualizacja narzędzia polega na odinstalowaniu i ponownym zainstalowaniu go z najnowszą stabilną wersją.Updating a tool involves uninstalling and reinstalling it with the latest stable version. Aby zaktualizować narzędzie, należy użyć polecenia " Update" narzędzia dotnet z tą samą opcją, która została użyta do zainstalowania narzędzia:To update a tool, use the dotnet tool update command with the same option that you used to install the tool:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

W przypadku narzędzia lokalnego zestaw SDK znajduje pierwszy plik manifestu zawierający identyfikator pakietu, przeszukując bieżący katalog i katalogi nadrzędne.For a local tool, the SDK finds the first manifest file that contains the package ID by looking in the current directory and parent directories. Jeśli w pliku manifestu nie ma takiego identyfikatora pakietu, zestaw SDK dodaje nowy wpis do najbliższego pliku manifestu.If there is no such package ID in any manifest file, the SDK adds a new entry to the closest manifest file.

Odinstalowywanie narzędziaUninstall a tool

Usuń narzędzie za pomocą Narzędzia dotnet Command Uninstall polecenie z tą samą opcją, która została użyta do zainstalowania narzędzia:Remove a tool by using the dotnet tool uninstall command with the same option that you used to install the tool:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

W przypadku narzędzia lokalnego zestaw SDK znajduje pierwszy plik manifestu zawierający identyfikator pakietu, przeszukując bieżący katalog i katalogi nadrzędne.For a local tool, the SDK finds the first manifest file that contains the package ID by looking in the current directory and parent directories.

Uzyskiwanie pomocy i rozwiązywanie problemówGet help and troubleshoot

Aby uzyskać listę dostępnych dotnet tool poleceń, wprowadź następujące polecenie:To get a list of available dotnet tool commands, enter the following command:

dotnet tool --help

Aby uzyskać instrukcje dotyczące użycia narzędzia, wprowadź jedno z następujących poleceń lub zapoznaj się z witryną sieci Web narzędzia:To get tool usage instructions, enter one of the following commands or see the tool's website:

<command> --help
dotnet <command> --help

Jeśli instalacja lub uruchomienie narzędzia nie powiedzie się, zobacz Rozwiązywanie problemów z użyciem narzędzia platformy .NET.If a tool fails to install or run, see Troubleshoot .NET tool usage issues.

Zobacz takżeSee also