dotnet-local-tools

.NET Lokale Tools

Wann dieses Skill verwendet werden sollte

Verwenden Sie dieses Skill, wenn:

• Konsistente Werkzeuge über ein ganzes Entwicklungsteam hinweg eingerichtet werden sollen
• CI/CD-Pipelines die gleichen Tool-Versionen wie die lokale Entwicklung verwenden sollen
• Projekt-spezifische CLI-Tools (docfx, incrementalist, dotnet-ef, etc.) verwaltet werden sollen
• Konflikte zwischen verschiedenen Projekten durch global installierte Tools vermieden werden sollen

Was sind lokale Tools?

Lokale Tools sind .NET CLI-Tools, die pro Repository installiert und versioniert werden, anstatt global. Sie werden in .config/dotnet-tools.json definiert und mit dotnet tool restore wiederhergestellt.

Lokale vs. Globale Tools

Aspekt	Globale Tools	Lokale Tools
Installation	dotnet tool install -g	dotnet tool restore
Gültigkeitsbereich	Systemweit	Pro Repository
Versionskontrolle	Manuell	In .config/dotnet-tools.json
CI/CD	Muss jedes Tool installieren	Ein einziger Restore-Befehl
Konflikte	Kann Versionskonflikte geben	Pro Projekt isoliert

---

Lokale Tools einrichten

Das Manifest initialisieren

# Erstellen von .config/dotnet-tools.json
dotnet new tool-manifest

Dies erstellt:

.config/
└── dotnet-tools.json

Tools lokal installieren

# Ein Tool lokal installieren
dotnet tool install docfx

# Eine bestimmte Version installieren
dotnet tool install docfx --version 2.78.3

# Von einer bestimmten Quelle installieren
dotnet tool install MyTool --add-source https://mycompany.pkgs.visualstudio.com/_packaging/feed/nuget/v3/index.json

Tools wiederherstellen

# Alle Tools aus dem Manifest wiederherstellen
dotnet tool restore

---

dotnet-tools.json Format

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "docfx": {
      "version": "2.78.3",
      "commands": [
        "docfx"
      ],
      "rollForward": false
    },
    "dotnet-ef": {
      "version": "9.0.0",
      "commands": [
        "dotnet-ef"
      ],
      "rollForward": false
    },
    "incrementalist.cmd": {
      "version": "1.2.0",
      "commands": [
        "incrementalist"
      ],
      "rollForward": false
    },
    "dotnet-reportgenerator-globaltool": {
      "version": "5.4.1",
      "commands": [
        "reportgenerator"
      ],
      "rollForward": false
    }
  }
}

Felder

Feld	Beschreibung
version	Schema-Version des Manifests (immer 1)
isRoot	Markiert dies als Wurzelmanifest (verhindert die Suche in übergeordneten Verzeichnissen)
tools	Wörterbuch der Tool-Konfigurationen
tools.<name>.version	Exakte zu installierende Version
tools.<name>.commands	CLI-Befehle, die das Tool bereitstellt
tools.<name>.rollForward	Neuere Versionen zulassen (normalerweise false für Reproduzierbarkeit)

---

Häufig verwendete Tools

Dokumentation

# DocFX - API-Dokumentationsgenerator
dotnet tool install docfx

"docfx": {
  "version": "2.78.3",
  "commands": ["docfx"],
  "rollForward": false
}

Verwendung:

dotnet docfx docfx.json
dotnet docfx serve _site

Entity Framework Core

# EF Core CLI für Migrationen
dotnet tool install dotnet-ef

"dotnet-ef": {
  "version": "9.0.0",
  "commands": ["dotnet-ef"],
  "rollForward": false
}

Verwendung:

dotnet ef migrations add InitialCreate
dotnet ef database update

Code Coverage

# ReportGenerator für Coverage-Berichte
dotnet tool install dotnet-reportgenerator-globaltool

"dotnet-reportgenerator-globaltool": {
  "version": "5.4.1",
  "commands": ["reportgenerator"],
  "rollForward": false
}

Verwendung:

dotnet reportgenerator -reports:coverage.cobertura.xml -targetdir:coveragereport -reporttypes:Html

Inkrementelle Builds

# Incrementalist - nur geänderte Projekte bauen
dotnet tool install incrementalist.cmd

"incrementalist.cmd": {
  "version": "1.2.0",
  "commands": ["incrementalist"],
  "rollForward": false
}

Verwendung:

# Projekte abrufen, die seit dem Hauptbranch geändert wurden
incrementalist --branch main

Code-Formatierung

# CSharpier - meinungsstarker C#-Formatierer
dotnet tool install csharpier

"csharpier": {
  "version": "0.30.3",
  "commands": ["dotnet-csharpier"],
  "rollForward": false
}

Verwendung:

dotnet csharpier .
dotnet csharpier --check .  # CI-Modus - schlägt fehl, wenn Änderungen nötig

Code-Analyse

# JB dotnet-inspect (erfordert Lizenz)
dotnet tool install jb

"jb": {
  "version": "2024.3.4",
  "commands": ["jb"],
  "rollForward": false
}

---

CI/CD-Integration

GitHub Actions

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          global-json-file: global.json

      - name: Restore tools
        run: dotnet tool restore

      - name: Build
        run: dotnet build

      - name: Test with coverage
        run: dotnet test --collect:"XPlat Code Coverage"

      - name: Generate coverage report
        run: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coveragereport

      - name: Build documentation
        run: dotnet docfx docs/docfx.json

Azure Pipelines

steps:
  - task: UseDotNet@2
    inputs:
      useGlobalJson: true

  - script: dotnet tool restore
    displayName: '.NET-Tools wiederherstellen'

  - script: dotnet build -c Release
    displayName: 'Build'

  - script: dotnet test -c Release --collect:"XPlat Code Coverage"
    displayName: 'Test'

  - script: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:$(Build.ArtifactStagingDirectory)/coverage
    displayName: 'Coverage-Bericht generieren'

---

Tool-Versionen verwalten

Ein Tool aktualisieren

# Auf die neueste Version aktualisieren
dotnet tool update docfx

# Auf eine bestimmte Version aktualisieren
dotnet tool update docfx --version 2.79.0

Installierte Tools auflisten

# Lokale Tools auflisten
dotnet tool list

# Mit veralteter Prüfung auflisten
dotnet tool list --outdated

Ein Tool entfernen

dotnet tool uninstall docfx

---

Bewährte Methoden

1. Immer isRoot: true setzen

Verhindert, dass MSBuild in übergeordneten Verzeichnissen nach Tool-Manifesten sucht:

{
  "version": 1,
  "isRoot": true,
  ...
}

2. Exakte Versionen festlegen

Verwenden Sie "rollForward": false für reproduzierbare Builds:

"docfx": {
  "version": "2.78.3",
  "rollForward": false
}

3. Vor der Verwendung im CI wiederherstellen

Führen Sie immer dotnet tool restore aus, bevor Sie ein lokales Tool verwenden:

- run: dotnet tool restore
- run: dotnet docfx docs/docfx.json

4. Tool-Anforderungen dokumentieren

Fügen Sie einen Kommentar oder Abschnitt in der README hinzu:

## Entwicklungsumgebung einrichten

1. Tools wiederherstellen: `dotnet tool restore`
2. Build: `dotnet build`
3. Test: `dotnet test`

5. Dependabot für Updates verwenden

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    # Enthält lokale Tools in .config/dotnet-tools.json

---

Fehlerbehebung

Tool nach dem Wiederherstellen nicht gefunden

Stellen Sie sicher, dass Sie vom Repository-Stammverzeichnis aus arbeiten:

# Falsch - Ausführen aus einem Unterverzeichnis
cd src/MyApp
dotnet docfx  # Fehler: Tool nicht gefunden

# Richtig - Ausführung aus dem Lösungsstammverzeichnis
cd ../..
dotnet docfx docs/docfx.json

Versionskonflikte

Wenn Sie Versionskonflikte sehen, überprüfen Sie:

1. Globales Tool mit anderer Version: dotnet tool list -g
2. Mehrere Tool-Manifeste: Suchen Sie nach .config/dotnet-tools.json in übergeordneten Verzeichnissen

Tool-Cache leeren

# NuGet-Tool-Cache leeren
dotnet nuget locals all --clear

# Tools erneut wiederherstellen
dotnet tool restore

---

Beispiel: Vollständige Entwicklungsumgebung einrichten

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "docfx": {
      "version": "2.78.3",
      "commands": ["docfx"],
      "rollForward": false
    },
    "dotnet-ef": {
      "version": "9.0.0",
      "commands": ["dotnet-ef"],
      "rollForward": false
    },
    "dotnet-reportgenerator-globaltool": {
      "version": "5.4.1",
      "commands": ["reportgenerator"],
      "rollForward": false
    },
    "csharpier": {
      "version": "0.30.3",
      "commands": ["dotnet-csharpier"],
      "rollForward": false
    },
    "incrementalist.cmd": {
      "version": "1.2.0",
      "commands": ["incrementalist"],
      "rollForward": false
    }
  }
}

Entwicklungsworkflow:

# Initiale Einrichtung
dotnet tool restore

# Code vor dem Commit formatieren
dotnet csharpier .

# Tests mit Coverage ausführen
dotnet test --collect:"XPlat Code Coverage"
dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coverage

# Dokumentation erstellen
dotnet docfx docs/docfx.json

# Überprüfen, welche Projekte geändert wurden (für große Repos)
incrementalist --branch main