Ferramentas Locais do .NET
Quando Usar Esta Skill
Use esta skill quando:
- Configurando ferramentas consistentes em toda a equipe de desenvolvimento
- Garantindo que pipelines CI/CD usem as mesmas versões de ferramentas que o desenvolvimento local
- Gerenciando ferramentas CLI específicas de projeto (docfx, incrementalist, dotnet-ef, etc.)
- Evitando conflitos de versão de ferramentas globais entre projetos
O Que São Ferramentas Locais?
Ferramentas locais são ferramentas CLI do .NET que são instaladas e versionadas por repositório, em vez de globalmente. Elas são definidas em .config/dotnet-tools.json e restauradas com dotnet tool restore.
Ferramentas Locais vs Globais
| Aspecto | Ferramentas Globais | Ferramentas Locais |
|---|---|---|
| Instalação | dotnet tool install -g | dotnet tool restore |
| Escopo | Em toda a máquina | Por repositório |
| Controle de versão | Manual | Em .config/dotnet-tools.json |
| CI/CD | Deve instalar cada ferramenta | Um único comando restore |
| Conflitos | Pode ter conflitos de versão | Isolado por projeto |
Configurando Ferramentas Locais
Inicializar o Manifesto
# Criar .config/dotnet-tools.json
dotnet new tool-manifest
Isso cria:
.config/
└── dotnet-tools.json
Instalar Ferramentas Localmente
# Instalar uma ferramenta localmente
dotnet tool install docfx
# Instalar versão específica
dotnet tool install docfx --version 2.78.3
# Instalar de uma fonte específica
dotnet tool install MyTool --add-source https://mycompany.pkgs.visualstudio.com/_packaging/feed/nuget/v3/index.json
Restaurar Ferramentas
# Restaurar todas as ferramentas do manifesto
dotnet tool restore
Formato dotnet-tools.json
{
"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
}
}
}
Campos
| Campo | Descrição |
|---|---|
version | Versão do esquema do manifesto (sempre 1) |
isRoot | Marca este como o manifesto raiz (impede busca em diretórios pai) |
tools | Dicionário de configurações de ferramentas |
tools.<nome>.version | Versão exata a ser instalada |
tools.<nome>.commands | Comandos CLI que a ferramenta fornece |
tools.<nome>.rollForward | Permitir versões mais recentes (geralmente false para reprodutibilidade) |
Ferramentas Comuns
Documentação
# DocFX - Gerador de documentação de API
dotnet tool install docfx
"docfx": {
"version": "2.78.3",
"commands": ["docfx"],
"rollForward": false
}
Uso:
dotnet docfx docfx.json
dotnet docfx serve _site
Entity Framework Core
# CLI do EF Core para migrações
dotnet tool install dotnet-ef
"dotnet-ef": {
"version": "9.0.0",
"commands": ["dotnet-ef"],
"rollForward": false
}
Uso:
dotnet ef migrations add InitialCreate
dotnet ef database update
Cobertura de Código
# ReportGenerator para relatórios de cobertura
dotnet tool install dotnet-reportgenerator-globaltool
"dotnet-reportgenerator-globaltool": {
"version": "5.4.1",
"commands": ["reportgenerator"],
"rollForward": false
}
Uso:
dotnet reportgenerator -reports:coverage.cobertura.xml -targetdir:coveragereport -reporttypes:Html
Builds Incrementais
# Incrementalist - constrói apenas projetos alterados
dotnet tool install incrementalist.cmd
"incrementalist.cmd": {
"version": "1.2.0",
"commands": ["incrementalist"],
"rollForward": false
}
Uso:
# Obter projetos afetados por alterações desde o branch main
incrementalist --branch main
Formatação de Código
# CSharpier - Formatador opinativo de C#
dotnet tool install csharpier
"csharpier": {
"version": "0.30.3",
"commands": ["dotnet-csharpier"],
"rollForward": false
}
Uso:
dotnet csharpier .
dotnet csharpier --check . # Modo CI - falha se houver alterações necessárias
Análise de Código
# JB dotnet-inspect (requer licença)
dotnet tool install jb
"jb": {
"version": "2024.3.4",
"commands": ["jb"],
"rollForward": false
}
Integração com CI/CD
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: 'Restore .NET tools'
- 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: 'Generate coverage report'
Gerenciando Versões de Ferramentas
Atualizar uma Ferramenta
# Atualizar para a versão mais recente
dotnet tool update docfx
# Atualizar para uma versão específica
dotnet tool update docfx --version 2.79.0
Listar Ferramentas Instaladas
# Listar ferramentas locais
dotnet tool list
# Listar com verificação de desatualizadas
dotnet tool list --outdated
Remover uma Ferramenta
dotnet tool uninstall docfx
Melhores Práticas
1. Sempre Defina isRoot: true
Impede que o MSBuild procure por manifestos de ferramentas em diretórios pai:
{
"version": 1,
"isRoot": true,
...
}
2. Fixe Versões Exatas
Use "rollForward": false para builds reproduzíveis:
"docfx": {
"version": "2.78.3",
"rollForward": false
}
3. Restaure no CI Antes de Usar
Sempre execute dotnet tool restore antes de usar qualquer ferramenta local:
- run: dotnet tool restore
- run: dotnet docfx docs/docfx.json
4. Documente os Requisitos de Ferramentas
Adicione um comentário ou seção no README:
## Configuração de Desenvolvimento
1. Restaure as ferramentas: `dotnet tool restore`
2. Build: `dotnet build`
3. Teste: `dotnet test`
5. Use Dependabot para Atualizações
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "nuget"
directory: "/"
schedule:
interval: "weekly"
# Inclui ferramentas locais em .config/dotnet-tools.json
Solução de Problemas
Ferramenta Não Encontrada Após Restore
Certifique-se de que está executando a partir da raiz do repositório:
# Errado - executando de um subdiretório
cd src/MyApp
dotnet docfx # Erro: ferramenta não encontrada
# Correto - execute da raiz da solução
cd ../..
dotnet docfx docs/docfx.json
Conflitos de Versão
Se você encontrar conflitos de versão, verifique:
- Ferramenta global com versão diferente:
dotnet tool list -g - Múltiplos manifestos de ferramentas: Procure por
.config/dotnet-tools.jsonem diretórios pai
Limpando o Cache de Ferramentas
# Limpar cache de ferramentas NuGet
dotnet nuget locals all --clear
# Re-restaurar ferramentas
dotnet tool restore
Exemplo: Configuração Completa de Desenvolvimento
{
"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
}
}
}
Fluxo de trabalho de desenvolvimento:
# Configuração inicial
dotnet tool restore
# Formatar código antes do commit
dotnet csharpier .
# Executar testes com cobertura
dotnet test --collect:"XPlat Code Coverage"
dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coverage
# Construir documentação
dotnet docfx docs/docfx.json
# Verificar quais projetos mudaram (para repositórios grandes)
incrementalist --branch main