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

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 usando o dotnet run comando com a --file opção:

dotnet run --file file.cs

Ou usar o dotnet run comando seguido do nome do ficheiro:

dotnet run file.cs

Ou use a sintaxe abreviada:

dotnet file.cs

Argumentos aprovados

Transmita argumentos à sua aplicação colocando-os depois de --:

dotnet run file.cs -- arg1 arg2

Sem --, os argumentos vão para o dotnet run comando:

dotnet run file.cs arg1 arg2

Crie aplicativos

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

dotnet build file.cs

O SDK gera um projeto virtual e constrói a sua aplicação. Por padrão, o resultado da compilação vai para o diretório temporário do sistema sob <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

Use a --output opção com o dotnet build comando para especificar um caminho diferente. Para definir um novo caminho de saída predefinido, defina a OutputPath propriedade no topo do seu ficheiro usando a diretiva: #:property OutputPath=./output.

Limpeza de saídas de compilação

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

dotnet clean file.cs

Apagar a cache para aplicações baseadas em ficheiros num diretório:

dotnet clean file-based-apps

Use a --days opção com o comando anterior para especificar quantos dias uma pasta de artefactos precisa de ficar sem uso antes de ser removida. O número padrão de dias é 30.

Publicar candidaturas

As aplicações baseadas em ficheiros ativam por defeito a publicação AOT nativa, produzindo executáveis otimizados e autónomos. Desative esta funcionalidade adicionando #:property PublishAot=false no topo do seu ficheiro.

Use o dotnet publish comando para criar um executável independente:

dotnet publish file.cs

A localização padrão do executável é um artifacts diretório ao lado do .cs ficheiro, com um subdiretório nomeado em homenagem à aplicação. Use a --output opção com o dotnet publish comando para especificar um caminho diferente.

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. Desative esta definição adicionando #:property PackAsTool=false no topo do seu ficheiro.

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 faz uma cópia do .cs ficheiro e cria um .csproj ficheiro com itens equivalentes do SDK, propriedades e referências de pacotes com base nas diretivas #: do ficheiro original. Ambos os ficheiros são colocados num diretório nomeado para a aplicação ao lado do ficheiro original .cs , que permanece intocado.

Restaurar dependências

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

dotnet restore file.cs

Por predefinição, a restauração é executada implicitamente quando constrói ou executa a sua aplicação. No entanto, podes passar --no-restore tanto para os comandos dotnet build quanto para dotnet run para construir ou executar sem restaurar implicitamente.

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

Liste segredos de utilizador para aplicações baseadas em ficheiros:

dotnet user-secrets list --file file.cs

O dotnet user-secrets list comando imprime o valor dos teus segredos. Não coloques este comando em scripts que correm em contextos públicos.

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

Observação

Use terminações de linha LF em vez de CRLF quando adicionar um shebang. Não inclua um BOM no ficheiro.

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 de build para melhorar o desempenho nas invocações subsequentes de dotnet run. Este sistema de cache é exclusivo das aplicações baseadas em ficheiros.

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.
Existência implícita do ficheiro de build e conteúdo.

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

Limpe artefactos de cache para aplicações baseadas em ficheiros usando o seguinte comando:

dotnet clean file-based-apps

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.