Introducción

Cada vez que necesito una pequeña automatización en el día a día — verificar una configuración, importar un CSV, llamar a una API interna — aparece la pregunta inevitable: ¿uso PowerShell, Python o creo un proyecto .NET completo? Durante años, la respuesta estándar para los equipos .NET era crear un proyecto de consola, incluso para tareas de cinco minutos. Eso cambió. Hoy es posible ejecutar C# como script en .NET sin crear una solución, sin .csproj, sin boilerplate.

En este artículo voy a mostrar los tres enfoques disponibles, cuándo tiene sentido cada uno y cómo incorporarlo al día a día de un equipo .NET. Los ejemplos completos están en el repositorio blog-zocateli-sample — en el artículo voy a mostrar solo los fragmentos esenciales para explicar cada concepto.

Los tres enfoques son:

  • Top-level statements — eliminan el boilerplate de class Program y static void Main(), pero todavía necesitan un .csproj
  • dotnet-script — ejecuta archivos .csx sin proyecto, con soporte para NuGet inline
  • dotnet run archivo.cs — novedad de .NET 10 que ejecuta un único archivo .cs sin ninguna configuración

Para quienes ya están familiarizados con .NET y quieren aprovechar C# para las automatizaciones cotidianas, los tres enfoques tienen casos de uso complementarios — y entender las diferencias es lo que va a guiar la elección correcta en el momento adecuado.

Recomiendo leer el artículo sobre el Pipeline de Configuración .NET 8+ para entender cómo gestionar secretos y variables de entorno, algo que inevitablemente aparece en los scripts de automatización.

Requisitos previos

Para seguir los ejemplos prácticos, vas a necesitar:

  • .NET SDK 10 instalado — verifícalo con dotnet --version (debe devolver 10.x.x)
  • dotnet-script instalado como global tool:
1
dotnet tool install -g dotnet-script

Después de la instalación, verifícalo con dotnet script --version.

  • Familiaridad básica con C# y la línea de comandos

¿Qué Es C# como Script?

Históricamente, ejecutar código C# exigía crear una solución, un proyecto .csproj, escribir un Program.cs con namespace, class Program y static void Main(string[] args) — solo después venía el código en sí. Para una tarea de diez líneas, el overhead era desproporcionado.

La idea de usar C# como lenguaje de script no es nueva: la Roslyn Scripting API existe desde 2015 y es la base de dotnet-script. Lo que cambió con el tiempo fue la integración de esa capacidad directamente en el flujo de trabajo .NET:

  • .NET 5 (2020): los top-level statements eliminan el boilerplate en Program.cs, pero el proyecto sigue siendo necesario
  • dotnet-script (independiente de la versión del SDK): herramienta de terceros que ejecuta .csx sin ningún proyecto
  • .NET 10 (2025): dotnet run archivo.cs ejecuta un único archivo .cs directamente, sin proyecto

La diferencia conceptual entre “script” y “aplicación” está en el ciclo de vida y en la intención: un script se ejecuta una vez, resuelve una tarea específica y no necesita distribución formal. Una aplicación tiene un ciclo de vida gestionado, despliegues y versionado. Cuando el script empieza a crecer — múltiples archivos, pruebas, configuración externalizada — llegó el momento de crear un proyecto dedicado.

La tabla siguiente resume los tres enfoques:

EnfoqueExtensiónRequiere proyectoNuGet inline.NET mínimo
Top-level statements.csSí (pero mínimo)No.NET 5
dotnet-script.csxNoSí (#r "nuget:...").NET Core 3.1+
dotnet run archivo.csNoNo (todavía).NET 10

Comparación de los tres enfoques de C# como script: top-level statements, dotnet-script y dotnet run

ℹ️ Información: Los tres enfoques son complementarios, no competidores. La elección depende del contexto: complejidad del script, necesidad de paquetes externos y versión del SDK disponible en el entorno.

Top-Level Statements: C# Moderno sin Boilerplate

Los top-level statements se introdujeron en C# 9 (.NET 5) y permiten escribir el código directamente en el archivo Program.cs, sin declarar namespace, class ni Main. El compilador genera todo eso automáticamente.

La diferencia visual es clara:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Antes — C# 8 y anteriores
using System;

namespace MeuApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Olá, mundo!");
        }
    }
}
1
2
// Después — C# 9+ con top-level statements
Console.WriteLine("Olá, mundo!");

Ambos compilan al mismo resultado. El compilador infiere la clase y el método de entrada. Cuando necesito argumentos de línea de comandos, el array args está disponible implícitamente:

1
2
3
// args está disponible sin declaración explícita
var ambiente = args.Length > 0 ? args[0] : "desenvolvimento";
Console.WriteLine($"Executando em: {ambiente}");

📂 Código Fuente: El ejemplo completo está disponible en el repositorio de ejemplos del blog: BlogSamples/Scripting/TopLevelStatements/

⚠️ Atención: Los top-level statements todavía exigen un archivo .csproj para compilar. Eliminan el boilerplate de la clase y del método Main, pero no eliminan el proyecto. Si quieres ejecutar código sin ningún proyecto, los dos enfoques siguientes son el camino.

La limitación principal es que solo un archivo por proyecto puede usar top-level statements — los demás necesitan declaraciones normales. En la práctica, eso es suficiente para la mayoría de los proyectos de consola.

dotnet-script: Ejecutando Archivos .csx

dotnet-script es una herramienta global que interpreta archivos .csx (C# Script) usando la Roslyn Scripting API. La diferencia fundamental con los top-level statements es que no necesita proyecto — el archivo es la unidad de ejecución completa.

1
2
3
4
5
# Instalar una sola vez
dotnet tool install -g dotnet-script

# Ejecutar un script
dotnet script meu-script.csx

El recurso más potente es la referencia a paquetes NuGet directamente en el archivo, sin csproj, sin dotnet add package:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// exemplo-com-nuget.csx
#r "nuget: Humanizer, 2.14.1"

using Humanizer;

var bytes = 1_048_576L;
// Humanizer convierte a un formato legible para humanos
Console.WriteLine(bytes.Bytes().Humanize()); // "1 MB"

var data = DateTime.Now.AddDays(-3);
Console.WriteLine(data.Humanize()); // "3 days ago"

📂 Código Fuente: El ejemplo completo está disponible en el repositorio de ejemplos del blog: BlogSamples/Scripting/DotnetScript/

Los casos de uso donde dotnet-script brilla:

  • Migraciones puntuales: ejecutar una migración específica en un entorno determinado sin el contexto del proyecto principal
  • Seed de datos: poblar la base de datos de desarrollo con datos realistas
  • Utilidades de CI/CD: verificar versiones, validar configuraciones, generar artefactos
  • Consultas e informes: combinar Entity Framework (vía NuGet) con lógica C# sin crear un proyecto

💡 Consejo: En Linux y macOS, agrega #!/usr/bin/env dotnet-script en la primera línea del archivo .csx para hacerlo ejecutable directamente en el shell, sin necesidad de anteponer dotnet script.

Ejecutando un Archivo .cs Directamente con dotnet run

.NET 10 trajo una funcionalidad muy esperada: ejecutar un único archivo .cs sin proyecto, sin solución, sin ninguna configuración:

1
dotnet run meu-script.cs

Esto es diferente del dotnet run tradicional, que debe ejecutarse dentro de un directorio de proyecto. Aquí, el archivo .cs es la unidad completa de ejecución.

Un ejemplo de uso real — verificar la versión de un servicio en múltiples entornos:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// verificar-versao.cs
using System.Net.Http;
using System.Text.Json;

var ambientes = new[] { "dev", "staging", "prod" };
var http = new HttpClient();

foreach (var env in ambientes)
{
    var url = $"https://api.{env}.empresa.com/health";
    var resposta = await http.GetStringAsync(url);
    var json = JsonDocument.Parse(resposta);
    var versao = json.RootElement.GetProperty("version").GetString();
    Console.WriteLine($"{env,-10} → {versao}");
}
1
dotnet run verificar-versao.cs

📂 Código Fuente: El ejemplo completo está disponible en el repositorio de ejemplos del blog: BlogSamples/Scripting/DotnetRunSingleFile/

ℹ️ Información: En la versión inicial de .NET 10, dotnet run archivo.cs no admite múltiples archivos ni referencias NuGet inline. Para scripts que necesitan paquetes externos, dotnet-script con .csx sigue siendo la mejor opción.

La mayor ventaja de este enfoque es la fricción cero: no hay que instalar ninguna herramienta adicional, funciona en cualquier máquina con el SDK de .NET 10 y no exige ningún archivo auxiliar.

Casos de Uso Reales: Cuándo C# como Script Tiene Sentido

Después de usar los tres enfoques en el día a día, estos son algunos escenarios donde elegir C# como script valió la pena:

Automatizaciones de CI/CD: scripts de pipeline que necesitan lógica de negocio — validar configuraciones de appsettings.json, verificar que las variables de entorno obligatorias estén presentes, generar artefactos de release con nombres estandarizados. Todo eso en C# tipado, con las mismas bibliotecas que usa el proyecto principal.

Seeding de datos de desarrollo: poblar una base de datos local con datos realistas usando el mismo DbContext y las mismas entidades del proyecto. Con dotnet-script y #r "nuget:Microsoft.EntityFrameworkCore.SqlServer,...", el script accede a la base de datos sin crear un proyecto dedicado.

Utilidades del equipo: herramientas internas que el equipo .NET necesita mantener a lo largo del tiempo. En C# con tipado estático, el próximo desarrollador que abra el script va a entender el código sin aprender un nuevo lenguaje.

Prototipado: probar el comportamiento de una API o biblioteca antes de integrarla al proyecto principal. Un archivo .csx con #r "nuget:..." es más rápido que crear un proyecto de pruebas.

⚠️ Atención: Cuando el script empieza a crecer — múltiples funciones, múltiples archivos, necesidad de pruebas unitarias, configuración externalizada — llegó el momento de crear un proyecto de consola dedicado. Los scripts son para tareas puntuales, no para sistemas. El artículo sobre .NET Worker Background Service muestra el camino cuando la automatización necesita convertirse en un servicio de larga duración.

Comparativa: C# Script vs PowerShell vs Python para Automatizaciones

Para los equipos .NET, la comparación con las alternativas más comunes es relevante. La tabla siguiente es objetiva — cada herramienta tiene ventajas reales:

CriterioC# ScriptPowerShellPython
Curva de aprendizaje (equipo .NET)BajaMediaAlta
Acceso a bibliotecas .NET / NuGet✅ Nativo❌ Limitado❌ No
Tipado estático✅ Sí❌ No❌ No
Portabilidad (Linux/macOS/Windows)✅ Sí✅ Sí (PS Core)✅ Sí
Soporte de IDE (IntelliSense, depuración)✅ VS Code + OmniSharpParcial✅ Sí
Rendimiento de arranque (JIT warm-up)⚠️ LentoMedioMedio
Administración del sistema operativo⚠️ Verboso✅ NativoBueno
Ecosistema de ML / data science❌ No❌ No✅ Sí

Cuándo pierde C# script: tareas de shell puro (mover archivos, gestionar procesos, pipelines de comandos), administración del sistema operativo, scripts de menos de diez líneas donde PowerShell es más conciso.

Cuándo gana C# script: lógica de negocio que usa los mismos tipos y bibliotecas del proyecto principal, consumo de APIs .NET, operaciones de base de datos vía Entity Framework, cualquier cosa donde el tipado estático reduzca errores.

Ejemplo Práctico

El escenario: un script que lee un archivo CSV con productos y envía cada registro a una API REST interna — una necesidad recurrente en proyectos de migración de datos.

Con dotnet-script, el archivo .csx referencia el paquete CSV directamente:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// importar-csv-api.csx (fragmento principal)
#r "nuget: CsvHelper, 33.0.1"

using CsvHelper;
using System.Globalization;
using System.Net.Http.Json;

var apiUrl = Environment.GetEnvironmentVariable("API_URL")
    ?? throw new InvalidOperationException("Variável API_URL não configurada");

using var http = new HttpClient();
using var reader = new StreamReader("produtos.csv");
using var csv = new CsvReader(reader, CultureInfo.InvariantCulture);

var produtos = csv.GetRecords<Produto>().ToList();
Console.WriteLine($"Lidos {produtos.Count} produtos. Enviando...");

foreach (var produto in produtos)
{
    var resposta = await http.PostAsJsonAsync($"{apiUrl}/produtos", produto);
    resposta.EnsureSuccessStatusCode();
    Console.WriteLine($"  ✓ {produto.Nome}");
}

📂 Código Fuente: El ejemplo completo, con manejo de errores, cancelación vía CancellationToken, retry y log estructurado, está disponible en el repositorio de ejemplos del blog: BlogSamples/Scripting/ExemploPratico/

El script completo en el repositorio incluye el record Produto, manejo de HttpRequestException con retry manual, log de progreso y soporte para --dry-run mediante un argumento.

Consejos y Buenas Prácticas

  • Prefiere .csx con dotnet-script cuando necesites NuGet. Los top-level statements en un proyecto .csproj mínimo todavía exigen dotnet add package y modifican el archivo de proyecto. Con .csx, la referencia queda dentro del propio script y cualquier persona puede ejecutarlo con dotnet script archivo.csx sin configuración adicional.

  • Nunca escribas secretos directamente en los scripts. Usa variables de entorno (Environment.GetEnvironmentVariable) o dotnet user-secrets para el desarrollo local. Los scripts de automatización circulan con frecuencia en repositorios y logs de CI — una connection string o un token expuestos son un riesgo real. Consulta el artículo sobre Logging Estructurado para entender cómo evitar también datos sensibles en los logs.

  • Para scripts usados en CI/CD, fija la versión de la herramienta. Crea un .config/dotnet-tools.json en el repositorio con dotnet tool install --local dotnet-script. Esto garantiza que el pipeline siempre use la misma versión, sin depender de lo que esté instalado globalmente en el agente de build.

  • Agrega #!/usr/bin/env dotnet-script para Linux/macOS. Con esa línea al inicio del archivo .csx y permiso de ejecución (chmod +x script.csx), el script puede llamarse directamente como ./script.csx en el terminal — sin prefijo. En equipos con desarrolladores en distintos sistemas operativos, esto reduce la fricción.

  • Define un límite de crecimiento. Los scripts de más de 150–200 líneas suelen indicar que la tarea superó el alcance de un script. En ese punto, crear un proyecto de consola con una estructura adecuada — pruebas, configuración externalizada, inyección de dependencias — es más sostenible que ampliar el script indefinidamente.

Resumen Objetivo

  • Top-level statements — eliminan el boilerplate de class Program y static void Main() desde C# 9 (.NET 5), pero todavía exigen un archivo .csproj para compilar; no son ejecución sin proyecto.
  • dotnet-script — herramienta global open-source que ejecuta archivos .csx sin proyecto, con soporte para referencias NuGet inline vía #r "nuget:Paquete,Versión", basada en la Roslyn Scripting API.
  • dotnet run archivo.cs — recurso nativo de .NET 10 que ejecuta un único archivo .cs sin proyecto, sin solución y sin configuración adicional; no admite NuGet inline en la versión inicial.
  • C# como script en CI/CD — permite que los equipos .NET escriban automatizaciones de pipeline reutilizando bibliotecas y tipado del ecosistema .NET, sin aprender PowerShell ni Python.
  • Limitación de dotnet run de archivo único (.NET 10) — no admite múltiples archivos ni NuGet inline; para esas necesidades, dotnet-script con .csx es la alternativa adecuada.
  • Criterio de elección — sin NuGet inline y sin proyecto: dotnet run archivo.cs; con NuGet inline y sin proyecto: dotnet-script .csx; con distribución formal y múltiples archivos: proyecto de consola con top-level statements.

Lee También

Referencias