Skip to content

NetFabric/NetFabric.Numerics / .agents/skills/csharp-file-based-app

csharp-file-based-app

Verified

Build, 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).

FileKindSize
SKILL.mdskill md4.1 KB
references/directives-reference.mdmarkdown2.1 KB
references/runtime-behavior.mdmarkdown4.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.
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: 469kUpdated Claude CodeCodexVerifiedInstall
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: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall