Rozwiązywanie problemów z użyciem narzędzi platformy .NET

  • Artykuł

Mogą wystąpić problemy podczas próby zainstalowania lub uruchomienia narzędzia .NET, które może być narzędziem globalnym lub narzędziem lokalnym. W tym artykule opisano typowe główne przyczyny i niektóre możliwe rozwiązania.

Nie można uruchomić zainstalowanego narzędzia .NET

Gdy nie można uruchomić narzędzia .NET, najprawdopodobniej wystąpił jeden z następujących problemów:

Nie można odnaleźć pliku wykonywalnego

Jeśli plik wykonywalny nie zostanie znaleziony, zostanie wyświetlony komunikat podobny do następującego:

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

Nazwa pliku wykonywalnego określa sposób wywoływania narzędzia. W poniższej tabeli opisano format:

Format nazwy pliku wykonywalnego Format wywołania
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Narzędzia globalne

Narzędzia globalne można zainstalować w katalogu domyślnym lub w określonej lokalizacji. Katalogi domyślne to:

System operacyjny Ścieżka
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Jeśli próbujesz uruchomić narzędzie globalne, sprawdź, czy PATH zmienna środowiskowa na maszynie zawiera ścieżkę, w której zainstalowano narzędzie globalne i czy plik wykonywalny znajduje się w tej ścieżce.

Interfejs wiersza polecenia platformy .NET próbuje dodać domyślną lokalizację do zmiennej środowiskowej PATH przy pierwszym użyciu. Istnieją jednak pewne scenariusze, w których lokalizacja może nie zostać automatycznie dodana do ścieżki PATH:

  • Jeśli używasz systemu Linux i zainstalowano zestaw .NET SDK przy użyciu plików tar.gz , a nie apt-get lub rpm.
  • Jeśli używasz systemu macOS 10.15 "Catalina" lub nowszych wersji.
  • Jeśli używasz systemu macOS 10.14 "Mojave" lub starszych wersji, a zestaw SDK platformy .NET został zainstalowany przy użyciu plików tar.gz , a nie .pkg.
  • Jeśli zainstalowano zestaw .NET Core 3.0 SDK, a zmienna DOTNET_ADD_GLOBAL_TOOLS_TO_PATH środowiskowa została ustawiona na false.
  • Jeśli zainstalowano zestaw .NET Core 2.2 SDK lub starsze wersje, a zmienna środowiskowa została ustawiona DOTNET_SKIP_FIRST_TIME_EXPERIENCE na true.

W tych scenariuszach lub w przypadku określenia --tool-path opcji podczas instalowania narzędziaPATH dotnet zmienna środowiskowa na maszynie nie zawiera automatycznie ścieżki, w której zainstalowano narzędzie globalne. W takim przypadku dołącz lokalizację narzędzia (na przykład $HOME/.dotnet/tools) do PATH zmiennej środowiskowej przy użyciu dowolnej metody zapewnianej przez powłokę do aktualizowania zmiennych środowiskowych. Aby uzyskać więcej informacji, zobacz .NET tools (Narzędzia platformy .NET).

Narzędzia lokalne

Jeśli próbujesz uruchomić narzędzie lokalne, sprawdź, czy w bieżącym katalogu lub w dowolnym katalogu nadrzędnym znajduje się plik manifestu o nazwie dotnet-tools.json . Ten plik może również znajdować się w folderze o nazwie .config w dowolnym miejscu w hierarchii folderów projektu, a nie w folderze głównym. Jeśli plik dotnet-tools.json istnieje, otwórz go i sprawdź narzędzie, które próbujesz uruchomić. Jeśli plik nie zawiera wpisu dla "isRoot": trueelementu , sprawdź również hierarchię plików, aby uzyskać dodatkowe pliki manifestu narzędzia.

Jeśli próbujesz uruchomić narzędzie .NET zainstalowane przy użyciu określonej ścieżki, musisz uwzględnić ją podczas korzystania z narzędzia. Przykładem użycia zainstalowanego narzędzia ścieżki narzędzi jest:

..\<toolDirectory>\dotnet-<toolName>

Nie znaleziono środowiska uruchomieniowego

Narzędzia platformy .NET to aplikacje zależne od platformy, co oznacza, że korzystają ze środowiska uruchomieniowego platformy .NET zainstalowanego na maszynie. Jeśli oczekiwane środowisko uruchomieniowe nie zostanie znalezione, są zgodne z normalnymi regułami wycofywania środowiska uruchomieniowego platformy .NET, takimi jak:

  • Aplikacja jest przekazywana do najwyższego wydania poprawki określonej wersji głównej i pomocniczej.
  • Jeśli nie ma zgodnego środowiska uruchomieniowego z pasującym numerem wersji głównej i pomocniczej, zostanie użyta następna wyższa wersja pomocnicza.
  • Wprowadzanie do przodu nie występuje między wersjami wersji zapoznawczej środowiska uruchomieniowego ani między wersjami wersji zapoznawczej a wersjami wydania. Dlatego narzędzia platformy .NET utworzone przy użyciu wersji zapoznawczych muszą zostać ponownie skompilowane i ponownie utworzone przez autora i ponownie zainstalowane.

Rzutowania nie będą domyślnie wykonywane w dwóch typowych scenariuszach:

  • Dostępne są tylko niższe wersje środowiska uruchomieniowego. Rzutuj do przodu wybiera tylko nowsze wersje środowiska uruchomieniowego.
  • Dostępne są tylko wyższe wersje główne środowiska uruchomieniowego. Rzut do przodu nie przekracza głównych granic wersji.

Jeśli aplikacja nie może znaleźć odpowiedniego środowiska uruchomieniowego, uruchomienie nie powiedzie się i zgłosi błąd.

Aby dowiedzieć się, które środowiska uruchomieniowe platformy .NET są zainstalowane na maszynie, możesz użyć jednego z następujących poleceń:

dotnet --list-runtimes
dotnet --info

Jeśli uważasz, że narzędzie powinno obsługiwać zainstalowaną wersję środowiska uruchomieniowego, możesz skontaktować się z autorem narzędzia i sprawdzić, czy może zaktualizować numer wersji lub wielokierunkowy. Po ponownym skompilowania i ponownym opublikowaniu pakietu narzędzi w programie NuGet przy użyciu zaktualizowanego numeru wersji możesz zaktualizować kopię. Chociaż tak się nie stanie, najszybszym rozwiązaniem jest zainstalowanie wersji środowiska uruchomieniowego, która będzie działać z narzędziem, które próbujesz uruchomić. Aby pobrać określoną wersję środowiska uruchomieniowego platformy .NET, odwiedź stronę pobierania platformy .NET.

Jeśli zainstalujesz zestaw .NET SDK w lokalizacji innej niż domyślna, musisz ustawić zmienną środowiskową DOTNET_ROOT na katalog zawierający dotnet plik wykonywalny.

Instalacja narzędzia .NET kończy się niepowodzeniem

Istnieje wiele powodów, dla których instalacja narzędzia globalnego lub lokalnego platformy .NET może zakończyć się niepowodzeniem. Gdy instalacja narzędzia zakończy się niepowodzeniem, zostanie wyświetlony komunikat podobny do następującego:

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

Aby ułatwić diagnozowanie tych błędów, komunikaty NuGet są wyświetlane bezpośrednio użytkownikowi wraz z poprzednim komunikatem. Komunikat NuGet może pomóc w zidentyfikowaniu problemu.

Wymuszanie nazewnictwa pakietów

Firma Microsoft zmieniła swoje wskazówki dotyczące identyfikatora pakietu dla narzędzi, co spowodowało, że wiele narzędzi nie można odnaleźć z przewidywaną nazwą. Nowe wskazówki dotyczą tego, że wszystkie narzędzia firmy Microsoft mają prefiks "Microsoft". Ten prefiks jest zarezerwowany i może być używany tylko w przypadku pakietów podpisanych przy użyciu certyfikatu autoryzowanego przez firmę Microsoft.

Podczas przejścia niektóre narzędzia firmy Microsoft będą miały starą formę identyfikatora pakietu, a inne będą miały nowy formularz:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

W miarę aktualizowania identyfikatorów pakietów należy zmienić identyfikator nowego pakietu, aby uzyskać najnowsze aktualizacje. Pakiety z uproszczoną nazwą narzędzia zostaną wycofane.

Wersje zapoznawcze

  • Próbujesz zainstalować wersję zapoznawcza i nie używasz --version opcji określania wersji.

Aby wskazać, że są w wersji zapoznawczej, należy określić narzędzia platformy .NET z częścią nazwy, aby wskazać, że są w wersji zapoznawczej. Nie musisz uwzględniać całej wersji zapoznawczej. Zakładając, że numery wersji są w oczekiwanym formacie, możesz użyć czegoś podobnego do następującego przykładu:

dotnet tool install -g --version 1.1.0-pre <toolName>

Pakiet nie jest narzędziem .NET

  • Znaleziono pakiet NuGet o tej nazwie, ale nie był to narzędzie .NET.

Jeśli spróbujesz zainstalować pakiet NuGet, który jest zwykłym pakietem NuGet, a nie narzędziem .NET, zostanie wyświetlony błąd podobny do następującego:

NU1212: Nieprawidłowa kombinacja pakietu projektu dla elementu <toolName>. Styl projektu DotnetToolReference może zawierać tylko odwołania typu DotnetTool.

Nie można uzyskać dostępu do źródła danych NuGet

  • Nie można uzyskać dostępu do wymaganego kanału informacyjnego NuGet, być może z powodu problemu z połączeniem internetowym.

Instalacja narzędzia wymaga dostępu do kanału informacyjnego NuGet zawierającego pakiet narzędzi. Nie powiedzie się, jeśli kanał informacyjny nie jest dostępny. Możesz zmienić źródła danych za pomocą nuget.configpolecenia , zażądać określonego nuget.config pliku lub określić dodatkowe źródła danych za pomocą przełącznika --add-source . Domyślnie program NuGet zgłasza błąd dla dowolnego kanału informacyjnego, który nie może nawiązać połączenia. Flaga --ignore-failed-sources może pominąć te nieosiągalne źródła.

Nieprawidłowy identyfikator pakietu

  • Nazwa narzędzia została błędnie wtypowana.

Częstą przyczyną niepowodzenia jest to, że nazwa narzędzia nie jest poprawna. Może się to zdarzyć z powodu mglistości lub dlatego, że narzędzie zostało przeniesione lub przestarzałe. W przypadku narzędzi w NuGet.org jednym ze sposobów upewnienia się, że nazwa jest poprawna, jest wyszukanie narzędzia w NuGet.org i skopiowanie polecenia instalacji.

401 (Brak autoryzacji)

Najprawdopodobniej określono alternatywny kanał informacyjny NuGet i ten kanał informacyjny wymaga uwierzytelniania. Istnieje kilka różnych sposobów rozwiązania tego problemu:

  • Dodaj parametr , --ignore-failed-sources aby pominąć błąd z prywatnego źródła danych i użyć publicznego źródła danych firmy Microsoft.

    Jeśli instalujesz narzędzie ze źródła danych NuGet firmy Microsoft, źródło danych niestandardowych zwraca ten błąd, zanim źródło danych NuGet firmy Microsoft zwróci wynik. Błąd kończy żądanie, anulując wszelkie inne oczekujące żądania kanału informacyjnego, które mogą być źródłem danych NuGet firmy Microsoft. --ignore-failed-sources Dodanie opcji powoduje, że polecenie traktuje ten błąd jako ostrzeżenie i umożliwia innym kanałom informacyjnym przetwarzanie żądania.

    dotnet tool install -g --ignore-failed-sources <toolName>

  • Wymuś źródło danych NuGet firmy Microsoft za pomocą parametru --add-source .

    Istnieje możliwość, że w globalnym lub lokalnym pliku konfiguracji NuGet brakuje publicznego źródła danych NuGet firmy Microsoft. Użyj kombinacji parametrów i--ignore-failed-sources, aby uniknąć błędnego --add-source źródła danych i polegać na publicznym kanale informacyjnym firmy Microsoft.

    dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>

  • Użyj niestandardowej konfiguracji NuGet, --configfile <FILE> parametru.

    Utwórz lokalny plik nuget.config z publicznym źródłem danych NuGet firmy Microsoft i odwołuj się do niego za pomocą parametru --configfile :

    dotnet tool install -g --configfile "./nuget.config" <toolName>

    Oto przykładowy plik konfiguracji:

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>

    Aby uzyskać więcej informacji, zobacz nuget.config reference (Dokumentacja narzędzia nuget.config)

  • Dodaj wymagane poświadczenia do pliku konfiguracji.

    Jeśli wiesz, że pakiet istnieje w skonfigurowanym kanale informacyjnym, podaj poświadczenia logowania w pliku konfiguracji NuGet. Aby uzyskać więcej informacji na temat poświadczeń w pliku konfiguracji nuget, zobacz sekcję packageSourceCredentials w dokumentacji nuget.config.

Zobacz też