Jak zarządzać narzędziami .NETHow to manage .NET tools
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:
- Użyj polecenia Search narzędzia dotnet , aby znaleźć narzędzie, które jest publikowane w usłudze NuGet.org.Use the dotnet tool search command to find a tool that is published to NuGet.org.
- Przeszukaj witrynę sieci Web NuGet przy użyciu filtru typu pakietu "narzędzie .NET".Search the NuGet website by using the ".NET tool" package type filter. Aby uzyskać więcej informacji, zobacz Znajdowanie i wybieranie pakietów.For more information, see Finding and choosing packages.
- Zobacz kod źródłowy narzędzi utworzonych przez zespół ASP.NET Core w katalogu Tools w repozytorium GitHub/aspnetcore.See the source code for the tools created by the ASP.NET Core team in the Tools directory of the dotnet/aspnetcore GitHub repository.
- Informacje o narzędziach diagnostycznych w narzędziach diagnostycznych platformy .NET.Learn about diagnostic tools at .NET diagnostic 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 bydotnet-
. - 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
- Samouczek: Tworzenie narzędzia platformy .NET przy użyciu interfejsu wiersza polecenia platformy .NETTutorial: Create a .NET tool using the .NET CLI
- Samouczek: Instalowanie i używanie narzędzia globalnego platformy .NET przy użyciu interfejsu wiersza polecenia platformy .NETTutorial: Install and use a .NET global tool using the .NET CLI
- Samouczek: Instalowanie i używanie lokalnego narzędzia .NET przy użyciu interfejsu wiersza polecenia platformy .NETTutorial: Install and use a .NET local tool using the .NET CLI