Aplicações baseadas em ficheiros

Este artigo aplica-se a: ✔️ SDK do .NET 10 e versões posteriores

As aplicações baseadas em ficheiros permitem-lhe construir, executar e publicar aplicações .NET a partir de um único ficheiro C# sem criar um ficheiro de projeto tradicional. Oferecem uma alternativa leve aos projetos tradicionais .NET. Esta abordagem simplifica o desenvolvimento de scripts, utilitários e pequenas aplicações. O SDK .NET gera automaticamente a configuração necessária do projeto com base nas diretivas do seu ficheiro de origem.

Os principais benefícios incluem:

Redução do boilerplate para aplicações simples.
Ficheiros fonte autónomos com configuração integrada.
Ativada por padrão a publicação nativa AOT.
Embalagem automática como ferramentas .NET.

Neste artigo, aprenda a criar, configurar e trabalhar eficazmente com aplicações baseadas em ficheiros.

Diretivas apoiadas

As aplicações baseadas em ficheiros usam diretivas com o prefixo #: para configurar a compilação e executar a aplicação. As diretivas apoiadas incluem: #:package, #:project, #:property, e #:sdk. Coloque estas diretivas no topo do ficheiro C#.

`#:package`

Adiciona uma referência de pacote NuGet à sua candidatura.

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

`#:project`

Faz referência a outro ficheiro ou diretório de projeto que contém um ficheiro de projeto.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Define um valor de propriedade MSBuild.

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

`#:sdk`

Especifica o SDK a usar. O padrão é Microsoft.NET.Sdk.

#:sdk Microsoft.NET.Sdk.Web

Comandos da CLI

A CLI .NET oferece suporte total para aplicações baseadas em ficheiros através de comandos familiares.

Executar aplicações

Execute uma aplicação baseada em ficheiros diretamente usando o dotnet run comando:

dotnet run file.cs

Ou use a sintaxe abreviada:

dotnet file.cs

Argumentos aprovados

Transmita argumentos à sua candidatura de várias formas:

dotnet run file.cs -- arg1 arg2

Os argumentos após -- são passados para a sua aplicação. Sem --, os argumentos vão para o dotnet run comando:

dotnet run file.cs arg1 arg2

Código de tubo do stdin

Pipe código C# diretamente para dotnet run usando a entrada padrão com o argumento -. O - argumento indica que dotnet run lê o código a partir de uma entrada padrão em vez de um ficheiro. Com este - argumento, dotnet run não procura outros ficheiros no diretório de trabalho atual, como perfis de lançamento. O diretório atual continua a ser o diretório de trabalho para construir e executar o programa.

PowerShell::

'Console.WriteLine("hello from stdin!");' | dotnet run -

Bash:

echo 'Console.WriteLine("hello from stdin!");' | dotnet run -

Esta abordagem é útil para testes rápidos, execução de comandos pontuais ou integração com scripts de shell que geram código C# dinamicamente.

Crie aplicativos

Compila a tua aplicação baseada em ficheiros usando o dotnet build comando:

dotnet build file.cs

O SDK gera um projeto temporário e constrói a sua aplicação.

Limpeza de saídas de compilação

Remover artefactos de construção usando o dotnet clean comando:

dotnet clean file.cs

Limpe todas as aplicações baseadas em ficheiros num diretório:

dotnet clean file-based-apps

Publicar candidaturas

Crie um pacote de deployment usando o dotnet publish comando:

dotnet publish file.cs

As aplicações baseadas em ficheiros ativam por defeito a publicação AOT nativa, produzindo executáveis otimizados e autónomos.

Empacotamento como ferramenta

Empacota a tua aplicação baseada em ficheiros como uma ferramenta .NET usando o dotnet pack comando:

dotnet pack file.cs

Aplicações baseadas em ficheiros são definidas PackAsTool=true por defeito.

Converter em projeto

Converta a sua aplicação baseada em ficheiros num projeto tradicional usando o dotnet project convert comando:

dotnet project convert file.cs

Este comando cria um .csproj ficheiro com SDK e propriedades equivalentes. Todas as diretivas # são removidas do ficheiro .cs e transformadas em elementos no correspondente ficheiro .csproj.

Restaurar dependências

Restaure os pacotes NuGet referenciados no seu ficheiro usando o dotnet restore comando:

dotnet restore file.cs

A restauração corre implicitamente quando constróis ou executas a tua aplicação.

Itens incluídos por padrão

As aplicações baseadas em ficheiros incluem automaticamente tipos específicos de ficheiros para compilação e embalagem.

Por defeito, os seguintes itens estão incluídos:

O único ficheiro C# em si.
Arquivos de recursos ResX no mesmo diretório.

Diferentes SDKs incluem outros tipos de ficheiros:

Microsoft.NET.Sdk.Web inclui ficheiros de configuração *.json.
Outros SDKs especializados podem incluir outros padrões.

Publicação AOT nativa

As aplicações baseadas em ficheiros ativam a compilação nativa ahead-of-time (AOT) por defeito. Esta funcionalidade produz executáveis otimizados e autónomos, com arranque mais rápido e menor espaço de memória.

Se precisares de desativar o AOT nativo, usa a seguinte definição:

#:property PublishAot=false

Para mais informações sobre o AOT nativo, consulte a implementação do AOT nativo.

Segredos de utilizador

As aplicações baseadas em ficheiros geram um ID estável de segredos de utilizador baseado num hash do caminho completo do ficheiro. Este ID permite-lhe armazenar configurações sensíveis separadamente do seu código-fonte.

Aceda aos segredos de utilizador da mesma forma que nos projetos tradicionais:

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

Para mais informações, veja Armazenamento seguro dos segredos da aplicação em desenvolvimento.

Perfis de lançamento

As aplicações baseadas em ficheiros suportam perfis de lançamento para configurar como a aplicação corre durante o desenvolvimento. Em vez de colocar perfis de lançamento em Properties/launchSettings.json, as aplicações baseadas em ficheiros podem usar um ficheiro de definições de lançamento plano nomeado [ApplicationName].run.json no mesmo diretório do ficheiro de origem.

Ficheiro de definições de lançamento simples

Crie um ficheiro de definições de arranque com o nome da sua aplicação. Por exemplo, se a sua aplicação baseada em ficheiros for app.cs, crie app.run.json no mesmo diretório:

{
  "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"
      }
    }
  }
}

Múltiplas aplicações baseadas em ficheiros

Quando tem várias aplicações baseadas em ficheiros no mesmo diretório, cada aplicação pode ter o seu próprio ficheiro de definições de lançamento:

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

Seleção de perfis

A CLI .NET seleciona perfis de lançamento usando a seguinte prioridade:

O perfil especificado pela opção --launch-profile.
O perfil especificado pela DOTNET_LAUNCH_PROFILE variável de ambiente.
O primeiro perfil definido no ficheiro de definições de lançamento.

Para executar com um perfil específico:

dotnet run app.cs --launch-profile https

Configurações tradicionais de lançamento

As aplicações baseadas em ficheiros também suportam o ficheiro tradicional Properties/launchSettings.json . Se ambos os ficheiros existirem, a localização tradicional tem prioridade. Se ambos os ficheiros estiverem presentes, a CLI .NET regista um aviso para esclarecer qual o ficheiro utilizado.

Execução do shell

Permita a execução direta de aplicações baseadas em ficheiros em sistemas do tipo Unix usando uma linha shebang e permissões executáveis.

Adicione um shebang no topo do seu ficheiro:

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

using Spectre.Console;

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

Torne o ficheiro executável:

chmod +x file.cs

Execute diretamente:

./file.cs

Ficheiros de construção implícitos

As aplicações baseadas em ficheiros respeitam os ficheiros de configuração MSBuild e NuGet no mesmo diretório ou diretórios pais. Estes ficheiros afetam a forma como o SDK constrói a sua aplicação. Tenha atenção a estes ficheiros ao organizar as suas aplicações baseadas em ficheiros.

`Directory.Build.props`

Define propriedades do MSBuild que se aplicam a todos os projetos numa árvore de diretórios. As aplicações baseadas em ficheiros herdam estas propriedades.

`Directory.Build.targets`

Define alvos do MSBuild e lógica de construção personalizada. As aplicações baseadas em ficheiros executam estes alvos durante a compilação.

`Directory.Packages.props`

Permite a gestão centralizada de pacotes para dependências NuGet. As aplicações baseadas em ficheiros podem usar versões de pacotes geridas centralmente.

`nuget.config`

Configura as fontes e definições dos pacotes NuGet. As aplicações baseadas em ficheiros usam estas configurações ao restaurar pacotes.

`global.json`

Especifica a versão do SDK .NET a usar. As aplicações baseadas em ficheiros respeitam esta seleção de versões.

Construir cache

O SDK .NET armazena em cache as saídas das builds para melhorar o desempenho em builds subsequentes. Aplicações baseadas em ficheiros participam neste sistema de cache.

Comportamento do cache

O SDK armazena em cache as saídas da build baseadas em:

Conteúdo do ficheiro de origem.
Configuração diretiva.
Versão do SDK.
Ficheiros de build implícitos.

O cache melhora o desempenho da compilação, mas pode causar confusão quando:

Alterações aos ficheiros implícitos de compilação não desencadeiam reconstruções.
Mover ficheiros para diferentes diretórios não invalida a cache.

Soluções

Executa uma build completa usando a --no-cache flag:
```
dotnet build file.cs --no-cache
```
Forçar uma compilação limpa para ignorar a cache.
```
dotnet clean file.cs
dotnet build file.cs
```

Recomendações de layout de pastas

Organize cuidadosamente as suas aplicações baseadas em ficheiros para evitar conflitos com projetos tradicionais e ficheiros de construção implícitos.

Evite cones de ficheiros de projeto

Não coloque aplicações baseadas em ficheiros dentro da estrutura de diretórios de um .csproj projeto. Os ficheiros de compilação implícitos e as definições do ficheiro de projeto podem interferir com a sua aplicação baseada em ficheiros.

❌ Não recomendado:

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

✅ Recomendado:

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

Tenha atenção aos ficheiros implícitos

Os ficheiros de construção implícitos nos diretórios pai afetam todas as aplicações baseadas em arquivos nos subdiretórios. Cria diretórios isolados para aplicações baseadas em ficheiros quando precisares de configurações de compilação diferentes.