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@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
#:sdk Aspire.AppHost.Sdk@13.0.2

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 mediante el dotnet run comando con la --file opción :

dotnet run --file file.cs

O bien, use el dotnet run comando seguido del nombre del archivo:

dotnet run file.cs

O bien, use la sintaxis abreviada:

dotnet file.cs

Pasar argumentos

Pase argumentos a la aplicación colocándolos después de --:

dotnet run file.cs -- arg1 arg2

Sin --, los argumentos van al dotnet run comando :

dotnet run 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 virtual y compila la aplicación. De forma predeterminada, la salida de compilación va al directorio temporal del sistema en <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

Use la --output opción con el dotnet build comando para especificar una ruta de acceso diferente. Para definir una nueva ruta de acceso de salida predeterminada, establezca la OutputPath propiedad en la parte superior del archivo mediante la directiva : #:property OutputPath=./output.

Limpiar salidas de compilación

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

dotnet clean file.cs

Elimine la memoria caché de las aplicaciones basadas en archivos en un directorio:

dotnet clean file-based-apps

Use la --days opción con el comando anterior para especificar cuántos días debe no usarse una carpeta de artefactos antes de la eliminación. El número predeterminado de días es 30.

Publicación de aplicaciones

Las aplicaciones basadas en archivos habilitan la publicación nativa de AOT de forma predeterminada, lo que genera ejecutables optimizados y autocontenido. Deshabilite esta característica agregando #:property PublishAot=false en la parte superior del archivo.

Use el dotnet publish comando para crear un archivo ejecutable independiente:

dotnet publish file.cs

La ubicación predeterminada del archivo ejecutable es un artifacts directorio junto al .cs archivo, con un subdirectorio denominado después de la aplicación. Use la --output opción con el dotnet publish comando para especificar una ruta de acceso diferente.

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. Deshabilite esta configuración agregando #:property PackAsTool=false en la parte superior del archivo.

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 realiza una copia del .cs archivo y crea un .csproj archivo con elementos de SDK, propiedades y referencias de paquete equivalentes en función de las directivas del #: archivo original. Ambos archivos se colocan en un directorio denominado para la aplicación junto al archivo original .cs , que se deja intacto.

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

De forma predeterminada, la restauración se ejecuta implícitamente al compilar o ejecutar la aplicación. Sin embargo, puede pasar --no-restore a los comandos dotnet build y dotnet run para compilar o ejecutar sin restaurar implícitamente.

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" --file file.cs

Enumeración de secretos de usuario para aplicaciones basadas en archivos:

dotnet user-secrets list --file file.cs

El dotnet user-secrets list comando imprime el valor de los secretos. No coloque este comando en scripts que se ejecutan en contextos públicos.

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

Nota:

Utilice LF finales de línea en lugar de CRLF cuando añada un shebang. No incluya un BOM (marca de orden de bytes) en el archivo.

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 en las invocaciones posteriores de dotnet run. Este sistema de almacenamiento en caché es único para las aplicaciones basadas en archivos.

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.
Existencia y contenido implícitos del archivo de compilación.

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

Borre los artefactos de caché para las aplicaciones basadas en archivos mediante el comando siguiente:

dotnet clean file-based-apps

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.