.NET-hulpprogramma's beheren

  • Artikel

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. U kunt op de volgende manieren een hulpprogramma op uw computer installeren:

  • Als globale tool.

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

  • Als een algemeen 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 door de map met 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 een lokaal hulpprogramma (van toepassing op .NET Core SDK 3.0 en latere versies).

    De binaire bestanden van het hulpprogramma worden geïnstalleerd in een standaardmap. U kunt het hulpprogramma aanroepen 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 hulpprogramma's bij te houden die 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 om alle hulpprogramma's in de manifestbestanden te installeren.

Belangrijk

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

.NET-hulpprogramma's werken mogelijk niet correct als .NET is geïnstalleerd via Snap.

Een hulpprogramma zoeken

Hier volgen enkele manieren om hulpprogramma's te vinden:

De auteur en statistieken controleren

.NET-hulpprogramma's kunnen krachtig zijn omdat ze in volledig vertrouwen worden uitgevoerd en globale hulpprogramma's worden toegevoegd aan de omgevingsvariabele PATH. 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 algemeen 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

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

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

Notitie

De architectuur van de binaire .NET-bestanden die moeten worden geïnstalleerd, vertegenwoordigt standaard de huidige besturingssysteemarchitectuur. Als u een andere besturingssysteemarchitectuur wilt opgeven, raadpleegt u de optie dotnet tool install, --arch.

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

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

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

Toegang tot hulpprogramma's is gebruikersspecifiek, niet machine global. 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 algemeen 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 hulpprogrammapaden wilt aanroepen, moet u ervoor zorgen dat de opdracht beschikbaar is met behulp van 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

Is 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 u het hulpprogramma toevoegen aan een manifestbestand voor het hulpprogramma. Voer de dotnet new tool-manifest opdracht uit om een manifestbestand voor het 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 en --tool-path opties weg, 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 aanwezig is, 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 hebt ingecheckt bij de opslagplaats, 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 de herstelde hulpprogramma's aan:

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 dotnet tool list :

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 het vorige voorbeeld wordt weergegeven, worden in de lijst lokale hulpprogramma's weergegeven. Als u algemene hulpprogramma's wilt zien, gebruikt u de --global optie. Als u hulpprogramma's voor het hulpprogrammapad wilt zien, gebruikt u de --tool-path optie.

Als u een specifiek hulpprogramma wilt weergeven, gebruikt u de opdracht dotnet tool list <PACKAGE_ID> opdracht:

dotnet tool list dotnetsay

In de uitvoer wordt alleen dat hulpprogramma weergegeven als het is geïnstalleerd, vergelijkbaar met het volgende voorbeeld:

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

Een globaal hulpprogramma aanroepen

Voor globale hulpprogramma's gebruikt u de opdracht hulpprogramma zelf. Als de opdracht bijvoorbeeld is dotnetsay of dotnet-doc, gebruikt u om het globale hulpprogramma 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 echter niet de dotnet opdracht gebruiken om een algemeen hulpprogramma aan te roepen:

  • Een algemeen 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 algemene hulpprogramma wilt aanroepen, gebruikt u de opdracht zelf:

dotnet-doc

Een hulpprogramma voor hulpprogrammapad aanroepen

Als u een algemeen 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 (dotnet tool run <COMMAND_NAME>) gebruiken,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 dotnet tool update 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 zoekt de SDK in de huidige map en bovenliggende mappen naar het eerste manifestbestand met de pakket-id. Als er geen dergelijke pakket-id aanwezig is in een manifestbestand, 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 zoekt de SDK in de huidige map en bovenliggende mappen naar het eerste manifestbestand met de pakket-id.

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 het hulpprogramma 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