Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
.NET 10 SDK file-based apps let you build, run, and publish C# applications from a single .cs file without creating a
.csproj project file. The SDK auto-generates project configuration from #: directives embedded in the source file.
This feature targets scripts, utilities, and small applications where traditional project scaffolding is unnecessary.
This is NOT file I/O. For FileStream, RandomAccess, FileSystemWatcher, and path handling, see
[skill:dotnet-file-io].
Prerequisites: Requires .NET 10 SDK or later. Run [skill:dotnet-version-detection] to confirm SDK version.
Cross-references: [skill:dotnet-version-detection] for SDK version gating, [skill:dotnet-project-analysis] for
project-based analysis (file-based apps have no .csproj), [skill:dotnet-scaffold-project] for csproj-based project
scaffolding.
Scope
#: directives (package, sdk, property, project)
CLI commands for file-based apps (dotnet run, dotnet publish)
Migration from file-based to .csproj project format
Out of scope
File I/O (FileStream, RandomAccess, paths) -- see [skill:dotnet-file-io]
Project-based .csproj scaffolding -- see [skill:dotnet-scaffold-project]
Solution structure analysis -- see [skill:dotnet-project-analysis]
Directives Overview
File-based apps use #: directives to configure the build. Directives are SDK-level instructions, not C# syntax.
They must appear at the top of the .cs file, before any C# code.
Four directive types are supported:
Directive
Purpose
Example
#:package
Add a NuGet package reference
#:package Serilog@3.1.1
#:sdk
Set the SDK (default: Microsoft.NET.Sdk)
#:sdk Microsoft.NET.Sdk.Web
#:property
Set an MSBuild property
#:property PublishAot=false
#:project
Reference another project file
#:project ../Lib/Lib.csproj
#:package Directive
Adds a NuGet package reference. Specify the package name, optionally followed by @version.
#:package Newtonsoft.Json#:package Serilog@3.1.1#:package Spectre.Console@*
```csharp
Version behavior:
- **`@version`** -- pins to a specific version
- **`@*`** -- uses the latest stable version (NuGet floating version)
- **No version** -- only works when Central Package Management (CPM) is configured with a `Directory.Packages.props`
file; otherwise, specify a version explicitly or use `@*`
---
## `#:sdk` Directive
Specifies which SDK to use. Defaults to `Microsoft.NET.Sdk` if omitted.
```csharp
#:sdk Microsoft.NET.Sdk.Web
```csharp
```csharp
#:sdk Aspire.AppHost.Sdk@9.2.0
```csharp
Use this directive to access SDK-specific features. For example, `Microsoft.NET.Sdk.Web` enables ASP.NET Core features
and automatically includes `*.json` configuration files in the build.
---
## `#:property` Directive
Sets an MSBuild property value. Use this to customize build behavior.
```csharp
#:property TargetFramework=net10.0#:property PublishAot=false
```csharp
### Conditional Property Values
Property directives support MSBuild property functions and expressions for conditional configuration.
**Environment variables with defaults:**
```csharp
#:property LogLevel=$([MSBuild]::ValueOrDefault('$(LOG_LEVEL)', 'Information'))
```csharp
**Conditional expressions:**
```csharp
#:property EnableLogging=$([System.Convert]::ToBoolean($([MSBuild]::ValueOrDefault('$(ENABLE_LOGGING)', 'true'))))
```csharp
---
## `#:project` Directive
References another project fileor directory containing a project file. Use to share code between a -based app
a traditional project.
```csharp
```csharp
The referenced project built linked a project reference, just like `<ProjectReference>` a `.csproj`.
---
The .NET CLI supports -based apps through familiar commands.
```bash
dotnet run app.cs
dotnet run -- app.cs
dotnet app.cs
dotnet run app.cs -- arg1 arg2
```csharp
When a `.csproj` exists the current directory, `dotnet run app.cs` (without `--`) runs the project passes
`app.cs` an argument to preserve backward compatibility. Use `dotnet run -- app.cs` to force -based
execution.
```bash
echo | dotnet run -
```bash
The `-` argument reads C
```bash
dotnet build app.cs
```bash
Build output goes to a cached location under the system temp directory . Override `--output`
`
```bash
dotnet clean app.cs
dotnet clean -based-apps
dotnet clean -based-apps --days
```text
```bash
dotnet publish app.cs
```bash
File-based apps enable **native AOT **. The output goes to an `artifacts` directory next to the `.cs` .
Disable AOT `
```bash
dotnet pack app.cs
```bash
File-based apps `PackAsTool=` . Disable `
```bash
dotnet restore app.cs
```bash
Restore runs implicitly build/run. Pass `--no-restore` to `dotnet build` `dotnet run` to skip it.
---
Enable direct execution Unix-like systems a shebang line.
```csharp
Spectre.Console;
AnsiConsole.MarkupLine();
```text
```bash
chmod +x app.cs
./app.cs
```bash
The must use `LF`
{
: {
: {
: ,
: ,
: ,
: {
:
}
}
}
}
```text
Select a profile `--launch-profile`:
```bash
dotnet run app.cs --launch-profile https
```bash
If both `app.run.json` `Properties/launchSettings.json` exist, the traditional location takes priority.
---
File-based apps generate a stable user secrets ID the s directory tree. The project
this
file
and
#:project ../SharedLibrary/SharedLibrary.csproj
is
and
as
in
## CLI Commands
file
### Run
# Preferred: pass file directly
# Explicit --file option
file
# Shorthand (no 'run' subcommand)
# Pass arguments after --
in
file
and
as
file
file
### Pipe from stdin
'Console.WriteLine("hello");'
# code from standard input. Useful for quick testing and shell script integration.
### Build
by
default
with
or
#:property OutputPath=./output`.
### Clean
# Clean build artifacts for a specific file
# Clean all file-based app caches in the current directory
file
# Clean caches unused for N days (default: 30)
file
7
### Publish
by
default
file
with
#:property PublishAot=false`.
### Pack as .NET Tool
set
true
by
default
with
#:property PackAsTool=false`.
### Restore
on
or
## Shell Execution (Unix)
on
with
#!/usr/bin/env dotnet
#:package Spectre.Console
using
"[green]Hello, World![/]"
file
line endings (not `CRLF`) and must not include a BOM.
---
## Launch Profiles
File-based apps support launch profiles via a flat `[AppName].run.json` filein the same directory as the source file.
For `app.cs`, create `app.run.json`:
```json
"profiles"
"https"
"commandName"
"Project"
"launchBrowser"
true
"applicationUrl"
"https://localhost:5001;http://localhost:5000"
"environmentVariables"
"ASPNETCORE_ENVIRONMENT"
"Development"
with
and
## User Secrets
from
file
's full path.
```bash
dotnet user-secrets set "ApiKey" "your-secret-value" --file app.cs
dotnet user-secrets list --file app.cs
```bash
---
## Implicit Build Files
File-based apps respect MSBuild and NuGet configuration files in the same or parent directories:
- **`Directory.Build.props`** -- inherited MSBuild properties
- **`Directory.Build.targets`** -- inherited MSBuild targets
- **`Directory.Packages.props`** -- Central Package Management versions
- **`nuget.config`** -- NuGet package source configuration
- **`global.json`** -- SDK version pinning
Be mindful of these files when placing file-based apps in a repository that also contains traditional projects.
Inherited properties may cause unexpected build behavior.
---
## Build Caching
The SDK caches build outputs based on source content, directives, SDK version, and implicit build files. Caching
improves repeated `dotnet run` performance.
Known caching pitfalls:
- Changes to implicit build files (`Directory.Build.props`, etc.) may not trigger rebuilds
- Moving files to different directories does not invalidate the cache
- **Concurrent execution** of the same file-based app can cause build contention errors -- build first with
`dotnet build app.cs`, then run multiple instances with `dotnet run app.cs --no-build`
Clear the cache with `dotnet clean app.cs` or `dotnet clean file-based-apps`.
---
## Folder Layout
Do not place file-based apps inside a `.csproj` project'
's implicit build configuration
will interfere.
```csharp
# Recommended layout
repo/
src/
MyProject/
MyProject.csproj
Program.cs
scripts/ # Separate directory for file-based apps
utility.cs
tool.cs
```csharp
---
## Migration: File-Based to Project-Based
When a file-based app outgrows a single file, convert to a traditional project.
### Automatic Conversion
```bash
dotnet project convert app.cs
```bash
This creates a new directory named after the app, containing:
- A `.csproj` with equivalent SDK, properties, and package references derived from the `#:` directives
- A copy of the `.cs` file with `#:` directives removed
The original `.cs` file is left untouched.
### When to Convert
Convert to a project-based app when:
- Multiple source files are needed
- Complex MSBuild customization is required beyond what `#:property` supports
- The app needs `dotnet test` with a test framework
- The app needs integration with CI/CD workflows that expect a `.csproj`
- Team members need IDE project support (Solution Explorer, etc.)
---
## Default Behaviors
File-based apps differ from project-based apps in several default settings:
| Setting | File-based default | Project-based default |
| --------------------------- | ------------------------------- | ----------------------------- |
| Native AOT (`PublishAot`) | `true` | `false` |
| Pack as tool (`PackAsTool`) | `true` | `false` |
| Build output location | System temp directory | `bin/` in project directory |
| Publish output location | `artifacts/` next to `.cs` file | `bin/<config>/<tfm>/publish/` |
---
## Agent Gotchas
1. **Do not confuse file-based apps with file I/O** -- `dotnet-file-based-apps` covers running C# without a project file
(`.NET 10 SDK feature`). For FileStream, RandomAccess, and path handling, use [skill:dotnet-file-io].
2. **Do not use `#:` directives after C# code** -- all directives must appear at the top of the file, before any C#
statements, `using` directives, or namespace declarations. The SDK ignores directives placed later in the file.
3. **Do not omit package versions without CPM** -- `#:package SomePackage` without a version only works when Central
Package Management is configured via `Directory.Packages.props`. Without CPM, use `#:package SomePackage@1.0.0` or
`#:package SomePackage@*`.
4. **Do not assume `dotnet build` and `dotnet test` work the same** -- `dotnet build app.cs` compiles via a virtual
project, but `dotnet test` does not apply to file-based apps. Convert to a project for test framework support.
5. **Do not place file-based apps inside a `.csproj` project directory** -- the project'
s implicit build files
(`Directory.Build.props`, etc.) will affect the file-based app, causing unexpected behavior. Use a separate
directory.
6. **Do not run concurrent instances without pre-building** -- parallel execution of the same file-based app causes
build output contention. Build first with `dotnet build app.cs`, then run instances with
`dotnet run app.cs --no-build`.
7. **Do not forget backward compatibility** -- when a `.csproj` exists in the current directory, `dotnet run app.cs`
passes `app.cs` as an argument to the project rather than running it as a file-based app. Use
`dotnet run --file app.cs` to force file-based execution.
8. **Do not use `CRLF` line endings with shebang** -- Unix shebang execution requires `LF` line endings and no BOM.
Files with `CRLF` will fail with `/usr/bin/env: 'dotnet\r': No such fileor directory`.
---
## References
- [File-based apps - .NET](https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps)
- [Native AOT deployment](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/)
- [Central Package Management](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management)
- [MSBuild property functions](https://learn.microsoft.com/en-us/visualstudio/msbuild/property-functions)
