.NET-hulpprogramma's beheren

  • Artikel
  • 8 minuten om te lezen

Dit artikel is van toepassing op: ✔️ .NET Core 2.1 SDK en latere versies

Een .NET-hulpprogramma is een speciaal NuGet-pakket dat een consoletoepassing bevat. Een hulpprogramma kan op de volgende manieren op uw computer worden geïnstalleerd:

  • Als een globaal hulpprogramma.

    De binaire bestanden van het hulpprogramma worden geïnstalleerd in een standaardmap die wordt toegevoegd aan de omgevingsvariabele PATH. U kunt het hulpprogramma aanroepen vanuit elke map op de computer zonder de locatie op te geven. Eén versie van een hulpprogramma wordt gebruikt voor alle mappen op de computer.

  • Als een globaal hulpprogramma op een aangepaste locatie (ook wel een hulpprogramma voor hulpprogrammapad genoemd).

    De binaire bestanden van het hulpprogramma worden geïnstalleerd op een locatie die u opgeeft. U kunt het hulpprogramma aanroepen vanuit de installatiemap of door de map de opdrachtnaam op te geven of door de map toe te voegen aan de omgevingsvariabele PATH. Eén versie van een hulpprogramma wordt gebruikt voor alle mappen op de computer.

  • Als lokaal hulpprogramma (van toepassing op .NET Core SDK 3.0 en hoger).

    De binaire bestanden van het hulpprogramma worden geïnstalleerd in een standaardmap. U roept het hulpprogramma aan vanuit de installatiemap of een van de bijbehorende submappen. Verschillende mappen kunnen verschillende versies van hetzelfde hulpprogramma gebruiken.

    De .NET CLI maakt gebruik van manifestbestanden om bij te houden welke hulpprogramma's zijn geïnstalleerd als lokaal in een map. Wanneer het manifestbestand wordt opgeslagen in de hoofdmap van een opslagplaats met broncode, kan een inzender de opslagplaats klonen en één .NET CLI-opdracht aanroepen waarmee alle hulpprogramma's worden geïnstalleerd die worden vermeld in de manifestbestanden.

Belangrijk

.NET-hulpprogramma's worden volledig vertrouwd uitgevoerd. Installeer geen .NET-hulpprogramma tenzij u de auteur vertrouwt.

Een hulpprogramma zoeken

Hier volgen enkele manieren om hulpprogramma's te vinden:

De auteur en statistieken controleren

Omdat .NET-hulpprogramma's volledig vertrouwen hebben en globale hulpprogramma's worden toegevoegd aan de omgevingsvariabele PATH, kunnen ze zeer krachtig zijn. Download geen hulpprogramma's van personen die u niet vertrouwt.

Als het hulpprogramma wordt gehost op NuGet, kunt u de auteur en statistieken controleren door naar het hulpprogramma te zoeken.

Een algemeen hulpprogramma installeren

Als u een hulpprogramma wilt installeren als een globaal hulpprogramma, gebruikt u de -g of --global optie voor het installeren van dotnet-hulpprogramma's, zoals wordt weergegeven in het volgende voorbeeld:

dotnet tool install -g dotnetsay

De uitvoer toont de opdracht die wordt gebruikt om het hulpprogramma aan te roepen en de geïnstalleerde versie, vergelijkbaar met het volgende voorbeeld:

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

De standaardlocatie voor binaire bestanden van een hulpprogramma is afhankelijk van het besturingssysteem:

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

Deze locatie wordt toegevoegd aan het pad van de gebruiker wanneer de SDK voor het eerst wordt uitgevoerd, zodat globale hulpprogramma's vanuit elke map kunnen worden aangeroepen zonder de locatie van het hulpprogramma op te geven.

Toegang tot hulpprogramma's is gebruikersspecifiek, niet algemeen. Een algemeen hulpprogramma is alleen beschikbaar voor de gebruiker die het hulpprogramma heeft geïnstalleerd.

Een globaal hulpprogramma installeren op een aangepaste locatie

Als u een hulpprogramma wilt installeren als een globaal hulpprogramma op een aangepaste locatie, gebruikt u de --tool-path optie voor het installeren van dotnet-hulpprogramma's, zoals wordt weergegeven in de volgende voorbeelden.

In Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

In Linux of macOS:

dotnet tool install dotnetsay --tool-path ~/bin

De .NET SDK voegt deze locatie niet automatisch toe aan de omgevingsvariabele PATH. Als u een hulpprogramma voor het pad naar een hulpprogramma wilt aanroepen, moet u ervoor zorgen dat de opdracht beschikbaar is met een van de volgende methoden:

  • Voeg de installatiemap toe aan de omgevingsvariabele PATH.
  • Geef het volledige pad naar het hulpprogramma op wanneer u het aanroept.
  • Roep het hulpprogramma aan vanuit de installatiemap.

Een lokaal hulpprogramma installeren

Van toepassing op .NET Core 3.0 SDK en hoger.

Als u alleen een hulpprogramma voor lokale toegang wilt installeren (voor de huidige map en submappen), moet het worden toegevoegd aan een manifestbestand van het hulpprogramma. Voer de opdracht uit om een manifestbestand voor het dotnet new tool-manifest hulpprogramma te maken:

dotnet new tool-manifest

Met deze opdracht maakt u een manifestbestand met de naam dotnet-tools.json onder de map.config . Als u een lokaal hulpprogramma wilt toevoegen aan het manifestbestand, gebruikt u de opdracht voor het installeren van het dotnet-hulpprogramma en laat u de --global opties weg --tool-path , zoals wordt weergegeven in het volgende voorbeeld:

dotnet tool install dotnetsay

In de uitvoer van de opdracht ziet u in welk manifestbestand het zojuist geïnstalleerde hulpprogramma zich bevindt, vergelijkbaar met het volgende voorbeeld:

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

In het volgende voorbeeld ziet u een manifestbestand waarop twee lokale hulpprogramma's zijn geïnstalleerd:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Meestal voegt u een lokaal hulpprogramma toe aan de hoofdmap van de opslagplaats. Nadat u het manifestbestand naar de opslagplaats hebt ingecheckt, krijgen ontwikkelaars die code uit de opslagplaats uitchecken het meest recente manifestbestand. Als u alle hulpprogramma's wilt installeren die worden vermeld in het manifestbestand, voeren ze de dotnet tool restore opdracht uit:

dotnet tool restore

De uitvoer geeft aan welke hulpprogramma's zijn hersteld:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Een specifieke versie van het hulpprogramma installeren

Als u een voorlopige versie of een specifieke versie van een hulpprogramma wilt installeren, geeft u het versienummer op met behulp van de --version optie, zoals wordt weergegeven in het volgende voorbeeld:

dotnet tool install dotnetsay --version 2.1.3

Als u een voorlopige versie van het hulpprogramma wilt installeren zonder het exacte versienummer op te geven, gebruikt u de --version optie en geeft u een jokerteken op, zoals wordt weergegeven in het volgende voorbeeld:

dotnet tool install --global dotnetsay --version "*-rc*"

Een hulpprogramma gebruiken

De opdracht die u gebruikt om een hulpprogramma aan te roepen, kan afwijken van de naam van het pakket dat u installeert. Als u alle hulpprogramma's wilt weergeven die momenteel op de computer voor de huidige gebruiker zijn geïnstalleerd, gebruikt u de opdracht voor de lijst met dotnet-hulpprogramma's :

dotnet tool list

De uitvoer toont de versie en opdracht van elk hulpprogramma, vergelijkbaar met het volgende voorbeeld:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Zoals in dit voorbeeld wordt weergegeven, worden in de lijst lokale hulpprogramma's weergegeven. Als u algemene hulpprogramma's wilt zien, gebruikt u de --global optie en gebruikt u de --tool-path optie om hulpprogramma's voor hulpprogramma's weer te geven.

Een algemeen hulpprogramma aanroepen

Gebruik voor globale hulpprogramma's zelf de opdracht tool. Als de opdracht bijvoorbeeld is dotnetsay of dotnet-doc, gebruikt u de opdracht om de opdracht aan te roepen:

dotnetsay
dotnet-doc

Als de opdracht begint met het voorvoegsel dotnet-, kunt u het hulpprogramma ook aanroepen door de dotnet opdracht te gebruiken en het opdrachtvoorvoegsel van het hulpprogramma weg te laten. Als de opdracht bijvoorbeeld is dotnet-doc, roept de volgende opdracht het hulpprogramma aan:

dotnet doc

In het volgende scenario kunt u de dotnet opdracht echter niet gebruiken om een globaal hulpprogramma aan te roepen:

  • Een globaal hulpprogramma en een lokaal hulpprogramma hebben dezelfde opdracht voorafgegaan door dotnet-.
  • U wilt het globale hulpprogramma aanroepen vanuit een map die binnen het bereik van het lokale hulpprogramma valt.

In dit scenario dotnet doc en dotnet dotnet-doc roept u het lokale hulpprogramma aan. Als u het globale hulpprogramma wilt aanroepen, gebruikt u de opdracht zelf:

dotnet-doc

Een hulpprogramma voor hulpprogrammapad aanroepen

Als u een globaal hulpprogramma wilt aanroepen dat is geïnstalleerd met behulp van de tool-path optie, moet u ervoor zorgen dat de opdracht beschikbaar is, zoals eerder in dit artikel is uitgelegd.

Een lokaal hulpprogramma aanroepen

Als u een lokaal hulpprogramma wilt aanroepen, moet u de dotnet opdracht vanuit de installatiemap gebruiken. U kunt het lange formulier () of het korte formulier () gebruiken,dotnet tool run <COMMAND_NAME>dotnet <COMMAND_NAME> zoals wordt weergegeven in de volgende voorbeelden:

dotnet tool run dotnetsay
dotnet dotnetsay

Als de opdracht wordt voorafgegaan door dotnet-, kunt u het voorvoegsel opnemen of weglaten wanneer u het hulpprogramma aanroept. Als de opdracht bijvoorbeeld is dotnet-doc, roept een van de volgende voorbeelden het lokale hulpprogramma aan:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Een hulpprogramma bijwerken

Het bijwerken van een hulpprogramma omvat het verwijderen en opnieuw installeren met de nieuwste stabiele versie. Als u een hulpprogramma wilt bijwerken, gebruikt u de opdracht voor het bijwerken van het dotnet-hulpprogramma met dezelfde optie die u hebt gebruikt om het hulpprogramma te installeren:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Voor een lokaal hulpprogramma vindt de SDK het eerste manifestbestand dat de pakket-id bevat door te zoeken in de huidige map en bovenliggende mappen. Als er geen dergelijke pakket-id in een manifestbestand staat, voegt de SDK een nieuwe vermelding toe aan het dichtstbijzijnde manifestbestand.

Een hulpprogramma verwijderen

Verwijder een hulpprogramma met behulp van de opdracht dotnet tool uninstall met dezelfde optie die u hebt gebruikt om het hulpprogramma te installeren:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Voor een lokaal hulpprogramma vindt de SDK het eerste manifestbestand dat de pakket-id bevat door te zoeken in de huidige map en bovenliggende mappen.

Hulp krijgen en problemen oplossen

Als een hulpprogramma niet kan worden geïnstalleerd of uitgevoerd, raadpleegt u Problemen met het gebruik van .NET-hulpprogramma's oplossen. U kunt een lijst met beschikbare dotnet tool opdrachten en parameters ophalen met behulp van de --help parameter:

dotnet tool --help

Als u gebruiksinstructies voor hulpprogramma's wilt ophalen, voert u een van de volgende opdrachten in of bekijkt u de website van het hulpprogramma:

<command> --help
dotnet <command> --help

Zie ook