Jak zarządzać narzędziami platformy .NET
Ten artykuł dotyczy: ✔️ zestaw .NET Core 2.1 SDK i nowsze wersje.
Narzędzie .NET to specjalny pakiet NuGet zawierający aplikację konsolową. Narzędzie można zainstalować na maszynie w następujący sposób:
Jako narzędzie globalne.
Pliki binarne narzędzi są instalowane w katalogu domyślnym dodanym do zmiennej środowiskowej PATH. Narzędzie można wywołać z dowolnego katalogu na maszynie bez określania jego lokalizacji. Jedna wersja narzędzia jest używana dla wszystkich katalogów na maszynie.
Jako narzędzie globalne w lokalizacji niestandardowej (nazywane również narzędziem ścieżki narzędzi).
Pliki binarne narzędzi są instalowane w określonej lokalizacji. Narzędzie można wywołać z katalogu instalacyjnego, podając katalog o nazwie polecenia lub dodając katalog do zmiennej środowiskowej PATH. Jedna wersja narzędzia jest używana dla wszystkich katalogów na maszynie.
Jako narzędzie lokalne (dotyczy zestawu .NET Core SDK 3.0 i nowszych wersji).
Pliki binarne narzędzi są instalowane w katalogu domyślnym. Narzędzie można wywołać z katalogu instalacyjnego lub dowolnego z jego podkatalogów. Różne katalogi mogą używać różnych wersji tego samego narzędzia.
Interfejs wiersza polecenia platformy .NET używa plików manifestu do śledzenia narzędzi zainstalowanych jako lokalne w katalogu. Gdy plik manifestu zostanie zapisany w katalogu głównym repozytorium kodu źródłowego, współautor może sklonować repozytorium i wywołać pojedyncze polecenie interfejsu wiersza polecenia platformy .NET, aby zainstalować wszystkie narzędzia wymienione w plikach manifestu.
Ważne
Narzędzia platformy .NET działają w pełnym zaufaniu. Nie instaluj narzędzia .NET, chyba że ufasz autorowi.
Narzędzia .NET mogą nie działać poprawnie, jeśli platforma .NET została zainstalowana za pośrednictwem przystawki.
Znajdowanie narzędzia
Oto kilka sposobów znajdowania narzędzi:
- Użyj polecenia wyszukiwania narzędzi dotnet , aby znaleźć narzędzie opublikowane do NuGet.org.
- Użyj filtru typu pakietu ".NET tool", aby wyszukać witrynę internetową NuGet . Aby uzyskać więcej informacji, zobacz Znajdowanie i wybieranie pakietów.
- Zobacz kod źródłowy narzędzi utworzonych przez zespół ASP.NET Core w katalogu Tools repozytorium GitHub dotnet/aspnetcore.
- Dowiedz się więcej o narzędziach diagnostycznych na platformie .NET.
Sprawdzanie autora i statystyk
Narzędzia platformy .NET mogą być zaawansowane, ponieważ działają w pełnym zaufaniu, a narzędzia globalne są dodawane do zmiennej środowiskowej PATH. Nie pobieraj narzędzi od osób, którym nie ufasz.
Jeśli narzędzie jest hostowane w narzędziu NuGet, możesz sprawdzić autora i statystyki, wyszukując narzędzie.
Instalowanie narzędzia globalnego
Aby zainstalować narzędzie jako narzędzie globalne, użyj -g
opcji lub --global
instalacji narzędzia dotnet, jak pokazano w poniższym przykładzie:
dotnet tool install -g dotnetsay
Dane wyjściowe pokazują polecenie użyte do wywołania narzędzia i zainstalowanej wersji, podobnie jak w poniższym przykładzie:
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:
System operacyjny | Ścieżka |
---|---|
Linux/macOS | $HOME/.dotnet/tools |
Windows | %USERPROFILE%\.dotnet\tools |
Ta lokalizacja jest dodawana do ścieżki użytkownika po pierwszym uruchomieniu zestawu SDK. Dlatego narzędzia globalne można wywołać z dowolnego katalogu bez określania lokalizacji narzędzia.
Dostęp do narzędzi jest specyficzny dla użytkownika, a nie globalny. Narzędzie globalne jest dostępne tylko dla użytkownika, który zainstalował to narzędzie.
Instalowanie narzędzia globalnego w lokalizacji niestandardowej
Aby zainstalować narzędzie jako narzędzie globalne w lokalizacji niestandardowej, użyj --tool-path
opcji instalacji narzędzia dotnet, jak pokazano w poniższych przykładach:
W systemie Windows:
dotnet tool install dotnetsay --tool-path c:\dotnet-tools
W systemie Linux lub macOS:
dotnet tool install dotnetsay --tool-path ~/bin
Zestaw SDK platformy .NET nie dodaje tej lokalizacji automatycznie do zmiennej środowiskowej PATH. Aby wywołać narzędzie ścieżki narzędzi, należy upewnić się, że polecenie jest dostępne przy użyciu jednej z następujących metod:
- Dodaj katalog instalacyjny do zmiennej środowiskowej PATH.
- Określ pełną ścieżkę do narzędzia podczas wywoływania.
- Wywołaj narzędzie z poziomu katalogu instalacyjnego.
Instalowanie narzędzia lokalnego
Dotyczy zestawu .NET Core 3.0 SDK i nowszych wersji.
Jeśli chcesz zainstalować narzędzie tylko do dostępu lokalnego (dla bieżącego katalogu i podkatalogów), musisz dodać narzędzie do pliku manifestu narzędzia. Aby utworzyć plik manifestu narzędzia, uruchom dotnet new tool-manifest
polecenie:
dotnet new tool-manifest
To polecenie tworzy plik manifestu o nazwie dotnet-tools.json w katalogu .config . Aby dodać narzędzie lokalne do pliku manifestu, użyj polecenia dotnet tool install i pomiń--global
opcje i --tool-path
, jak pokazano w poniższym przykładzie:
dotnet tool install dotnetsay
Dane wyjściowe polecenia pokazują, w którym pliku manifestu znajduje się nowo zainstalowane narzędzie, podobnie jak w poniższym przykładzie:
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:
{
"version": 1,
"isRoot": true,
"tools": {
"botsay": {
"version": "1.0.0",
"commands": [
"botsay"
]
},
"dotnetsay": {
"version": "2.1.3",
"commands": [
"dotnetsay"
]
}
}
}
Zazwyczaj do katalogu głównego repozytorium jest dodawane narzędzie lokalne. Po zaewidencjonowania pliku manifestu w repozytorium deweloperzy, którzy wyewidencjonują kod z repozytorium, uzyskają najnowszy plik manifestu. Aby zainstalować wszystkie narzędzia wymienione w pliku manifestu, uruchomią dotnet tool restore
polecenie:
dotnet tool restore
Dane wyjściowe wskazują przywrócone narzędzia:
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.
Instalowanie określonej wersji narzędzia
Aby zainstalować wersję wstępną lub określoną wersję narzędzia, określ numer wersji przy użyciu --version
opcji, jak pokazano w poniższym przykładzie:
dotnet tool install dotnetsay --version 2.1.3
Aby zainstalować wersję wstępną narzędzia bez określenia dokładnego numeru wersji, użyj --version
opcji i podaj symbol wieloznaczny, jak pokazano w poniższym przykładzie:
dotnet tool install --global dotnetsay --version "*-rc*"
Korzystanie z narzędzia
Polecenie, którego używasz do wywoływania narzędzia, może różnić się od nazwy instalowanego pakietu. Aby wyświetlić wszystkie narzędzia aktualnie zainstalowane na maszynie dla bieżącego użytkownika, użyj polecenia dotnet tool list :
dotnet tool list
Dane wyjściowe pokazują wersję i polecenie każdego narzędzia, podobnie jak w poniższym przykładzie:
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 poprzednim przykładzie, lista zawiera narzędzia lokalne. Aby wyświetlić narzędzia globalne, użyj --global
opcji . Aby wyświetlić narzędzia ścieżki narzędzi, użyj --tool-path
opcji .
Wywoływanie narzędzia globalnego
W przypadku narzędzi globalnych użyj samego polecenia narzędzia. Jeśli na przykład polecenie to dotnetsay
lub dotnet-doc
, to właśnie służy do wywoływania narzędzia globalnego:
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. Jeśli na przykład polecenie to dotnet-doc
, następujące polecenie wywołuje narzędzie:
dotnet doc
Jednak w poniższym scenariuszu nie można użyć dotnet
polecenia , aby wywołać narzędzie globalne:
- Narzędzie globalne i narzędzie lokalne mają to samo polecenie poprzedzone prefiksem
dotnet-
. - Chcesz wywołać narzędzie globalne z katalogu, który jest w zakresie narzędzia lokalnego.
W tym scenariuszu dotnet doc
i dotnet dotnet-doc
wywołaj narzędzie lokalne. Aby wywołać narzędzie globalne, użyj samego polecenia :
dotnet-doc
Wywoływanie narzędzia do ścieżki narzędzi
Aby wywołać narzędzie globalne zainstalowane przy użyciu tool-path
opcji, upewnij się, że polecenie jest dostępne zgodnie z opisem wcześniej w tym artykule.
Wywoływanie narzędzia lokalnego
Aby wywołać narzędzie lokalne, należy użyć dotnet
polecenia z poziomu katalogu instalacyjnego. Możesz użyć długiego formularza () lub krótkiego formularza (dotnet tool run <COMMAND_NAME>
dotnet <COMMAND_NAME>
), jak pokazano w poniższych przykładach:
dotnet tool run dotnetsay
dotnet dotnetsay
Jeśli polecenie jest poprzedzone dotnet-
prefiksem , można dołączyć lub pominąć prefiks podczas wywoływania narzędzia. Jeśli na przykład polecenie to dotnet-doc
, którykolwiek z poniższych przykładów wywołuje narzędzie lokalne:
dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc
Aktualizowanie narzędzia
Aktualizowanie narzędzia obejmuje odinstalowanie i ponowne zainstalowanie go przy użyciu najnowszej stabilnej wersji. Aby zaktualizować narzędzie, użyj polecenia dotnet tool update z tą samą opcją, która była używana do zainstalowania narzędzia:
dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>
W przypadku narzędzia lokalnego zestaw SDK wyszukuje bieżący katalog i katalogi nadrzędne, aby znaleźć pierwszy plik manifestu zawierający identyfikator pakietu. Jeśli w żadnym pliku manifestu nie ma takiego identyfikatora pakietu, zestaw SDK doda nowy wpis do najbliższego pliku manifestu.
Odinstalowywanie narzędzia
Odinstaluj narzędzie przy użyciu polecenia dotnet tool uninstall z tą samą opcją, która była używana do zainstalowania narzędzia:
dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>
W przypadku narzędzia lokalnego zestaw SDK wyszukuje bieżący katalog i katalogi nadrzędne, aby znaleźć pierwszy plik manifestu zawierający identyfikator pakietu.
Uzyskiwanie pomocy i rozwiązywanie problemów
Jeśli nie można zainstalować lub uruchomić narzędzia, zobacz Rozwiązywanie problemów z użyciem narzędzi platformy .NET. Listę dostępnych dotnet tool
poleceń i parametrów można uzyskać przy użyciu parametru --help
:
dotnet tool --help
Aby uzyskać instrukcje dotyczące użycia narzędzi, wprowadź jedno z następujących poleceń lub zobacz witrynę internetową narzędzia:
<command> --help
dotnet <command> --help
Zobacz też
- Samouczek: tworzenie narzędzia .NET przy użyciu interfejsu wiersza polecenia platformy .NET
- Samouczek: instalowanie i używanie narzędzia globalnego platformy .NET przy użyciu interfejsu wiersza polecenia platformy .NET
- Samouczek: instalowanie i używanie narzędzia lokalnego platformy .NET przy użyciu interfejsu wiersza polecenia platformy .NET