Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
.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)
