Jak zarządzać narzędziami platformy .NET

  • Artykuł

Ten artykuł dotyczy: ✔️ .NET Core 2.1 SDK i nowszych wersji.

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, który jest dodawany 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 (znanej również jako narzędzie do rysowania ścieżki narzędzi).

    Pliki binarne narzędzia są instalowane w określonej lokalizacji. Narzędzie można wywołać z katalogu instalacyjnego, podając katalog z nazwą 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:

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.

Uwaga

Domyślnie architektura plików binarnych platformy .NET do zainstalowania reprezentuje obecnie uruchomioną architekturę systemu operacyjnego. Aby określić inną architekturę systemu operacyjnego, zobacz dotnet tool install, --arch option(Instalacja narzędzia dotnet).

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 mogą być wywoływane z dowolnego katalogu bez określania lokalizacji narzędzia.

Dostęp do narzędzi jest specyficzny dla użytkownika, a nie globalny komputer. 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 .NET SDK 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 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 narzędzie lokalne jest dodawane do katalogu głównego repozytorium. 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, uruchamiają 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 używane 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 przedstawiają 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 .

Aby wyświetlić listę określonego narzędzia, użyj polecenia dotnet tool list <PACKAGE_ID> :

dotnet tool list dotnetsay

Dane wyjściowe będą wyświetlać tylko to narzędzie, jeśli jest zainstalowane, podobnie jak w poniższym przykładzie:

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

Wywoływanie narzędzia globalnego

W przypadku narzędzi globalnych użyj polecenia narzędzia samodzielnie. 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 rozpoczyna się od prefiksu dotnet-, alternatywnym sposobem wywoływania 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 w celu wywołania narzędzia globalnego:

  • Narzędzie globalne i narzędzie lokalne mają ten sam prefiks polecenia z 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 polecenia samodzielnie:

dotnet-doc

Wywoływanie narzędzia ś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 we wcześniejszej sekcji tego artykułu.

Wywoływanie narzędzia lokalnego

Aby wywołać narzędzie lokalne, należy użyć dotnet polecenia z katalogu instalacyjnego. Można użyć formularza długiego (dotnet tool run <COMMAND_NAME>) lub krótkiego formularza (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 za pomocą 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ędzia, wprowadź jedno z następujących poleceń lub zobacz witrynę internetową narzędzia:

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

Zobacz też