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 platformy .NET, najprawdopodobniej wystąpił jeden z następujących problemów:

Nie znaleziono 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:

  • Jeśli używasz systemu Linux i zainstalowano zestaw SDK platformy .NET 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 i ustawisz zmienną DOTNET_ADD_GLOBAL_TOOLS_TO_PATH środowiskową na false.
  • Jeśli zainstalowano zestaw .NET Core 2.2 SDK lub starsze wersje, a zmienna DOTNET_SKIP_FIRST_TIME_EXPERIENCE środowiskowa została ustawiona na true.

W tych scenariuszach lub w przypadku określenia --tool-path opcji PATH 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 zmiennej środowiskowej PATH przy użyciu dowolnej metody zapewnianej przez powłokę do aktualizowania zmiennych środowiskowych. Aby uzyskać więcej informacji, zobacz 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 w celu uzyskania dodatkowych plików manifestu narzędzia.

Jeśli próbujesz uruchomić narzędzie .NET, które zostało zainstalowane z określoną ścieżką, musisz dołączyć tą ścieżkę podczas korzystania z narzędzia. Przykładem użycia zainstalowanego narzędzia 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 pasującego środowiska uruchomieniowego z pasującym numerem wersji głównej i pomocniczej, zostanie użyta następna wyższa wersja pomocnicza.
  • Wycofywanie nie występuje między wersjami wersji zapoznawczej środowiska uruchomieniowego lub między wersjami wersji zapoznawczej a wersjami wersji zapoznawczej. Dlatego narzędzia platformy .NET utworzone przy użyciu wersji zapoznawczej muszą zostać ponownie skompilowane i ponownie utworzone przez autora i ponownie zainstalowane.

Wycofywanie nie będzie domyślnie wykonywane w dwóch typowych scenariuszach:

  • Dostępne są tylko niższe wersje środowiska uruchomieniowego. Funkcja roll-forward wybiera tylko nowsze wersje środowiska uruchomieniowego.
  • Dostępne są tylko wyższe wersje główne środowiska uruchomieniowego. Roll-forward nie przekracza głównych granic wersji.

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

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

dotnet --list-runtimes
dotnet --info

Jeśli uważasz, że narzędzie powinno obsługiwać aktualnie zainstalowaną wersję środowiska uruchomieniowego, możesz skontaktować się z autorem narzędzia i sprawdzić, czy mogą zaktualizować numer wersji lub wiele elementów docelowych. Po ponownym skompilowania i ponownym opublikowaniu pakietu narzędzi do narzędzia 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 SDK platformy .NET w lokalizacji innej niż domyślna, musisz ustawić zmienną DOTNET_ROOT środowiskową 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 nie można odnaleźć wielu narzędzi o przewidywanej nazwie. Nowe wskazówki polegają na tym, że wszystkie narzędzia firmy Microsoft mają prefiks "Microsoft". Ten prefiks jest zarezerwowany i może być używany tylko dla pakietów podpisanych przy użyciu certyfikatu autoryzowanego przez firmę Microsoft.

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

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

Po zaktualizowaniu identyfikatorów pakietów należy zmienić identyfikator nowego pakietu, aby pobrać najnowsze aktualizacje. Pakiety z uproszczoną nazwą narzędzia będą przestarzałe.

Wersje zapoznawcza

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

Narzędzia platformy .NET, które są w wersji zapoznawczej, muszą być określone z częścią nazwy, aby wskazać, że są one 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 platformy .NET, zostanie wyświetlony błąd podobny do następującego:

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

Nie można uzyskać dostępu do kanału informacyjnego 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 źródła danych NuGet zawierającego pakiet narzędzi. Nie powiedzie się, jeśli kanał informacyjny jest niedostępny. Możesz zmienić kanały informacyjne za pomocą polecenia nuget.config, zażądać określonego nuget.config pliku lub określić dodatkowe źródła danych za pomocą przełącznika --add-source . Domyślnie narzędzie 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 zostało 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 kanału informacyjnego 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 kanału informacyjnego --add-source 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 przy użyciu 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 dokumentację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 wnuget.config reference's.

Zobacz też