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@3.1.1
#:package Spectre.Console@*

Observação

Omitir o número de versão após o nome do pacote atualmente só funciona se você usar o gerenciamento central de pacotes com um arquivo Directory.Packages.props. Caso contrário, especifique o número de versão explicitamente ou adicione @* após o nome do pacote para usar a versão mais recente.

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

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

dotnet run --file file.cs

Ou use o dotnet run comando seguido pelo nome do arquivo:

dotnet run file.cs

Observação

Quando um arquivo de projeto existe no diretório de trabalho atual, dotnet run file.cs sem a opção --file executa esse projeto e passa file.cs como um argumento para o aplicativo de destino para preservar a compatibilidade com versões anteriores.

Ou use a sintaxe abreviada:

dotnet file.cs

Passar argumentos

Passe argumentos para seu aplicativo colocando-os após --:

dotnet run file.cs -- arg1 arg2

Código de pipe do stdin

Encaminhe o 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 da entrada padrão em vez de um arquivo. Com o - argumento, dotnet run não pesquisa o diretório de trabalho atual em busca de outros arquivos, como perfis de inicialização. O diretório atual ainda é o diretório de trabalho para compilar e executar o programa.

PowerShell:

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

Bash:

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

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

Criar aplicativos

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

dotnet build file.cs

O SDK gera um projeto virtual e cria seu aplicativo. Por padrão, a saída de build vai para o diretório temporário do sistema em <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

Use a opção --output com o dotnet build comando para especificar um caminho diferente. Para definir um novo caminho de saída padrão, defina a OutputPath propriedade na parte superior do arquivo usando a diretiva: #:property OutputPath=./output.

Limpar saídas de build

Remova artefatos de build usando o dotnet clean comando:

dotnet clean file.cs

Excluir cache para aplicativos baseados em arquivo em um diretório:

dotnet clean file-based-apps

Use a opção --days com o comando anterior para especificar quantos dias uma pasta de artefato precisa ser não utilizada antes da remoção. O número padrão de dias é 30.

Publicar aplicativos

Os aplicativos baseados em arquivo permitem a publicação AOT nativa por padrão, produzindo executáveis otimizados e autocontidos. Desabilite esse recurso adicionando #:property PublishAot=false na parte superior do arquivo.

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

dotnet publish file.cs

O local padrão do executável é um artifacts diretório ao lado do .cs arquivo, com um subdiretório com o nome do aplicativo. Use a opção --output com o dotnet publish comando para especificar um caminho diferente.

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. Desabilite essa configuração adicionando #:property PackAsTool=false na parte superior do arquivo.

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 faz uma cópia do .cs arquivo e cria um .csproj arquivo com itens, propriedades e referências de pacote equivalentes do SDK com base nas diretivas do #: arquivo original. Ambos os arquivos são colocados em um diretório nomeado para o aplicativo ao lado do arquivo original .cs , que é deixado intocado.

Restaurar dependências

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

dotnet restore file.cs

Por padrão, a restauração é executada implicitamente quando você cria ou executa seu aplicativo. No entanto, você pode passar --no-restore para ambos os comandos dotnet build e dotnet run para compilar ou executar sem a restauração implícita.

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, o único arquivo C# é incluído.

SDKs diferentes incluem outros tipos de arquivo:

Microsoft.NET.Sdk.Web inclui arquivos de configuração *.json.
Os SDKs não padrão incluem arquivos de recurso ResX.

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

Listar segredos do usuário para aplicativos baseados em arquivo:

dotnet user-secrets list --file file.cs

O comando dotnet user-secrets list exibe o valor de seus segredos. Não coloque esse comando em scripts executados em contextos públicos.

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

Observação

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

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 invocações subsequentes de dotnet run. Esse sistema de cache é exclusivo para aplicativos baseados em arquivo.

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.
Conteúdo e existência de arquivo de build implícito.

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

Limpe caches para aplicativos baseados em arquivos usando o seguinte comando:

dotnet clean file-based-apps

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.

❌ Não recomendado:

📁 repo/
├── Directory.Build.props  // Affects everything below
├── app1.cs
└── app2.cs

✅ Recomendado:

📁 repo/
├── Directory.Build.props
├──📁 projects/
│   └── MyProject.csproj
└──📁 scripts/
    ├── Directory.Build.props  // Isolated configuration
    ├── app1.cs
    └── app2.cs

Consulte também

Comentários

Esta página foi útil?

Last updated on 2026-01-08

Compartilhar via

Aplicativos baseados em arquivo

Diretivas com suporte

#:package

#:project

#:property

#:sdk

Comandos da CLI

Executar aplicativos

Passar argumentos

Código de pipe do stdin

Criar aplicativos

Limpar saídas de build

Publicar aplicativos

Criar pacote como ferramenta

Converter em projeto

Restaurar dependências

Itens incluídos padrão

Publicação do AOT nativo

Segredos do usuário

Perfis de inicialização

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

Vários aplicativos baseados em arquivo

Seleção de perfil

Configurações de inicialização tradicionais

Execução do shell

Arquivos de build implícitos

Directory.Build.props

Directory.Build.targets

Directory.Packages.props

nuget.config

global.json

Compilar cache

Comportamento do cache

Soluções alternativas

Recomendações de layout de pasta

Evitar cones de arquivo de projeto

Esteja atento aos arquivos implícitos

Consulte também

Comentários

Recursos adicionais

`#:package`

`#:project`

`#:property`

`#:sdk`

`Directory.Build.props`

`Directory.Build.targets`

`Directory.Packages.props`

`nuget.config`

`global.json`