Udostępnij za pośrednictwem

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 zmienna środowiskowa PATH 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 zainstalowałeś zestaw SDK platformy .NET przy użyciu plików .tar.gz, a nie przez 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 i ustawiono zmienną środowiskową DOTNET_ADD_GLOBAL_TOOLS_TO_PATH na false.
  • Jeśli zainstalowano zestaw .NET Core 2.2 SDK lub starsze wersje, a zmienna środowiskowa DOTNET_SKIP_FIRST_TIME_EXPERIENCE została ustawiona na true.

W tych scenariuszach lub jeśli określono opcję --tool-pathpodczas instalowania narzędzia dotnet, zmienna środowiskowa PATH 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 zmiennej środowiskowej PATH przy użyciu dowolnej metody zapewnianej przez powłokę do aktualizowania zmiennych środowiskowych. Aby uzyskać więcej informacji, zobacz .NET tools.

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 dotnet-tools.json istnieje, otwórz go i sprawdź narzędzie, które próbujesz uruchomić. Jeśli plik nie zawiera wpisu dla "isRoot": true, sprawdź również wyżej w hierarchii plików, aby znaleźć 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 narzędzia zainstalowanego według ścieżki narzędziowej jest:

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

Nie znaleziono środowiska uruchomieniowego

Narzędzia platformy .NET to aplikacje zależne od platformy , co oznacza, że polegają na środowisku uruchomieniowym platformy .NET zainstalowanym na maszynie. Jeśli oczekiwane środowisko wykonawcze nie zostanie znalezione, stosują normalne reguły przesuwania do przodu wersji środowiska platformy .NET, takie jak:

  • Aplikacja zostaje zaktualizowana do najnowszej poprawki określonej wersji głównej i podwersji.
  • 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.
  • Przejście do przodu nie występuje między wersjami zapoznawczymi środowiska uruchomieniowego ani między wersjami zapoznawczymi a wersjami oficjalnymi. Dlatego narzędzia platformy .NET utworzone przy użyciu wersji zapoznawczych muszą zostać ponownie skompilowane i ponownie utworzone przez autora i ponownie zainstalowane.

Przesunięcie do przodu nie będzie domyślnie zachodzić 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. Przesunięcie w przód nie przekracza granic głównych 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 dodać wsparcie dla różnych wersji. Po ponownym skompilowaniu i ponownym opublikowaniu pakietu narzędzi w NuGet przy użyciu zaktualizowanego numeru wersji możesz zaktualizować swoją 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 .NET.

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

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 opcji --version, aby określić wersję.

Narzędzia .NET w wersji zapoznawczej muszą mieć część nazwy wskazującą, ż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 <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. Kanały informacyjne można zmienić za pomocą nuget.config, zażądać określonego pliku nuget.config lub określić dodatkowe kanały informacyjne za pomocą przełącznika --add-source. Domyślnie program NuGet zgłasza błąd dla dowolnego źródła, które 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 literówki lub dlatego, że narzędzie zostało przeniesione lub wycofane z użycia. 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 z kanału NuGet firmy Microsoft, kanał niestandardowy zwraca ten błąd, zanim kanał NuGet firmy Microsoft zwróci wynik. Błąd kończy żądanie, anulując wszelkie inne oczekujące żądania kanału, które mogą dotyczyć kanału NuGet firmy Microsoft. Dodanie opcji --ignore-failed-sources 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ś kanał 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 --add-source i --ignore-failed-sources, aby uniknąć błędnego ź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, parametru --configfile <FILE>.

    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.

  • 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 odniesieniu nuget.config,.

Zobacz też