Felsöka användningsproblem med .NET-verktyg

Du kan stöta på problem när du försöker installera eller köra ett .NET-verktyg, som kan vara ett globalt verktyg eller ett lokalt verktyg. Den här artikeln beskriver de vanliga rotorsakerna och några möjliga lösningar.

Det går inte att köra det installerade .NET-verktyget

När ett .NET-verktyg inte kan köras stötte du troligtvis på något av följande problem:

• Det gick inte att hitta den körbara filen för verktyget.
• Rätt version av .NET-körningen hittades inte.

Det gick inte att hitta den körbara filen

Om den körbara filen inte hittas visas ett meddelande som liknar följande:

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.

Namnet på den körbara filen avgör hur du anropar verktyget. I följande tabell beskrivs formatet:

Format för körbart namn	Anropsformat
dotnet-<toolName>.exe	dotnet <toolName>
<toolName>.exe	<toolName>

Globala verktyg

Globala verktyg kan installeras i standardkatalogen eller på en specifik plats. Standardkatalogerna är:

OS	Sökväg
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

Om du försöker köra ett globalt verktyg kontrollerar du att PATH miljövariabeln på datorn innehåller sökvägen där du installerade det globala verktyget och att den körbara filen finns i den sökvägen.

.NET CLI försöker lägga till standardplatsen i PATH-miljövariabeln vid den första användningen. Det finns dock vissa scenarier där platsen kanske inte läggs till i PATH automatiskt:

• Om du använder Linux och har installerat .NET SDK med hjälp av .tar.gz-filer och inte apt-get eller rpm.
• Om du använder macOS 10.15 "Catalina" eller senare versioner.
• Om du använder macOS 10.14 "Mojave" eller tidigare versioner, och du har installerat .NET SDK med hjälp av .tar.gz-filer och inte .pkg.
• Om du har installerat .NET Core 3.0 SDK och du har angett DOTNET_ADD_GLOBAL_TOOLS_TO_PATH miljövariabeln till false.
• Om du har installerat .NET Core 2.2 SDK eller tidigare versioner och du har angett DOTNET_SKIP_FIRST_TIME_EXPERIENCE miljövariabeln till true.

I dessa scenarier eller om du angav --tool-path alternativet när du installerade ett dotnet-verktyg innehåller PATH miljövariabeln på datorn inte automatiskt sökvägen där du installerade det globala verktyget. I så fall lägger du till verktygsplatsen (till exempel $HOME/.dotnet/tools) i PATH miljövariabeln med hjälp av den metod som gränssnittet tillhandahåller för uppdatering av miljövariabler. Mer information finns i .NET-verktyg.

Lokala verktyg

Om du försöker köra ett lokalt verktyg kontrollerar du att det finns en manifestfil med namnet dotnet-tools.json i den aktuella katalogen eller någon av dess överordnade kataloger. Den här filen kan också finnas under en mapp med namnet .config var som helst i projektmappshierarkin, i stället för rotmappen. Om dotnet-tools.json finns öppnar du det och söker efter det verktyg som du försöker köra. Om filen inte innehåller någon post för "isRoot": truekontrollerar du även ytterligare verktygsmanifestfiler längre upp i filhierarkin.

Om du försöker köra ett .NET-verktyg som har installerats med en angiven sökväg måste du inkludera den sökvägen när du använder verktyget. Ett exempel på hur du använder ett verktygssökväg installerat är:

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

Körningen hittades inte

.NET-verktyg är ramverksberoende program, vilket innebär att de förlitar sig på en .NET-körning installerad på datorn. Om den förväntade körningen inte hittas följer de vanliga regler för .NET-körningsöversättning, till exempel:

• Ett program rullar vidare till den högsta korrigeringsversionen av den angivna huvudversionen och delversionen.
• Om det inte finns någon matchande körning med ett matchande huvud- och delversionsnummer används nästa högre delversion.
• Vidarekoppling sker inte mellan förhandsversioner av körningen eller mellan förhandsversioner och versionsversioner. Därför måste .NET-verktyg som skapats med förhandsversioner återskapas och publiceras på nytt av författaren och installeras om.

Roll-forward sker inte som standard i två vanliga scenarier:

• Endast lägre versioner av körningen är tillgängliga. Roll-forward väljer bara senare versioner av körningen.
• Endast högre huvudversioner av körningen är tillgängliga. Framåtrullningen går inte över huvudversionsgränserna.

Om ett program inte kan hitta en lämplig körning kan det inte köras och rapporterar ett fel.

Du kan ta reda på vilka .NET-körningar som är installerade på datorn med något av följande kommandon:

dotnet --list-runtimes
dotnet --info

Om du tycker att verktyget ska ha stöd för den körningsversion som du för närvarande har installerat kan du kontakta verktygsförfattaren och se om de kan uppdatera versionsnumret eller flermålsversionen. När de har omkompilerat och publicerat om sitt verktygspaket till NuGet med ett uppdaterat versionsnummer kan du uppdatera din kopia. Även om det inte sker är den snabbaste lösningen för dig att installera en version av körningen som skulle fungera med det verktyg som du försöker köra. Om du vill ladda ned en specifik .NET-körningsversion går du till nedladdningssidan för .NET.

Om du installerar .NET SDK på en plats som inte är standard måste du ange miljövariabeln DOTNET_ROOT till den katalog som innehåller den dotnet körbara filen.

Installationen av .NET-verktyget misslyckas

Det finns ett antal orsaker till att installationen av ett globalt .NET-verktyg eller ett lokalt verktyg kan misslyckas. När verktygsinstallationen misslyckas visas ett meddelande som liknar följande:

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

För att diagnostisera dessa fel visas NuGet-meddelanden direkt för användaren, tillsammans med föregående meddelande. NuGet-meddelandet kan hjälpa dig att identifiera problemet.

• Tvingande av namn på paket
• Förhandsversioner
• Paketet är inte ett .NET-verktyg
• Det går inte att komma åt NuGet-feeden
• Paket-ID är felaktigt
• 401 (ej auktoriserad)

Tvingande av namn på paket

Microsoft har ändrat sin vägledning om paket-ID för verktyg, vilket resulterar i att ett antal verktyg inte hittas med det förutsagda namnet. Den nya vägledningen är att alla Microsoft-verktyg är prefix med "Microsoft". Det här prefixet är reserverat och kan endast användas för paket som är signerade med ett Microsoft-auktoriserat certifikat.

Under övergången har vissa Microsoft-verktyg den gamla formen av paket-ID,medan andra har det nya formuläret:

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

När paket-ID:n uppdateras måste du ändra till det nya paket-ID:t för att få de senaste uppdateringarna. Paket med det förenklade verktygsnamnet kommer att bli inaktuella.

Förhandsversioner

• Du försöker installera en förhandsversion och använde --version inte alternativet för att ange versionen.

.NET-verktyg som är i förhandsversion måste anges med en del av namnet för att indikera att de är i förhandsversion. Du behöver inte ta med hela förhandsversionen. Förutsatt att versionsnumren är i förväntat format kan du använda något som liknar följande exempel:

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

Paketet är inte ett .NET-verktyg

• Ett NuGet-paket med det här namnet hittades, men det var inte ett .NET-verktyg.

Om du försöker installera ett NuGet-paket som är ett vanligt NuGet-paket och inte ett .NET-verktyg visas ett fel som liknar följande:

NU1212: Ogiltig kombination av projektpaket för <toolName>. Projektformatet DotnetToolReference kan bara innehålla referenser av typen DotnetTool.

Det går inte att komma åt NuGet-feeden

• Det går inte att komma åt det nödvändiga NuGet-flödet, kanske på grund av ett internetanslutningsproblem.

Verktygsinstallationen kräver åtkomst till NuGet-feeden som innehåller verktygspaketet. Det misslyckas om feeden inte är tillgänglig. Du kan ändra feeds med nuget.config, begära en specifik nuget.config fil eller ange ytterligare feeds med växeln --add-source . Som standard genererar NuGet ett fel för alla feeds som inte kan ansluta. Flaggan --ignore-failed-sources kan hoppa över dessa källor som inte kan nås.

Paket-ID är felaktigt

• Du skrev fel namn på verktyget.

En vanlig orsak till felet är att verktygsnamnet inte är korrekt. Detta kan inträffa på grund av feltypning, eller på grund av att verktyget har flyttats eller blivit inaktuellt. För verktyg på NuGet.org är ett sätt att se till att du har rätt namn att söka efter verktyget på NuGet.org och kopiera installationskommandot.

401 (behörighet saknas)

Troligtvis har du angett ett alternativt NuGet-flöde, och det flödet kräver autentisering. Det finns några olika sätt att lösa detta:

• Lägg till parametern --ignore-failed-sources för att kringgå felet från det privata flödet och använda det offentliga Microsoft-flödet.

  Om du installerar ett verktyg från Microsoft NuGet-feeden returnerar din anpassade feed det här felet innan Microsofts NuGet-feed returnerar ett resultat. Felet avslutar begäran och avbryter alla andra väntande feedbegäranden, som kan vara Microsofts NuGet-feed. --ignore-failed-sources Om du lägger till alternativet kan kommandot behandla det här felet som en varning och andra feeds kan bearbeta begäran.

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

• Framtvinga Microsoft NuGet-feeden med parametern --add-source .

  Det är möjligt att den globala eller lokala NuGet-konfigurationsfilen saknar det offentliga Microsoft NuGet-flödet. Använd en kombination av parametrarna --add-source och --ignore-failed-sources för att undvika det felaktiga flödet och förlita dig på det offentliga Microsoft-flödet.

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

• Använd en anpassad NuGet-konfiguration, --configfile <FILE> parameter.

  Skapa en lokal nuget.config-fil med bara det offentliga Microsoft NuGet-flödet och referera till den med parametern --configfile :

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

  Här är en exempelkonfigurationsfil:

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

  Mer information finns i referensen för nuget.config

• Lägg till nödvändiga autentiseringsuppgifter i konfigurationsfilen.

  Om du vet att paketet finns i den konfigurerade feeden anger du inloggningsuppgifterna i NuGet-konfigurationsfilen. Mer information om autentiseringsuppgifter i en nuget-konfigurationsfil finns i avsnittet om nuget.config-referensens packageSourceCredentials.

Se även

• .NET-verktyg