Sdílet prostřednictvím

Řešení potíží s používáním nástrojů .NET

  • Článek

Při pokusu o instalaci nebo spuštění nástroje .NET může docházet k problémům, což může být globální nástroj nebo místní nástroj. Tento článek popisuje běžné původní příčiny a některá možná řešení.

Nainstalovaný nástroj .NET nejde spustit

Pokud se nástroj .NET nepodaří spustit, pravděpodobně jste narazili na některý z následujících problémů:

Spustitelný soubor nebyl nalezen.

Pokud se spustitelný soubor nenajde, zobrazí se zpráva podobná této:

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.

Název spustitelného souboru určuje způsob vyvolání nástroje. Následující tabulka popisuje formát:

Formát názvu spustitelného souboru Formát vyvolání
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Globální nástroje

Globální nástroje je možné nainstalovat do výchozího adresáře nebo do konkrétního umístění. Výchozí adresáře jsou:

Operační systém Cesta
Linux/macOS $HOME/.dotnet/tools
Okna %USERPROFILE%\.dotnet\tools

Pokud se pokoušíte spustit globální nástroj, zkontrolujte, jestli PATH proměnná prostředí na vašem počítači obsahuje cestu, kam jste nainstalovali globální nástroj, a že spustitelný soubor je v této cestě.

Rozhraní příkazového řádku .NET se pokusí přidat výchozí umístění do proměnné prostředí PATH při prvním použití. Existují však některé scénáře, kdy se umístění nemusí automaticky přidat do path:

  • Pokud používáte Linux a nainstalovali jste sadu .NET SDK pomocí souborů .tar.gz , a ne apt-get nebo rpm.
  • Pokud používáte macOS 10.15 "Catalina" nebo novější verze.
  • Pokud používáte macOS 10.14 Mojave nebo starší verze a nainstalovali jste sadu .NET SDK pomocí souborů .tar.gz , nikoli .pkg.
  • Pokud jste nainstalovali sadu .NET Core 3.0 SDK a nastavili jste proměnnou DOTNET_ADD_GLOBAL_TOOLS_TO_PATH prostředí na falsehodnotu .
  • Pokud jste nainstalovali sadu .NET Core 2.2 SDK nebo starší verze a nastavili jste proměnnou DOTNET_SKIP_FIRST_TIME_EXPERIENCE prostředí na true.

V těchto scénářích nebo pokud jste při instalaci nástroje dotnet zadali --tool-path možnost, proměnná prostředí na vašem počítači automaticky neobsahuje cestu, PATH do které jste nainstalovali globální nástroj. V takovém případě připojte umístění nástroje (například $HOME/.dotnet/tools) k PATH proměnné prostředí pomocí libovolné metody, kterou prostředí poskytuje pro aktualizaci proměnných prostředí. Další informace najdete v tématu Nástroje .NET.

Místní nástroje

Pokud se pokoušíte spustit místní nástroj, ověřte, že v aktuálním adresáři nebo v libovolném nadřazené adresáři existuje soubor manifestu s názvem dotnet-tools.json . Tento soubor může být také aktivní ve složce s názvem .config kdekoli v hierarchii složek projektu místo kořenové složky. Pokud soubor dotnet-tools.json existuje, otevřete ho a zkontrolujte nástroj, který se pokoušíte spustit. Pokud soubor neobsahuje položku pro "isRoot": true, zkontrolujte také další hierarchii souborů pro další soubory manifestu nástroje.

Pokud se pokoušíte spustit nástroj .NET, který byl nainstalován se zadanou cestou, musíte tuto cestu zahrnout při použití nástroje. Příkladem použití nainstalovaného nástroje s cestou k nástrojům je:

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

Modul runtime nebyl nalezen.

Nástroje .NET jsou aplikace závislé na platformě, což znamená, že spoléhají na modul runtime .NET nainstalovaný na vašem počítači. Pokud se očekávaný modul runtime nenajde, dodržují normální pravidla vrácení modulu runtime .NET, například:

  • Aplikace se přepojí na nejvyšší verzi opravy zadané hlavní verze a podverze.
  • Pokud neexistuje žádný odpovídající modul runtime s odpovídajícím číslem hlavní verze a podverze, použije se další vyšší podverze.
  • Mezi verzemi runtime verze Preview nebo mezi verzemi Preview a verzemi verze Preview nedochází k vrácení vpřed. Nástroje .NET vytvořené pomocí verzí Preview proto musí znovu vytvořit a znovu publikovat autor a přeinstalovat.

Ve dvou běžných scénářích nedojde ve výchozím nastavení k postupnému uvedení:

  • K dispozici jsou pouze nižší verze modulu runtime. Roll-forward only selects later versions of the runtime.
  • K dispozici jsou pouze vyšší hlavní verze modulu runtime. Roll-forward nepřekračuje hranice hlavní verze.

Pokud aplikace nemůže najít odpovídající modul runtime, nepodaří se spustit a nahlásí chybu.

Moduly runtime .NET jsou na vašem počítači nainstalované pomocí jednoho z následujících příkazů:

dotnet --list-runtimes
dotnet --info

Pokud si myslíte, že nástroj by měl podporovat verzi modulu runtime, kterou jste právě nainstalovali, můžete kontaktovat autora nástroje a zjistit, jestli může aktualizovat číslo verze nebo více cílů. Po opětovném zkompilování a opětovném publikování balíčku nástrojů na NuGet s aktualizovaným číslem verze můžete aktualizovat kopii. I když k tomu nedojde, nejrychlejším řešením je nainstalovat verzi modulu runtime, která by fungovala s nástrojem, který se pokoušíte spustit. Pokud chcete stáhnout konkrétní verzi modulu runtime .NET, přejděte na stránku pro stažení .NET.

Pokud nainstalujete sadu .NET SDK do jiného než výchozího umístění, musíte proměnnou DOTNET_ROOT prostředí nastavit na adresář, který obsahuje dotnet spustitelný soubor.

Instalace nástroje .NET selže

Existuje několik důvodů, proč může instalace globálního nebo místního nástroje .NET selhat. Když se instalace nástroje nezdaří, zobrazí se zpráva podobná této:

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

Kvůli diagnostice těchto selhání se zprávy NuGet zobrazují přímo uživateli spolu s předchozí zprávou. S identifikací problému vám může pomoct zpráva NuGet.

Vynucení pojmenování balíčků

Společnost Microsoft změnila pokyny k ID balíčku pro nástroje, což vede k tomu, že se s předpovídaném názvem nenašel počet nástrojů. Nové pokyny jsou uvedené v tom, že všechny nástroje Microsoftu mají předponu Microsoft. Tato předpona je vyhrazená a dá se použít jenom pro balíčky podepsané pomocí autorizovaného certifikátu Microsoftu.

Během přechodu budou mít některé nástroje Microsoftu starý formulář ID balíčku, zatímco jiné budou mít nový formulář:

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

Při aktualizaci ID balíčků budete muset změnit nové ID balíčku, abyste získali nejnovější aktualizace. Balíčky se zjednodušeným názvem nástroje budou zastaralé.

Verze Preview

  • Pokoušíte se nainstalovat verzi Preview a nepoužíli jste --version možnost určit verzi.

Nástroje .NET, které jsou ve verzi Preview, musí být zadané s částí názvu, aby bylo možné označit, že jsou ve verzi Preview. Nemusíte zahrnout celý náhled. Za předpokladu, že jsou čísla verzí v očekávaném formátu, můžete použít něco jako v následujícím příkladu:

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

Balíček není nástroj .NET.

  • Našel se balíček NuGet podle tohoto názvu, ale nebyl to nástroj .NET.

Pokud se pokusíte nainstalovat balíček NuGet, který je běžným balíčkem NuGet, a ne nástrojem .NET, zobrazí se chyba podobná následující:

NU1212: Neplatná kombinace balíčku projektu pro <toolName>. Styl projektu DotnetToolReference může obsahovat pouze odkazy typu DotnetTool.

K informačnímu kanálu NuGet nelze získat přístup

  • Požadovaný informační kanál NuGet není přístupný, možná kvůli problému s připojením k internetu.

Instalace nástroje vyžaduje přístup k informačnímu kanálu NuGet, který obsahuje balíček nástroje. Pokud informační kanál není dostupný, selže. Informační kanály můžete změnit pomocí nuget.config, požádat o konkrétní nuget.config soubor nebo zadat další informační kanály s přepínačem --add-source . Ve výchozím nastavení NuGet vyvolá chybu u jakéhokoli informačního kanálu, který se nemůže připojit. Příznak --ignore-failed-sources může tyto nedostupné zdroje přeskočit.

NESPRÁVNÉ ID balíčku

  • Nesprávně jste zadali název nástroje.

Běžným důvodem selhání je, že název nástroje není správný. K tomu může dojít kvůli nesprávnému přetypování nebo kvůli přesunutí nebo vyřazení nástroje. U nástrojů na NuGet.org je jedním ze způsobů, jak zajistit, abyste měli správný název, je vyhledat nástroj na NuGet.org a zkopírovat instalační příkaz.

401 (Neautorizováno)

Pravděpodobně jste zadali alternativní informační kanál NuGet a tento informační kanál vyžaduje ověření. Existuje několik různých způsobů, jak to vyřešit:

  • --ignore-failed-sources Přidejte parametr pro obejití chyby z privátního informačního kanálu a použijte veřejný informační kanál Microsoftu.

    Pokud instalujete nástroj z informačního kanálu Microsoft NuGet, váš vlastní informační kanál vrací tuto chybu předtím, než informační kanál NuGet microsoftu vrátí výsledek. Chyba požadavek ukončí a zruší všechny ostatní čekající žádosti o informační kanál, což může být informační kanál NuGet od Microsoftu. Přidání možnosti způsobí, --ignore-failed-sources že příkaz bude tuto chybu považovat za upozornění a umožní ostatním informačním kanálům zpracovat požadavek.

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

  • Vynuťte informační kanál Microsoft NuGet s parametrem --add-source .

    Je možné, že globální nebo místní konfigurační soubor NuGetu chybí ve veřejném informačním kanálu Microsoft NuGet. Použijte kombinaci parametrů --add-source a --ignore-failed-sources vyhněte se chybnému informačnímu kanálu a spoléháte na veřejný informační kanál Microsoftu.

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

  • Použijte vlastní konfiguraci NuGet, --configfile <FILE> parametr.

    Vytvořte místní soubor nuget.config pouze s veřejným informačním kanálem Microsoft NuGet a odkazujte na něj pomocí parametru --configfile :

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

    Tady je příklad konfiguračního souboru:

    <?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>

    Další informace najdete v referenčních informacích k nuget.config.

  • Přidejte požadované přihlašovací údaje do konfiguračního souboru.

    Pokud víte, že balíček existuje v nakonfigurovaném informačním kanálu, zadejte přihlašovací údaje v konfiguračním souboru NuGet. Další informace o přihlašovacích údajích v konfiguračním souboru nuget naleznete v části packageSourceCredentials odkazu nuget.config.

Viz také