Aplicaciones basadas en archivos

Este artículo se aplica a: ✔️ SDK de .NET 10 y versiones posteriores

Las aplicaciones basadas en archivos permiten compilar, ejecutar y publicar aplicaciones .NET desde un único archivo de C# sin crear un archivo de proyecto tradicional. Ofrecen una alternativa ligera a los proyectos tradicionales de .NET. Este enfoque simplifica el desarrollo de scripts, utilidades y aplicaciones pequeñas. El SDK de .NET genera automáticamente la configuración del proyecto necesaria en función de las directivas del archivo de origen.

Entre las ventajas clave se incluyen las siguientes:

Código plantilla reducido para aplicaciones sencillas.
Archivos de código fuente independientes con configuración embebida.
La publicación AOT nativa está habilitada por defecto.
Empaquetado automático como herramientas de .NET.

En este artículo, aprenderá a crear, configurar y trabajar con aplicaciones basadas en archivos de forma eficaz.

Directivas admitidas

Las aplicaciones basadas en archivos usan directivas prefijos con #: para configurar la compilación y ejecutar la aplicación. Las directivas admitidas incluyen: #:package, #:project, #:propertyy #:sdk. Coloque estas directivas en la parte superior del archivo de C#.

`#:package`

Agrega una referencia de paquete NuGet a la aplicación.

#:package Newtonsoft.Json
#:package Serilog version="3.1.1"

`#:project`

Hace referencia a otro archivo de proyecto o directorio que contiene un archivo de proyecto.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Establece un valor de propiedad de MSBuild.

#:property TargetFramework=net10.0
#:property PublishAot=false

`#:sdk`

Especifica el SDK que se va a usar. Tiene como valor predeterminado Microsoft.NET.Sdk.

#:sdk Microsoft.NET.Sdk.Web

Comandos de la CLI

La CLI de .NET proporciona compatibilidad completa con aplicaciones basadas en archivos a través de comandos conocidos.

Ejecución de aplicaciones

Ejecute una aplicación basada en archivos directamente mediante el dotnet run comando :

dotnet run file.cs

O bien, use la sintaxis abreviada:

dotnet file.cs

Pasar argumentos

Pase argumentos a la aplicación de varias maneras:

dotnet run file.cs -- arg1 arg2

Los argumentos después de -- se pasan a su aplicación. Sin --, los argumentos van al dotnet run comando :

dotnet run file.cs arg1 arg2

Sin embargo, con la sintaxis abreviada, todos los argumentos van a la aplicación:

dotnet file.cs arg1 arg2

Creación de aplicaciones

Compile la aplicación basada en archivos mediante el dotnet build comando :

dotnet build file.cs

El SDK genera un proyecto temporal y compila la aplicación.

Limpiar salidas de compilación

Quite los artefactos de construcción mediante el comando dotnet clean.

dotnet clean file.cs

Limpie todas las aplicaciones basadas en archivos en un directorio:

dotnet clean file-based-apps

Publicación de aplicaciones

Cree un paquete de implementación mediante el dotnet publish comando :

dotnet publish file.cs

Las aplicaciones basadas en archivos habilitan la publicación nativa de AOT de forma predeterminada, lo que genera ejecutables optimizados y autocontenido.

Paquete como herramienta

Empaquete la aplicación basada en archivos como una herramienta .NET mediante el dotnet pack comando :

dotnet pack file.cs

Las aplicaciones basadas en archivos se establecen PackAsTool=true de forma predeterminada.

Convertir en proyecto

Convierta la aplicación basada en archivos en un proyecto tradicional mediante el dotnet project convert comando :

dotnet project convert file.cs

Este comando crea un .csproj archivo con el SDK y las propiedades equivalentes. Todas las # directivas se quitan del .cs archivo y se convierten en elementos del archivo correspondiente .csproj .

Restauración de dependencias

Restaure los paquetes NuGet a los que se hace referencia en el archivo mediante el dotnet restore comando :

dotnet restore file.cs

La restauración se ejecuta implícitamente al compilar o ejecutar la aplicación.

Elementos predeterminados incluidos

Las aplicaciones basadas en archivos incluyen automáticamente tipos de archivo específicos para la compilación y el empaquetado.

De forma predeterminada, se incluyen los siguientes elementos:

El único archivo de C#.
Archivos de recursos de ResX en el mismo directorio.

Los SDK diferentes incluyen otros tipos de archivo:

Microsoft.NET.Sdk.Web incluye *.json archivos de configuración.
Otros SDK especializados pueden incluir otros patrones.

Publicación de AOT nativo

Las aplicaciones basadas en archivos habilitan la compilación nativa de antemano (AOT) de forma predeterminada. Esta característica genera ejecutables optimizados e independientes con un inicio más rápido y una superficie de memoria más pequeña.

Si necesita deshabilitar AOT nativo, use la siguiente configuración:

#:property PublishAot=false

Para obtener más información sobre AOT nativo, consulte Implementación de AOT nativa.

Secretos de usuario

Las aplicaciones basadas en archivos generan un identificador de secretos de usuario estable basado en un hash de la ruta de acceso de archivo completa. Este identificador le permite almacenar la configuración confidencial por separado del código fuente.

Acceda a secretos de usuario de la misma manera que los proyectos tradicionales:

dotnet user-secrets set "ApiKey" "your-secret-value" --project file.cs

Para más información, consulte Almacenamiento seguro de secretos de aplicaciones en desarrollo.

Perfiles de lanzamiento

Las aplicaciones basadas en archivos admiten perfiles de inicio para configurar cómo se ejecuta la aplicación durante el desarrollo. En lugar de colocar perfiles de inicio en Properties/launchSettings.json, las aplicaciones que usan archivos pueden utilizar un archivo de configuración inicial simple denominado [ApplicationName].run.json en el mismo directorio que el archivo fuente.

Archivo de configuración de lanzamiento simple

Cree un archivo de configuración de lanzamiento con el nombre de su aplicación. Por ejemplo, si la aplicación basada en archivos es app.cs, cree app.run.json en el mismo directorio:

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Varias aplicaciones basadas en archivos

Cuando tiene varias aplicaciones basadas en archivos en el mismo directorio, cada aplicación puede tener su propio archivo de configuración de inicio:

📁 myapps/
├── foo.cs
├── foo.run.json
├── bar.cs
└── bar.run.json

Selección de perfil

La CLI de .NET selecciona perfiles de inicio con la siguiente prioridad:

Perfil especificado por la --launch-profile opción .
Perfil especificado por la variable de entorno DOTNET_LAUNCH_PROFILE.
Primer perfil definido en el archivo de configuración de inicio.

Para ejecutar con un perfil específico:

dotnet run app.cs --launch-profile https

Configuración de inicio tradicional

Las aplicaciones basadas en archivos también admiten el archivo tradicional Properties/launchSettings.json . Si existen ambos archivos, la ubicación tradicional tiene prioridad. Si ambos archivos están presentes, la CLI de .NET registra una advertencia para aclarar qué archivo se usa.

Ejecución del shell

Habilite la ejecución directa de aplicaciones basadas en archivos en sistemas similares a Unix mediante el uso de una línea shebang y permisos ejecutables.

Agregue un shebang en la parte superior de su archivo.

#!/usr/bin/env dotnet
#:package Spectre.Console

using Spectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");

Convierta el archivo ejecutable:

chmod +x file.cs

Ejecute directamente:

./file.cs

Archivos de compilación implícitos

Las aplicaciones basadas en archivos respetan los archivos de configuración de MSBuild y NuGet en el mismo directorio o directorios primarios. Estos archivos afectan al modo en que el SDK compila la aplicación. Tenga en cuenta estos archivos al organizar las aplicaciones basadas en archivos.

`Directory.Build.props`

Define las propiedades de MSBuild que se aplican a todos los proyectos de un árbol de directorios. Las aplicaciones basadas en archivos heredan estas propiedades.

`Directory.Build.targets`

Define destinos de MSBuild y lógica de compilación personalizada. Las aplicaciones orientadas a archivos ejecutan estos objetivos durante la compilación.

`Directory.Packages.props`

Habilita la administración central de paquetes para las dependencias de NuGet. Las aplicaciones basadas en archivos pueden usar versiones de paquetes administradas centralmente.

`nuget.config`

Configura los orígenes y las opciones del paquete NuGet. Las aplicaciones basadas en archivos usan estas configuraciones al restaurar paquetes.

`global.json`

Especifica la versión del SDK de .NET que se va a usar. Las aplicaciones basadas en archivos respetan esta selección de versión.

Caché de compilación

El SDK de .NET almacena en caché las salidas de compilación para mejorar el rendimiento de las compilaciones posteriores. Las aplicaciones basadas en archivos participan en este sistema de almacenamiento en caché.

Comportamiento de la caché

El SDK almacena en caché las salidas de compilación basadas en:

Contenido del archivo de origen.
Configuración de directivas.
Versión del SDK.
Archivos de compilación implícitos.

El almacenamiento en caché mejora el rendimiento de la compilación, pero puede causar confusión cuando:

Los cambios en los archivos de compilación implícitos no desencadenan recompilaciones.
Mover archivos a directorios diferentes no invalida la memoria caché.

Soluciones alternativas

Ejecute una compilación completa con el indicador --no-cache.
```
dotnet build file.cs --no-cache
```
Forzar una compilación limpia para omitir la memoria caché:
```
dotnet clean file.cs
dotnet build file.cs
```

Recomendaciones de diseño de carpetas

Organice cuidadosamente las aplicaciones basadas en archivos para evitar conflictos con proyectos tradicionales y archivos de compilación implícitos.

Evitar conos de archivos de proyecto

No coloque aplicaciones basadas en archivos dentro de la estructura de directorios de un .csproj proyecto. La configuración y los archivos de compilación implícitos del archivo del proyecto pueden interferir con la aplicación basada en archivos.

❌ No recomendado:

📁 MyProject/
├── MyProject.csproj
├── Program.cs
└──📁 scripts/
    └── utility.cs  // File-based app - bad location

✅ Recomienda:

📁 MyProject/
├── MyProject.csproj
└── Program.cs
📁 scripts/
└── utility.cs  // File-based app - good location

Tenga en cuenta los archivos implícitos.

Los archivos de compilación implícitos en directorios primarios afectan a todas las aplicaciones basadas en archivos en subdirectorios. Cree directorios aislados para aplicaciones basadas en archivos cuando necesite configuraciones de compilación diferentes.