NetFabric/NetFabric.Numerics / .agents/skills/csharp-file-based-app
csharp-file-based-app
VerifiedBuild, run, and publish .NET applications from a single C# file without a .csproj, using .NET 10 SDK file-based apps. USE FOR: dotnet run file.cs; dotnet run --file; shebang/shell-executable C# scripts; colon-prefixed directives (sdk, package, project, property, include); converting a file-based app to a project with dotnet project convert; publishing file-based apps with native AOT; packaging a file-based app as a .NET tool (PackAsTool); user secrets for file-based apps; flat *.run.json launch profiles; dotnet build/clean/publish/pack/restore on a .cs file; build caching behavior and dotnet clean file-based-apps; folder layout to avoid project-file cone conflicts. DO NOT USE FOR: traditional .csproj solution scaffolding (use dotnet-solution-setup); C# language idioms unrelated to the SDK/CLI (use csharp-best-practices); benchmarking (use dotnet-benchmarking).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.1 KB |
| references/directives-reference.md | markdown | 2.1 KB |
| references/runtime-behavior.md | markdown | 4.4 KB |
references/runtime-behavior.md
View on GitHub# Runtime Behavior Reference
## Shell Execution
Enable direct execution on Unix-like systems via shebang + executable bit.
```csharp
#!/usr/bin/env -S dotnet --
#:package Spectre.Console
using Spectre.Console;
AnsiConsole.MarkupLine("[green]Hello, World![/]");
```
```bash
chmod +x file.cs
./file.cs
```
- `-S` lets `env` split the shebang into separate args so `--` can be included; `--` tells `dotnet` to forward all remaining args to the app instead of parsing them as its own flags.
- If `-S` isn't supported, fall back to `#!/usr/bin/env dotnet` β but then `dotnet` may consume args that collide with its own CLI parameters (e.g. `--help`).
- Use `LF` line endings, no BOM.
## User Secrets
File-based apps get a stable user-secrets ID hashed from the full file path β no `UserSecretsId` property needed.
```bash
dotnet user-secrets set "ApiKey" "your-secret-value" --file file.cs
dotnet user-secrets list --file file.cs
```
`list` prints secret values in plain text β don't run it in scripts executed in public/CI logs.
## Launch Profiles
Flat launch settings file named `<AppName>.run.json`, next to the `.cs` file, instead of `Properties/launchSettings.json`:
```json
{
"profiles": {
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "http://localhost:5000",
"environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" }
}
}
}
```
Multiple apps in one directory each get their own file:
```text
π myapps/
βββ foo.cs
βββ foo.run.json
βββ bar.cs
βββ bar.run.json
```
Profile selection order: `--launch-profile` flag β `DOTNET_LAUNCH_PROFILE` env var β first profile in the file.
```bash
dotnet run app.cs --launch-profile https
```
If both `<AppName>.run.json` and `Properties/launchSettings.json` exist, the traditional location wins; the CLI logs a warning.
## Build Caching
The SDK caches build output keyed on: source file content, directive configuration, SDK version, and implicit build file existence/content.
Gotchas:
- Changes to implicit build files (`Directory.Build.props`, etc.) may not trigger a rebuild.
- Moving a file to a different directory doesn't invalidate its cache entry.
- Running multiple instances of the same file-based app concurrently can race over shared build output β `dotnet build file.cs` once first, then start concurrent instances with `dotnet run file.cs --no-build`.
Workarounds:
```bash
dotnet clean file-based-apps # purge all cached artifacts (default: unused 30+ days)
dotnet clean file-based-apps --days 7 # custom retention window
dotnet clean file.cs && dotnet build file.cs # force a clean rebuild for one app
```
## Implicit Build Files
File-based apps respect MSBuild/NuGet files found in the same or parent directories:
| File | Effect |
|------|--------|
| `Directory.Build.props` | Shared MSBuild properties |
| `Directory.Build.targets` | Custom build targets, executed during build |
| `Directory.Packages.props` | Central package management |
| `nuget.config` | Package sources |
| `global.json` | Pins the SDK version used |
## Folder Layout Recommendations
**Avoid project file cones** β don't put file-based apps inside a `.csproj`'s directory tree; its implicit settings can interfere.
```text
β π MyProject/
βββ MyProject.csproj
βββ Program.cs
βββ π scripts/
βββ utility.cs # bad: inside the project cone
β
π MyProject/
βββ MyProject.csproj
βββ Program.cs
π scripts/
βββ utility.cs # good: sibling, outside the cone
```
**Isolate from ambient implicit files** β a repo-root `Directory.Build.props` affects every file-based app beneath it; give scripts their own directory (and its own `Directory.Build.props`) when they need different settings.
```text
β π repo/
βββ Directory.Build.props # affects everything below
βββ app1.cs
βββ app2.cs
β
π repo/
βββ Directory.Build.props
βββ π projects/
β βββ MyProject.csproj
βββ π scripts/
βββ Directory.Build.props # isolated
βββ app1.cs
βββ app2.cs
```
## Default Included Items
- The single `.cs` file is always included.
- `Microsoft.NET.Sdk.Web` also includes `*.json` config files.
- Non-default SDKs may include ResX resource files.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |