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

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ů:

• Nebyl nalezen spustitelný soubor nástroje.
• nebyla nalezena správná verze modulu runtime .NET.

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
Windows	%USERPROFILE%\.dotnet\tools

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

.NET CLI 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í .tar.gz souborů, 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í .tar.gz souborů, a ne .pkg.
• Pokud jste nainstalovali sadu .NET Core 3.0 SDK a nastavili jste proměnnou prostředí DOTNET_ADD_GLOBAL_TOOLS_TO_PATH na false.
• Pokud jste nainstalovali sadu .NET Core 2.2 SDK nebo starší verze a nastavili jste proměnnou prostředí DOTNET_SKIP_FIRST_TIME_EXPERIENCE na true.

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

Místní nástroje

Pokud se pokoušíte spustit místní nástroj, ověřte, že existuje soubor manifestu s názvem dotnet-tools.json v aktuálním adresáři nebo ve všech nadřazených adresářích. 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 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 rozhraní, což znamená, že spoléhají na modul runtime .NET nainstalovaný na vašem počítači. Pokud nebyl nalezen očekávaný runtime, postupují se podle obvyklých pravidel přenosu na novější verzi runtime .NET, jako 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 následující vyšší podverze.
• Mezi verzemi Preview runtime nebo mezi verzemi Preview a verzemi vydání nedochází k přechodu 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 k pokračování ve výchozím nastavení nedojde:

• K dispozici jsou pouze nižší verze modulu runtime. Roll-forward vybírá pouze pozdější verze prostředí pro spuštění.
• K dispozici jsou pouze vyšší hlavní verze modulu runtime. Roll-forward nepřekračuje hranice hlavní verze.

Pokud aplikace nemůže najít správný runtime, se nespustí a nahlásí chybu.

Na vašem počítači zjistíte, které runtime .NET jsou nainstalovány, pomocí jednoho z následujících příkazů:

dotnet --list-runtimes
dotnet --info

Pokud si myslíte, že by nástroj měl podporovat verzi modulu runtime, kterou máte nainstalovanou, můžete kontaktovat autora nástroje a zjistit, zda mohou aktualizovat číslo verze nebo přidat podporu pro více platforem. 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 nastavit proměnnou prostředí DOTNET_ROOT do adresáře, který obsahuje spustitelný soubor dotnet.

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í názvů balíčků
• Preview verze
• balíček není nástroj .NET
• Nelze získat přístup k kanálu NuGet
• NESPRÁVNÉ ID balíčku
• 401 (neautorizováno)

Vynucení pojmenování balíčků

Společnost Microsoft změnila pokyny k ID balíčku pro nástroje, což vede k tomu, že řada nástrojů není nalezena pod očekávaným názvem. 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é.

Náhledové verze

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

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 projektového balíčku 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í soubor nuget.config nebo zadat další informační kanály pomocí přepínače --add-source. Ve výchozím nastavení NuGet vyvolá chybu u jakéhokoli kanálu, který se nemůže připojit. Příznak --ignore-failed-sources může tyto nedostupné zdroje přeskočit.

Nesprávné číslo 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 překlepu nebo kvůli tomu, že byl nástroj přesunut nebo vyřazen. 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:

• Přidejte parametr --ignore-failed-sources, který vynechá chybu z privátního informačního kanálu a použije 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 ukončí požadavek a zruší všechny ostatní čekající žádosti o informační kanál, mezi kterými může být i informační kanál NuGet od Microsoftu. Přidání možnosti --ignore-failed-sources způsobí, ž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 kanál Microsoft NuGet pomocí parametru --add-source.

  Je možné, že v globálním nebo místním konfiguračním souboru NuGet chybí veřejný informační kanál Microsoft NuGet. Použijte kombinaci parametrů --add-source a --ignore-failed-sources, abyste se vyhnuli chybnému informačnímu kanálu a spoléhali 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 NuGetu, parametru --configfile <FILE>.

  Vytvořte místní soubor nuget.config obsahující pouze veřejný informační kanál 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 naleznete viz referenci 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 najdete v sekci packageSourceCredentials reference nuget.config.

Viz také

• nástroje .NET