Aplicativos baseados em arquivo

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

Os aplicativos baseados em arquivo permitem que você crie, execute e publique aplicativos .NET de um único arquivo C# sem criar um arquivo de projeto tradicional. Eles oferecem uma alternativa leve aos projetos tradicionais do .NET. Essa abordagem simplifica o desenvolvimento de scripts, utilitários e aplicativos pequenos. O SDK do .NET gera automaticamente a configuração de projeto necessária com base nas diretivas em seu arquivo de origem.

Entre os principais benefícios estão:

Clichê reduzido para aplicativos simples.
Arquivos de origem autossuficientes com configuração embutida.
Publicação AOT nativa habilitada por padrão.
Ferramentas do .NET para empacotamento automático.

Neste artigo, saiba como criar, configurar e trabalhar com aplicativos baseados em arquivo com eficiência.

Diretivas com suporte

Os aplicativos baseados em arquivo usam diretivas prefixadas #: para configurar o build e executar o aplicativo. As diretivas com suporte incluem: #:package, #:project, #:property, e #:sdk. Coloque essas diretivas na parte superior do arquivo C#.

`#:package`

Adiciona uma referência de pacote NuGet ao seu aplicativo.

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

`#:project`

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

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Define um valor da propriedade MSBuild.

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

`#:sdk`

Especifica o SDK a ser usado. Usa Microsoft.NET.Sdk como padrão.

#:sdk Microsoft.NET.Sdk.Web

Comandos da CLI

A CLI do .NET fornece suporte completo para aplicativos baseados em arquivo por meio de comandos familiares.

Executar aplicativos

Execute um aplicativo baseado em arquivo diretamente usando o dotnet run comando:

dotnet run file.cs

Ou use a sintaxe abreviada:

dotnet file.cs

Passar argumentos

Passe argumentos para seu aplicativo de várias maneiras:

dotnet run file.cs -- arg1 arg2

Os argumentos após o -- são passados para seu aplicativo. Sem --, os argumentos vão para o dotnet run comando:

dotnet run file.cs arg1 arg2

No entanto, com a sintaxe abreviada, todos os argumentos vão para seu aplicativo:

dotnet file.cs arg1 arg2

Criar aplicativos

Compile seu aplicativo baseado em arquivo usando o dotnet build comando:

dotnet build file.cs

O SDK gera um projeto temporário e cria seu aplicativo.

Limpar saídas de build

Remova artefatos de build usando o dotnet clean comando:

dotnet clean file.cs

Limpe todos os aplicativos baseados em arquivo em um diretório:

dotnet clean file-based-apps

Publicar aplicativos

Crie um pacote de implantação usando o dotnet publish comando:

dotnet publish file.cs

Os aplicativos baseados em arquivo permitem a publicação AOT nativa por padrão, produzindo executáveis otimizados e autocontidos.

Criar pacote como ferramenta

Empacote seu aplicativo baseado em arquivo como uma ferramenta .NET usando o dotnet pack comando:

dotnet pack file.cs

Apps baseados em arquivos são definidos PackAsTool=true por padrão.

Converter em projeto

Converta seu aplicativo baseado em arquivo em um projeto tradicional usando o dotnet project convert comando:

dotnet project convert file.cs

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

Restaurar dependências

Restaure os pacotes NuGet referenciados em seu arquivo usando o dotnet restore comando:

dotnet restore file.cs

A restauração é executada implicitamente quando você cria ou executa seu aplicativo.

Itens incluídos padrão

Os aplicativos baseados em arquivo incluem automaticamente tipos de arquivo específicos para compilação e empacotamento.

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

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

SDKs diferentes incluem outros tipos de arquivo:

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

Publicação do AOT nativo

Os aplicativos baseados em arquivo habilitam a compilação AOT (ahead-of-time) nativa por padrão. Esse recurso produz executáveis otimizados e autocontidos com inicialização mais rápida e um menor consumo de memória.

Se você precisar desabilitar o AOT nativo, use a seguinte configuração:

#:property PublishAot=false

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

Segredos do usuário

Aplicativos baseados em arquivo geram uma ID de segredos de usuário estável com base em um hash do caminho de arquivo completo. Essa ID permite armazenar a configuração confidencial separadamente do código-fonte.

Acesse os segredos do usuário da mesma maneira que os projetos tradicionais:

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

Para obter mais informações, consulte Armazenamento seguro de segredos do aplicativo no desenvolvimento.

Perfis de inicialização

Aplicativos baseados em arquivo dão suporte a perfis de inicialização para configurar como o aplicativo é executado durante o desenvolvimento. Em vez de colocar perfis de inicialização em Properties/launchSettings.json, aplicativos baseados em arquivos podem usar um arquivo de configurações de inicialização plano nomeado [ApplicationName].run.json no mesmo diretório que o arquivo de origem.

Arquivo de configurações de inicialização simples

Crie um arquivo de configurações de inicialização com o nome do aplicativo. Por exemplo, se o seu aplicativo que utiliza arquivos 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"
      }
    }
  }
}

Vários aplicativos baseados em arquivo

Quando você tem vários aplicativos baseados em arquivo no mesmo diretório, cada aplicativo pode ter seu próprio arquivo de configurações de inicialização:

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

Seleção de perfil

A CLI do .NET seleciona perfis de inicialização usando a seguinte prioridade:

O perfil especificado pela opção --launch-profile .
O perfil especificado pela variável de ambiente DOTNET_LAUNCH_PROFILE.
O primeiro perfil definido no arquivo de configurações de inicialização.

Para executar com um perfil específico:

dotnet run app.cs --launch-profile https

Configurações de inicialização tradicionais

Aplicativos baseados em arquivo também dão suporte ao arquivo tradicional Properties/launchSettings.json . Se ambos os arquivos existirem, o local tradicional tem prioridade. Se ambos os arquivos estiverem presentes, a CLI do .NET registrará um aviso para esclarecer qual arquivo é usado.

Execução do shell

Habilite a execução direta de aplicativos baseados em arquivos em sistemas semelhantes ao Unix utilizando linha shebang e permissões executáveis.

Adicione um shebang na parte superior do arquivo:

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

using Spectre.Console;

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

Torne o arquivo executável:

chmod +x file.cs

Execute diretamente:

./file.cs

Arquivos de build implícitos

Aplicativos baseados em arquivos respeitam arquivos de configuração do MSBuild e do NuGet no mesmo diretório ou diretórios pai. Esses arquivos afetam como o SDK cria seu aplicativo. Lembre-se desses arquivos ao organizar seus aplicativos baseados em arquivo.

`Directory.Build.props`

Define as propriedades do MSBuild que se aplicam a todos os projetos em uma árvore de diretório. Aplicativos baseados em arquivo herdam essas propriedades.

`Directory.Build.targets`

Define os destinos do MSBuild e a lógica de build personalizada. Os aplicativos baseados em arquivo executam esses destinos durante a compilação.

`Directory.Packages.props`

Habilita o gerenciamento de pacote central para dependências do NuGet. Aplicativos baseados em arquivo podem usar versões de pacote gerenciadas centralmente.

`nuget.config`

Define as fontes e as configurações do pacote NuGet. Aplicativos baseados em arquivo usam essas configurações ao restaurar pacotes.

`global.json`

Especifica a versão do SDK do .NET a ser usada. Os aplicativos baseados em arquivo respeitam essa seleção de versão.

Compilar cache

O SDK do .NET armazena em cache saídas de build para melhorar o desempenho em builds subsequentes. Aplicativos baseados em arquivo participam desse sistema de cache.

Comportamento do cache

O SDK armazena em cache saídas de build com base em:

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

O cache melhora o desempenho do build, mas pode causar confusão quando:

As alterações nos arquivos de build implícitos não disparam recompilações.
Mover arquivos para diretórios diferentes não invalida o cache.

Soluções alternativas

Execute um build completo usando a flag --no-cache.
```
dotnet build file.cs --no-cache
```
Force uma compilação limpa para ignorar o cache:
```
dotnet clean file.cs
dotnet build file.cs
```

Recomendações de layout de pasta

Organize seus aplicativos baseados em arquivos cuidadosamente para evitar conflitos com projetos tradicionais e arquivos de build implícitos.

Evitar cones de arquivo de projeto

Não coloque aplicativos baseados em arquivo na estrutura de diretório de um .csproj projeto. As configurações e os arquivos de build implícitos do arquivo de projeto podem interferir no aplicativo baseado em arquivo.

❌ 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

Esteja atento aos arquivos implícitos

Arquivos de build implícitos em diretórios pai afetam todos os aplicativos que operam com arquivos em subdiretórios. Crie diretórios isolados para aplicativos baseados em arquivo quando precisar de configurações de build diferentes.