From dotnet-skills
Running C# without a project file (.NET 10 SDK). Directives, CLI commands, migration.
npx claudepluginhub wshaddix/dotnet-skillsThis skill uses the workspace's default tool permissions.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Captures architectural decisions in Claude Code sessions as structured ADRs. Auto-detects choices between alternatives and maintains a docs/adr log for codebase rationale.
.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.
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 DirectiveAdds a NuGet package reference. Specify the package name, optionally followed by @version.
#:package Newtonsoft.Json
#:package Serilog@3.1.1
#:package Spectre.Console@*
Version behavior:
@version -- pins to a specific version@* -- uses the latest stable version (NuGet floating version)Directory.Packages.props file; otherwise, specify a version explicitly or use @*#:sdk DirectiveSpecifies which SDK to use. Defaults to Microsoft.NET.Sdk if omitted.
#:sdk Microsoft.NET.Sdk.Web
#:sdk Aspire.AppHost.Sdk@9.2.0
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 DirectiveSets an MSBuild property value. Use this to customize build behavior.
#:property TargetFramework=net10.0
#:property PublishAot=false
Property directives support MSBuild property functions and expressions for conditional configuration.
Environment variables with defaults:
#:property LogLevel=$([MSBuild]::ValueOrDefault('$(LOG_LEVEL)', 'Information'))
Conditional expressions:
#:property EnableLogging=$([System.Convert]::ToBoolean($([MSBuild]::ValueOrDefault('$(ENABLE_LOGGING)', 'true'))))
#:project DirectiveReferences another project file or directory containing a project file. Use this to share code between a file-based app and a traditional project.
#:project ../SharedLibrary/SharedLibrary.csproj
The referenced project is built and linked as a project reference, just like <ProjectReference> in a .csproj.
The .NET CLI supports file-based apps through familiar commands.
# Preferred: pass file directly
dotnet run app.cs
# Explicit --file option
dotnet run --file app.cs
# Shorthand (no 'run' subcommand)
dotnet app.cs
# Pass arguments after --
dotnet run app.cs -- arg1 arg2
When a .csproj exists in the current directory, dotnet run app.cs (without --file) runs the project and passes app.cs as an argument to preserve backward compatibility. Use dotnet run --file app.cs to force file-based execution.
echo 'Console.WriteLine("hello");' | dotnet run -
The - argument reads C# code from standard input. Useful for quick testing and shell script integration.
dotnet build app.cs
Build output goes to a cached location under the system temp directory by default. Override with --output or #:property OutputPath=./output.
# Clean build artifacts for a specific file
dotnet clean app.cs
# Clean all file-based app caches in the current directory
dotnet clean file-based-apps
# Clean caches unused for N days (default: 30)
dotnet clean file-based-apps --days 7
dotnet publish app.cs
File-based apps enable native AOT by default. The output goes to an artifacts directory next to the .cs file. Disable AOT with #:property PublishAot=false.
dotnet pack app.cs
File-based apps set PackAsTool=true by default. Disable with #:property PackAsTool=false.
dotnet restore app.cs
Restore runs implicitly on build/run. Pass --no-restore to dotnet build or dotnet run to skip it.
Enable direct execution on Unix-like systems with a shebang line.
#!/usr/bin/env dotnet
#:package Spectre.Console
using Spectre.Console;
AnsiConsole.MarkupLine("[green]Hello, World![/]");
chmod +x app.cs
./app.cs
The file must use LF line endings (not CRLF) and must not include a BOM.
File-based apps support launch profiles via a flat [AppName].run.json file in the same directory as the source file. For app.cs, create app.run.json:
{
"profiles": {
"https": {
"commandName": "Project",
"launchBrowser": true,
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
Select a profile with --launch-profile:
dotnet run app.cs --launch-profile https
If both app.run.json and Properties/launchSettings.json exist, the traditional location takes priority.
File-based apps generate a stable user secrets ID from the file's full path.
dotnet user-secrets set "ApiKey" "your-secret-value" --file app.cs
dotnet user-secrets list --file app.cs
File-based apps respect MSBuild and NuGet configuration files in the same or parent directories:
Directory.Build.props -- inherited MSBuild propertiesDirectory.Build.targets -- inherited MSBuild targetsDirectory.Packages.props -- Central Package Management versionsnuget.config -- NuGet package source configurationglobal.json -- SDK version pinningBe mindful of these files when placing file-based apps in a repository that also contains traditional projects. Inherited properties may cause unexpected build behavior.
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:
Directory.Build.props, etc.) may not trigger rebuildsdotnet build app.cs, then run multiple instances with dotnet run app.cs --no-buildClear the cache with dotnet clean app.cs or dotnet clean file-based-apps.
Do not place file-based apps inside a .csproj project's directory tree. The project's implicit build configuration will interfere.
# Recommended layout
repo/
src/
MyProject/
MyProject.csproj
Program.cs
scripts/ # Separate directory for file-based apps
utility.cs
tool.cs
When a file-based app outgrows a single file, convert to a traditional project.
dotnet project convert app.cs
This creates a new directory named after the app, containing:
.csproj with equivalent SDK, properties, and package references derived from the #: directives.cs file with #: directives removedThe original .cs file is left untouched.
Convert to a project-based app when:
#:property supportsdotnet test with a test framework.csprojFile-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/ |
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].#: 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.#: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@*.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..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.dotnet build app.cs, then run instances with dotnet run app.cs --no-build..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.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 file or directory.