.NET / C# - Entorno de Desarrollo¶

Guía completa para configurar un entorno de desarrollo .NET que permita a Claude Code trabajar eficazmente.

Requisitos del Sistema¶

Componente	Versión Mínima	Recomendada
.NET SDK	8.0	9.0 (latest)
Visual Studio	2022	2022 17.8+
VS Code	1.80+	Latest
Windows	10	11
macOS	12 (Monterey)	14 (Sonoma)
Linux	Ubuntu 22.04	Ubuntu 24.04

Instalación del SDK¶

Windows¶

# Opción 1: Winget (recomendado)
winget install Microsoft.DotNet.SDK.9

# Opción 2: Chocolatey
choco install dotnet-sdk

# Opción 3: Descarga directa
# https://dotnet.microsoft.com/download

# Verificar instalación
dotnet --version
dotnet --list-sdks

macOS¶

# Homebrew
brew install dotnet-sdk

# Verificar
dotnet --version
dotnet --list-sdks

Linux (Ubuntu/Debian)¶

# Añadir repositorio de Microsoft
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# Instalar SDK
sudo apt update
sudo apt install -y dotnet-sdk-9.0

# Verificar
dotnet --version

Herramientas CLI Esenciales¶

Entity Framework Core Tools¶

# Instalar globalmente
dotnet tool install --global dotnet-ef

# Actualizar si ya está instalado
dotnet tool update --global dotnet-ef

# Verificar
dotnet ef --version

# Comandos comunes que Claude Code usará:
dotnet ef migrations add NombreMigracion
dotnet ef database update
dotnet ef migrations script
dotnet ef dbcontext scaffold "ConnectionString" Npgsql.EntityFramework.PostgreSQL

Otras Herramientas Globales Útiles¶

# Formateo de código
dotnet tool install --global dotnet-format

# Análisis de código
dotnet tool install --global dotnet-outdated-tool

# Generador de reportes de cobertura
dotnet tool install --global dotnet-reportgenerator-globaltool

# HTTPS Dev Certs
dotnet dev-certs https --trust

# User Secrets
dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:Default" "Host=localhost;..."

# Listar todas las herramientas instaladas
dotnet tool list --global

IDEs y Extensiones¶

Visual Studio 2022 (Windows - Recomendado)¶

# Instalar con winget
winget install Microsoft.VisualStudio.2022.Professional

# Workloads recomendados durante instalación:
# - ASP.NET and web development
# - .NET desktop development
# - Data storage and processing
# - Azure development (opcional)

Extensiones recomendadas:

CodeMaid - Limpieza y formateo de código
Roslynator - Análisis estático
GitHub Extension - Integración Git
SQLite/SQL Server Compact Toolbox
Productivity Power Tools

Visual Studio Code¶

# Instalar VS Code
winget install Microsoft.VisualStudioCode  # Windows
brew install --cask visual-studio-code     # macOS

# Extensiones obligatorias
code --install-extension ms-dotnettools.csharp
code --install-extension ms-dotnettools.csdevkit

# Extensiones recomendadas
code --install-extension ms-dotnettools.vscode-dotnet-runtime
code --install-extension kreativ-software.csharpextensions
code --install-extension jchannon.csharpextensions
code --install-extension fernandoescolar.vscode-solution-explorer
code --install-extension patcx.vscode-nuget-gallery

# Para trabajar con bases de datos
code --install-extension mtxr.sqltools
code --install-extension mtxr.sqltools-driver-pg
code --install-extension mtxr.sqltools-driver-mysql

JetBrains Rider (Alternativa multiplataforma)¶

# Windows
winget install JetBrains.Rider

# macOS
brew install --cask rider

# Incluye soporte nativo para:
# - Entity Framework
# - NuGet
# - Docker
# - Bases de datos

Bases de Datos¶

PostgreSQL (Recomendado para .NET)¶

# Windows
winget install PostgreSQL.PostgreSQL

# Añadir al PATH (PowerShell profile)
$env:PATH += ";C:\Program Files\PostgreSQL\16\bin"

# Crear base de datos de desarrollo
psql -U postgres -c "CREATE DATABASE myapp_dev;"
psql -U postgres -c "CREATE USER myapp WITH PASSWORD 'dev123';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE myapp_dev TO myapp;"

Connection String para Entity Framework:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=myapp_dev;Username=myapp;Password=dev123"
  }
}

Paquetes NuGet necesarios:

dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL.Design

SQL Server (LocalDB para desarrollo)¶

# Instalar SQL Server Express LocalDB
winget install Microsoft.SQLServer.2022.Express

# O solo LocalDB (más ligero)
# Se instala con Visual Studio

# Verificar instancias
sqllocaldb info

# Crear instancia
sqllocaldb create "MSSQLLocalDB"
sqllocaldb start "MSSQLLocalDB"

Connection String:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=MyAppDb;Trusted_Connection=True;"
  }
}

Paquetes NuGet:

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

SQLite (Para desarrollo rápido)¶

# No requiere servidor - solo el paquete NuGet
dotnet add package Microsoft.EntityFrameworkCore.Sqlite

Connection String:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=myapp.db"
  }
}

Configuración del Proyecto¶

Estructura Típica¶

MyApp/
├── src/
│   ├── MyApp.Api/              # ASP.NET Core Web API
│   │   ├── Controllers/
│   │   ├── Program.cs
│   │   └── appsettings.json
│   ├── MyApp.Core/             # Dominio y lógica de negocio
│   │   ├── Entities/
│   │   ├── Interfaces/
│   │   └── Services/
│   ├── MyApp.Infrastructure/    # EF Core, servicios externos
│   │   ├── Data/
│   │   │   ├── AppDbContext.cs
│   │   │   └── Migrations/
│   │   └── Services/
│   └── MyApp.Shared/           # DTOs, constantes
├── tests/
│   ├── MyApp.UnitTests/
│   └── MyApp.IntegrationTests/
├── MyApp.sln
└── Directory.Build.props

Crear Proyecto Nuevo¶

# Crear solución
dotnet new sln -n MyApp

# Crear proyectos
dotnet new webapi -n MyApp.Api -o src/MyApp.Api
dotnet new classlib -n MyApp.Core -o src/MyApp.Core
dotnet new classlib -n MyApp.Infrastructure -o src/MyApp.Infrastructure
dotnet new xunit -n MyApp.UnitTests -o tests/MyApp.UnitTests

# Añadir a la solución
dotnet sln add src/MyApp.Api
dotnet sln add src/MyApp.Core
dotnet sln add src/MyApp.Infrastructure
dotnet sln add tests/MyApp.UnitTests

# Añadir referencias entre proyectos
dotnet add src/MyApp.Api reference src/MyApp.Core src/MyApp.Infrastructure
dotnet add src/MyApp.Infrastructure reference src/MyApp.Core
dotnet add tests/MyApp.UnitTests reference src/MyApp.Core

Paquetes NuGet Comunes¶

# Entity Framework Core
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.Tools

# Logging
dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.Console
dotnet add package Serilog.Sinks.File

# Validación
dotnet add package FluentValidation.AspNetCore

# Mapping
dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection

# Testing
dotnet add package xunit
dotnet add package Moq
dotnet add package FluentAssertions
dotnet add package Microsoft.NET.Test.Sdk

# OpenAPI/Swagger
dotnet add package Swashbuckle.AspNetCore

# Health Checks
dotnet add package AspNetCore.HealthChecks.NpgSql
dotnet add package AspNetCore.HealthChecks.Redis

Comandos que Claude Code Ejecutará¶

Compilación y Ejecución¶

# Restaurar dependencias
dotnet restore

# Compilar
dotnet build

# Compilar en Release
dotnet build -c Release

# Ejecutar
dotnet run --project src/MyApp.Api

# Ejecutar con hot reload
dotnet watch run --project src/MyApp.Api

# Publicar
dotnet publish -c Release -o ./publish

Testing¶

# Ejecutar todos los tests
dotnet test

# Tests con cobertura
dotnet test --collect:"XPlat Code Coverage"

# Tests específicos
dotnet test --filter "FullyQualifiedName~UserServiceTests"

# Tests con output detallado
dotnet test --logger "console;verbosity=detailed"

Entity Framework¶

# Añadir migración
dotnet ef migrations add InitialCreate --project src/MyApp.Infrastructure --startup-project src/MyApp.Api

# Aplicar migraciones
dotnet ef database update --project src/MyApp.Infrastructure --startup-project src/MyApp.Api

# Revertir migración
dotnet ef database update PreviousMigrationName

# Generar script SQL
dotnet ef migrations script --idempotent -o migrations.sql

# Scaffold desde BD existente
dotnet ef dbcontext scaffold "Host=localhost;Database=mydb;Username=user;Password=pass" Npgsql.EntityFrameworkCore.PostgreSQL -o Models

NuGet¶

# Añadir paquete
dotnet add package NombrePaquete

# Añadir versión específica
dotnet add package NombrePaquete --version 1.2.3

# Listar paquetes
dotnet list package

# Actualizar paquetes
dotnet outdated
dotnet add package NombrePaquete  # actualiza a última versión

Docker para .NET¶

Dockerfile Típico¶

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY ["src/MyApp.Api/MyApp.Api.csproj", "MyApp.Api/"]
COPY ["src/MyApp.Core/MyApp.Core.csproj", "MyApp.Core/"]
COPY ["src/MyApp.Infrastructure/MyApp.Infrastructure.csproj", "MyApp.Infrastructure/"]
RUN dotnet restore "MyApp.Api/MyApp.Api.csproj"
COPY src/ .
RUN dotnet build "MyApp.Api/MyApp.Api.csproj" -c Release -o /app/build

# Publish stage
FROM build AS publish
RUN dotnet publish "MyApp.Api/MyApp.Api.csproj" -c Release -o /app/publish

# Runtime stage
FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS final
WORKDIR /app
COPY --from=publish /app/publish .
EXPOSE 8080
ENTRYPOINT ["dotnet", "MyApp.Api.dll"]

Docker Compose para Desarrollo¶

# docker-compose.yml
version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: src/MyApp.Api/Dockerfile
    ports:
      - "5000:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Host=postgres;Database=myapp;Username=myapp;Password=dev123
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: dev123
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

Verificación del Entorno¶

# verify-dotnet-env.ps1

Write-Host "=== Verificación Entorno .NET ===" -ForegroundColor Cyan

# .NET SDK
Write-Host "`n--- .NET SDK ---" -ForegroundColor Yellow
dotnet --list-sdks

# Herramientas globales
Write-Host "`n--- Herramientas Globales ---" -ForegroundColor Yellow
dotnet tool list --global

# EF Core Tools
Write-Host "`n--- Entity Framework ---" -ForegroundColor Yellow
dotnet ef --version

# Certificados HTTPS
Write-Host "`n--- HTTPS Dev Certs ---" -ForegroundColor Yellow
dotnet dev-certs https --check

# PostgreSQL
Write-Host "`n--- PostgreSQL ---" -ForegroundColor Yellow
try { psql --version } catch { Write-Host "psql no encontrado" -ForegroundColor Red }

# Docker
Write-Host "`n--- Docker ---" -ForegroundColor Yellow
docker --version

Write-Host "`n=== Verificación Completa ===" -ForegroundColor Green

Troubleshooting¶

"The SDK 'Microsoft.NET.Sdk.Web' not found"¶

# Reinstalar el SDK
winget uninstall Microsoft.DotNet.SDK.9
winget install Microsoft.DotNet.SDK.9

"A connection attempt failed" (PostgreSQL)¶

# Verificar que PostgreSQL está ejecutándose
Get-Service postgresql*

# Iniciar si está detenido
Start-Service postgresql-x64-16

"SSL certificate problem"¶

# Confiar en certificados de desarrollo
dotnet dev-certs https --trust

EF Core Migrations no encuentra el DbContext¶

# Especificar proyecto de startup
dotnet ef migrations add Test \
  --project src/MyApp.Infrastructure \
  --startup-project src/MyApp.Api