.NET-hulpprogramma's beheren

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

  • Als een globaal hulpmiddel.

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

  • Als een globaal hulpprogramma op een aangepaste locatie (ook wel een tool-path-tool 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. Er wordt één versie van een hulpprogramma 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 submappen. Verschillende mappen kunnen verschillende versies van hetzelfde hulpprogramma gebruiken.

    De .NET CLI gebruikt manifestbestanden om hulpprogramma's bij te houden die als lokaal zijn geïnstalleerd in een map. Wanneer het manifestbestand wordt opgeslagen in de hoofdmap van een broncodeopslagplaats, 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 een .NET-hulpprogramma alleen als u de auteur vertrouwt.

.NET-hulpprogramma's werken mogelijk niet goed als .NET is geïnstalleerd via Vastmaken.

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 path-omgevingsvariabele. 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 te zoeken naar het hulpprogramma.

Een globaal hulpprogramma installeren

Als u een hulpprogramma wilt installeren als een algemeen hulpprogramma, gebruikt u de -g optie of --globalvan dotnet-hulpprogramma installeren, 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 de 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. Globale hulpprogramma's kunnen dus worden aangeroepen vanuit elke map zonder de locatie van het hulpprogramma op te geven.

Toegang tot hulpprogramma's is gebruikersspecifiek, niet machine-globaal. 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 dotnet-hulpprogramma installeren, 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 het hulpprogramma 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

Van toepassing op .NET Core 3.0 SDK en hoger.

Als u een hulpprogramma alleen voor lokale toegang wilt installeren (voor de huidige map en submappen), moet u het hulpprogramma toevoegen aan een manifestbestand van 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 in de map.config . Als u een lokaal hulpprogramma wilt toevoegen aan het manifestbestand, gebruikt u de opdracht dotnet-hulpprogramma installeren en laat u de --global opties en --tool-path 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 met twee lokale hulpprogramma's 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 bij de opslagplaats hebt ingecheckt, krijgen ontwikkelaars die code uitchecken uit de opslagplaats het meest recente manifestbestand. Als u alle hulpprogramma's wilt installeren die in het manifestbestand worden vermeld, voert u de volgende opdracht uit dotnet tool restore :

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 zijn geïnstalleerd voor de huidige gebruiker, gebruikt u de opdracht dotnet-hulpprogrammalijst :

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, bevat de lijst lokale hulpprogramma's. Gebruik de --global optie om globale hulpprogramma's weer te geven. Gebruik de --tool-path optie om hulpprogramma's voor pad naar hulpprogramma's weer te geven.

Een algemeen hulpprogramma aanroepen

Voor globale hulpprogramma's gebruikt u de opdracht voor het hulpprogramma zelf. Als de opdracht bijvoorbeeld of dotnet-docisdotnetsay, gebruikt u dat 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 voorvoegsel van de opdracht van het hulpprogramma weg te laten. Als de opdracht bijvoorbeeld is, wordt dotnet-docmet de volgende opdracht het hulpprogramma aangeroepen:

dotnet doc

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

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

In dit scenario dotnet docdotnet 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 het pad naar het hulpprogramma 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 gebruiken vanuit de installatiemap. U kunt de lange vorm (dotnet tool run <COMMAND_NAME>) of de korte vorm () 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, roept dotnet-doceen 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 de bovenliggende mappen naar het eerste manifestbestand met de pakket-id. Als een manifestbestand geen dergelijke pakket-id bevat, 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 de 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 instructies voor het gebruik van het hulpprogramma wilt ophalen, voert u een van de volgende opdrachten in of gaat u naar de website van het hulpprogramma:

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

Zie ook