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 Programystatic void Main(), pero todavía necesitan un.csproj - dotnet-script — ejecuta archivos
.csxsin proyecto, con soporte para NuGet inline dotnet run archivo.cs— novedad de .NET 10 que ejecuta un único archivo.cssin 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 devolver10.x.x) - dotnet-script instalado como global tool:
| |
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
.csxsin ningún proyecto - .NET 10 (2025):
dotnet run archivo.csejecuta un único archivo.csdirectamente, 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:
| Enfoque | Extensión | Requiere proyecto | NuGet inline | .NET mínimo |
|---|---|---|---|---|
| Top-level statements | .cs | Sí (pero mínimo) | No | .NET 5 |
| dotnet-script | .csx | No | Sí (#r "nuget:...") | .NET Core 3.1+ |
| dotnet run archivo | .cs | No | No (todavía) | .NET 10 |

ℹ️ 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:
| |
| |
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:
| |
📂 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
.csprojpara compilar. Eliminan el boilerplate de la clase y del métodoMain, 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.
| |
El recurso más potente es la referencia a paquetes NuGet directamente en el archivo, sin csproj, sin dotnet add package:
| |
📂 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-scripten la primera línea del archivo.csxpara hacerlo ejecutable directamente en el shell, sin necesidad de anteponerdotnet 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:
| |
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:
| |
| |
📂 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.csno admite múltiples archivos ni referencias NuGet inline. Para scripts que necesitan paquetes externos,dotnet-scriptcon.csxsigue 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:
| Criterio | C# Script | PowerShell | Python |
|---|---|---|---|
| Curva de aprendizaje (equipo .NET) | Baja | Media | Alta |
| 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 + OmniSharp | Parcial | ✅ Sí |
| Rendimiento de arranque (JIT warm-up) | ⚠️ Lento | Medio | Medio |
| Administración del sistema operativo | ⚠️ Verboso | ✅ Nativo | Bueno |
| 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:
| |
📂 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
.csxcondotnet-scriptcuando necesites NuGet. Los top-level statements en un proyecto.csprojmínimo todavía exigendotnet add packagey modifican el archivo de proyecto. Con.csx, la referencia queda dentro del propio script y cualquier persona puede ejecutarlo condotnet script archivo.csxsin configuración adicional.Nunca escribas secretos directamente en los scripts. Usa variables de entorno (
Environment.GetEnvironmentVariable) odotnet user-secretspara 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.jsonen el repositorio condotnet 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-scriptpara Linux/macOS. Con esa línea al inicio del archivo.csxy permiso de ejecución (chmod +x script.csx), el script puede llamarse directamente como./script.csxen 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 Programystatic void Main()desde C# 9 (.NET 5), pero todavía exigen un archivo.csprojpara compilar; no son ejecución sin proyecto. - dotnet-script — herramienta global open-source que ejecuta archivos
.csxsin 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.cssin 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 runde archivo único (.NET 10) — no admite múltiples archivos ni NuGet inline; para esas necesidades,dotnet-scriptcon.csxes 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
- Pipeline de Configuración en .NET 8+ — gestionar configuración, secretos y variables de entorno en scripts y aplicaciones .NET
- Log Sin Contexto es Ruido: Logging Estructurado en .NET 8 — agregar observabilidad estructurada a tus scripts y workers
- .NET Worker Background Service — cuando el script crece y necesita convertirse en un servicio de larga duración con ciclo de vida gestionado
Referencias
- What’s new in .NET 10 — Run C# files directly — Microsoft Learn — documentación oficial de la funcionalidad
dotnet run archivo.cs - dotnet-script GitHub — repositorio oficial de la herramienta open-source para ejecutar
.csx - Top-level statements — C# Programming Guide — Microsoft Learn — referencia completa de la funcionalidad
- Roslyn Scripting API Samples — dotnet/roslyn — base técnica de dotnet-script, ejemplos de la Roslyn Scripting API
- .NET CLI reference — dotnet run — Microsoft Learn — referencia completa del comando
dotnet run - Global tools — .NET CLI — Microsoft Learn — instalación y gestión de global tools como
dotnet-script - CsvHelper — GitHub — biblioteca usada en el ejemplo práctico para leer CSV

Al comentar, aceptas nuestra Política de Privacidad, Términos de Uso, Política de Eliminación de Datos.