Problemen met het gebruik van .NET-hulpprogramma's oplossen

  • Artikel

Er kunnen problemen optreden bij het installeren of uitvoeren van een .NET-hulpprogramma. Dit kan een algemeen hulpprogramma of een lokaal hulpprogramma zijn. In dit artikel worden de veelvoorkomende hoofdoorzaken en enkele mogelijke oplossingen beschreven.

Het geïnstalleerde .NET-hulpprogramma kan niet worden uitgevoerd

Wanneer een .NET-hulpprogramma niet kan worden uitgevoerd, is er waarschijnlijk een van de volgende problemen opgetreden:

Uitvoerbaar bestand is niet gevonden

Als het uitvoerbare bestand niet wordt gevonden, ziet u een bericht dat er ongeveer als volgt uitziet:

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.

De naam van het uitvoerbare bestand bepaalt hoe u het hulpprogramma aanroept. In de volgende tabel wordt de indeling beschreven:

Indeling van uitvoerbare naam Aanroepindeling
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Algemene hulpprogramma's

Globale hulpprogramma's kunnen worden geïnstalleerd in de standaardmap of op een specifieke locatie. De standaardmappen zijn:

Besturingssysteem Pad
Linux/macOS $HOME/.dotnet/tools
Vensters %USERPROFILE%\.dotnet\tools

Als u een globaal hulpprogramma probeert uit te voeren, controleert u of de PATH omgevingsvariabele op uw computer het pad bevat waar u het globale hulpprogramma hebt geïnstalleerd en of het uitvoerbare bestand zich in dat pad bevindt.

De .NET CLI probeert de standaardlocatie toe te voegen aan de omgevingsvariabele PATH bij het eerste gebruik. Er zijn echter enkele scenario's waarin de locatie mogelijk niet automatisch wordt toegevoegd aan PATH:

  • Als u Linux gebruikt en u de .NET SDK hebt geïnstalleerd met .tar.gz-bestanden en niet apt-get of rpm.
  • Als u macOS 10.15 'Catalina' of nieuwere versies gebruikt.
  • Als u macOS 10.14 Mojave of eerdere versies gebruikt en u de .NET SDK hebt geïnstalleerd met .tar.gz-bestanden en niet .pkg.
  • Als u de .NET Core 3.0 SDK hebt geïnstalleerd en u de DOTNET_ADD_GLOBAL_TOOLS_TO_PATH omgevingsvariabele hebt ingesteld op false.
  • Als u .NET Core 2.2 SDK of eerdere versies hebt geïnstalleerd en u de DOTNET_SKIP_FIRST_TIME_EXPERIENCE omgevingsvariabele hebt ingesteld op true.

In deze scenario's of als u de optie hebt opgegeven tijdens het --tool-path installeren van een dotnet-hulpprogramma, bevat de PATH omgevingsvariabele op uw computer niet automatisch het pad waar u het globale hulpprogramma hebt geïnstalleerd. Voeg in dat geval de locatie van het hulpprogramma (bijvoorbeeld $HOME/.dotnet/tools) toe aan de PATH omgevingsvariabele met behulp van de methode die uw shell biedt voor het bijwerken van omgevingsvariabelen. Zie .NET-hulpprogramma's voor meer informatie.

Lokale hulpprogramma's

Als u een lokaal hulpprogramma probeert uit te voeren, controleert u of er een manifestbestand met de naam dotnet-tools.json in de huidige map of een van de bovenliggende mappen staat. Dit bestand kan ook worden uitgevoerd onder een map met de naam .config , overal in de projectmaphiërarchie, in plaats van de hoofdmap. Als dotnet-tools.json bestaat, opent u deze en controleert u het hulpprogramma dat u probeert uit te voeren. Als het bestand geen vermelding "isRoot": truevoor bevat, controleert u ook de bestandshiërarchie verder op aanvullende manifestbestanden voor hulpprogramma's.

Als u probeert een .NET-hulpprogramma uit te voeren dat is geïnstalleerd met een opgegeven pad, moet u dat pad opnemen wanneer u het hulpprogramma gebruikt. Een voorbeeld van het gebruik van een hulpprogrammapad dat is geïnstalleerd, is:

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

Runtime is niet gevonden

.NET-hulpprogramma's zijn frameworkafhankelijke toepassingen, wat betekent dat ze afhankelijk zijn van een .NET-runtime die op uw computer is geïnstalleerd. Als de verwachte runtime niet wordt gevonden, volgen ze normale roll-forwardregels voor .NET-runtime, zoals:

  • Een toepassing wordt doorgestuurd naar de hoogste patchrelease van de opgegeven primaire en secundaire versie.
  • Als er geen overeenkomende runtime is met een overeenkomend primaire en secundair versienummer, wordt de volgende hogere secundaire versie gebruikt.
  • Roll forward vindt niet plaats tussen preview-versies van de runtime of tussen preview-versies en releaseversies. Daarom moeten .NET-hulpprogramma's die zijn gemaakt met preview-versies opnieuw worden opgebouwd en opnieuw worden gepubliceerd door de auteur en opnieuw worden geïnstalleerd.

Roll-forward vindt niet standaard plaats in twee veelvoorkomende scenario's:

  • Alleen lagere versies van de runtime zijn beschikbaar. Roll-forward selecteert alleen latere versies van de runtime.
  • Alleen hogere primaire versies van de runtime zijn beschikbaar. Roll-forward overschrijdt geen primaire versiegrenzen.

Als een toepassing geen geschikte runtime kan vinden, kan deze niet worden uitgevoerd en wordt er een fout gerapporteerd.

U kunt zien welke .NET-runtimes op uw computer zijn geïnstalleerd met behulp van een van de volgende opdrachten:

dotnet --list-runtimes
dotnet --info

Als u denkt dat het hulpprogramma ondersteuning moet bieden voor de runtimeversie die u momenteel hebt geïnstalleerd, kunt u contact opnemen met de auteur van het hulpprogramma en kijken of ze het versienummer of het multidoel kunnen bijwerken. Nadat ze het hulpprogrammapakket opnieuw hebben gecompileerd en opnieuw hebben gepubliceerd naar NuGet met een bijgewerkt versienummer, kunt u uw kopie bijwerken. Hoewel dat niet gebeurt, is de snelste oplossing om een versie van de runtime te installeren die zou werken met het hulpprogramma dat u probeert uit te voeren. Als u een specifieke .NET Runtime-versie wilt downloaden, gaat u naar de .NET-downloadpagina.

Als u de .NET SDK op een niet-standaardlocatie installeert, moet u de omgevingsvariabele DOTNET_ROOT instellen op de map die het dotnet uitvoerbare bestand bevat.

Installatie van .NET-hulpprogramma mislukt

Er zijn een aantal redenen waarom de installatie van een algemeen of lokaal .NET-hulpprogramma kan mislukken. Wanneer de installatie van het hulpprogramma mislukt, ziet u een bericht dat lijkt op de volgende:

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

Om deze fouten vast te stellen, worden NuGet-berichten rechtstreeks aan de gebruiker weergegeven, samen met het vorige bericht. Het NuGet-bericht kan u helpen bij het identificeren van het probleem.

Afdwingen van pakketnamen

Microsoft heeft de richtlijnen voor de pakket-id voor hulpprogramma's gewijzigd, wat resulteert in een aantal hulpprogramma's die niet worden gevonden met de voorspelde naam. De nieuwe richtlijnen zijn dat alle Microsoft-hulpprogramma's worden voorafgegaan door 'Microsoft'. Dit voorvoegsel is gereserveerd en kan alleen worden gebruikt voor pakketten die zijn ondertekend met een door Microsoft geautoriseerd certificaat.

Tijdens de overgang hebben sommige Microsoft-hulpprogramma's de oude vorm van de pakket-id, terwijl anderen het nieuwe formulier hebben:

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

Wanneer pakket-id's worden bijgewerkt, moet u overschakelen naar de nieuwe pakket-id om de meest recente updates op te halen. Pakketten met de vereenvoudigde hulpprogrammanaam worden afgeschaft.

Voorlopige versies

  • U probeert een preview-versie te installeren en u hebt de --version optie niet gebruikt om de versie op te geven.

.NET-hulpprogramma's die in preview zijn, moeten worden opgegeven met een deel van de naam om aan te geven dat ze in preview zijn. U hoeft de volledige preview niet op te nemen. Ervan uitgaande dat de versienummers de verwachte indeling hebben, kunt u iets als in het volgende voorbeeld gebruiken:

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

Pakket is geen .NET-hulpprogramma

  • Er is een NuGet-pakket met deze naam gevonden, maar het was geen .NET-hulpprogramma.

Als u probeert een NuGet-pakket te installeren dat een normaal NuGet-pakket is en geen .NET-hulpprogramma, ziet u een foutbericht dat lijkt op het volgende:

NU1212: Ongeldige combinatie van projectpakketten voor <toolName>. De projectstijl DotnetToolReference kan alleen verwijzingen van het DotnetTool-type bevatten.

NuGet-feed kan niet worden geopend

  • De vereiste NuGet-feed kan niet worden geopend, mogelijk vanwege een internetverbindingsprobleem.

Installatie van hulpprogramma's vereist toegang tot de NuGet-feed die het hulpprogrammapakket bevat. Dit mislukt als de feed niet beschikbaar is. U kunt feeds wijzigen met nuget.config, een specifiek nuget.config bestand aanvragen of extra feeds opgeven met de --add-source switch. Standaard genereert NuGet een fout voor elke feed die geen verbinding kan maken. De vlag --ignore-failed-sources kan deze niet-bereikbaar bronnen overslaan.

Pakket-id onjuist

  • U hebt de naam van het hulpprogramma verkeerd getypt.

Een veelvoorkomende reden voor een fout is dat de naam van het hulpprogramma niet juist is. Dit kan gebeuren vanwege mistyping, of omdat het gereedschap is verplaatst of afgeschaft. Voor hulpprogramma's op NuGet.org kunt u er op één manier voor zorgen dat u de juiste naam hebt om te zoeken naar het hulpprogramma op NuGet.org en de installatieopdracht te kopiëren.

401 (Niet geautoriseerd)

Waarschijnlijk hebt u een alternatieve NuGet-feed opgegeven en die feed vereist verificatie. U kunt dit op verschillende manieren oplossen:

  • Voeg de --ignore-failed-sources parameter toe om de fout uit de privéfeed te omzeilen en gebruik de openbare Microsoft-feed.

    Als u een hulpprogramma installeert vanuit de Microsoft NuGet-feed, retourneert uw aangepaste feed deze fout voordat de NuGet-feed van Microsoft een resultaat retourneert. De fout beëindigt de aanvraag en annuleert alle andere in behandeling zijnde feedaanvragen. Dit kan de NuGet-feed van Microsoft zijn. Als u de --ignore-failed-sources optie toevoegt, wordt deze fout als waarschuwing behandeld en kunnen andere feeds de aanvraag verwerken.

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

  • Forceer de Microsoft NuGet-feed met de --add-source parameter.

    Het is mogelijk dat het globale of lokale NuGet-configuratiebestand de openbare Microsoft NuGet-feed mist. Gebruik een combinatie van de --add-source en --ignore-failed-sources parameters om de onjuiste feed te voorkomen en te vertrouwen op de openbare Microsoft-feed.

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

  • Gebruik een aangepaste NuGet-configuratie, --configfile <FILE> parameter.

    Maak een lokaal nuget.config-bestand met alleen de openbare Microsoft NuGet-feed en verwijs ernaar met de --configfile parameter:

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

    Hier volgt een voorbeeld van een configuratiebestand:

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

    Zie nuget.config-naslaginformatie voor meer informatie

  • Voeg de vereiste referenties toe aan het configuratiebestand.

    Als u weet dat het pakket bestaat in de geconfigureerde feed, geeft u de aanmeldingsreferenties op in het NuGet-configuratiebestand. Zie de sectie packageSourceCredentials van de nuget.config-verwijzing voor meer informatie over referenties in een nuget-configuratiebestand.

Zie ook