skip to content

With the .NET 10 SDK, how does dotnet run app.cs build a file-based app, and what do its #:package, #:sdk, #:property and #:project directives do?

level: seniorimportance: should knowfreq 36%

answer

  1. a virtual project, no .csproj
  2. #: directives at the top of the file
  3. #:package Name@Version
  4. publish defaults to Native AOT
  5. dotnet project convert

basics

~20 s

dotnet run app.cs generates a virtual project from the file's #: directives, builds it into a cached temp folder and runs it; #:package adds a NuGet reference, #:sdk picks the project SDK, #:property sets an MSBuild property and #:project references a project.

solid answer

~40 s

A file-based app is one `.cs` file with no project file. The .NET 10 SDK reads the `#:` directives at the top, synthesizes a project in memory, builds it into a cache under the temp directory and runs it, reusing the build when nothing changed. `#:package Name@Version` adds a package reference (`@*` takes the latest; omitting the version only works with Central Package Management). `#:sdk Microsoft.NET.Sdk.Web` swaps the default `Microsoft.NET.Sdk`. `#:property Name=Value` sets any MSBuild property, and `#:project ../Lib` references a project. The same file works with `dotnet build`, `dotnet publish` (Native AOT by default), `dotnet pack` (`PackAsTool` by default) and `dotnet project convert`. If a project file sits in the current folder, `dotnet run app.cs` runs that project instead, so use `--file`.

code

csharp · 12 lines
csharp
#!/usr/bin/env -S dotnet --
#:package [email protected]
#:property PublishAot=false
#:project ../PressCore/PressCore.csproj

using PressCore;

var csv = args.Length > 0 ? args[0] : "orders.csv";
foreach (var order in OrderFile.Read(csv))
{
    LabelPrinter.Print(order);
}

go deeper

for a junior

Recall that .NET 10 can run a single .cs file with dotnet run app.cs and that #: lines at the top configure packages and properties.

for a middle

Explain the virtual project, the four directives and their syntax, and the cached build that makes repeat runs fast.

for a senior

Show the traps: AOT by default on publish, the project-in-folder argument behaviour, quotes rejected in directives, and when to convert the file into a project.

for a principal

Judge where file-based apps belong in a team: good for scripts and tooling in a repository, but they should graduate to projects once they need tests, shared code or a review-friendly build definition.

## What a file-based app is The .NET 10 SDK can build and run a C# program that is **a single `.cs` file with no `.csproj`**. You run it with `dotnet run labels.cs`, `dotnet run --file labels.cs` or the shorthand `dotnet labels.cs`. Behind the scenes the SDK creates a **virtual project**: it reads the file's directives, generates the project MSBuild would otherwise read from disk, restores and builds it, and runs the result. Build output goes to a per-file cache under the system temp directory (`<temp>/dotnet/runfile/<app>-<hash>/`), and an unchanged file reuses the previous build. The print shop's `labels.cs` prints shipping labels from a CSV; it started as a quick script and is now a tool other staff run. ## The directives Directives start with `#:` and go at the top of the file, before any code: | Directive | Effect | Example | |---|---|---| | `#:package` | adds a NuGet package reference | `#:package [email protected]` | | `#:sdk` | sets the project SDK (default `Microsoft.NET.Sdk`) | `#:sdk Microsoft.NET.Sdk.Web` | | `#:property` | sets an MSBuild property | `#:property PublishAot=false` | | `#:project` | references another project | `#:project ../PressCore/PressCore.csproj` | Rules worth remembering: - `#:package` takes `Name@Version`; `@*` means the latest version. Omitting the version only works when a `Directory.Packages.props` file supplies it through Central Package Management. - `#:sdk` also accepts `Name@Version` for SDKs delivered as packages. - `#:property` values may use MSBuild property functions. - Double quotes inside a directive are a build error in .NET 10 GA; move such values into a `Directory.Build.props` file, which file-based apps also pick up. - `#:include` (other `.cs` files, globs) arrived later, in SDK 10.0.300. On Unix a first line of `#!/usr/bin/env -S dotnet --` plus `chmod +x` makes the file directly executable. ## The other verbs 1. `dotnet build labels.cs` compiles into the cache (or `-o` elsewhere). 2. `dotnet publish labels.cs` produces an executable in an `artifacts` folder next to the file. File-based apps set **`PublishAot=true` by default**, so the result is a Native AOT executable; `#:property PublishAot=false` opts out when a dependency is not AOT-compatible. 3. `dotnet pack labels.cs` packs a .NET tool, because `PackAsTool` defaults to `true` for file-based apps. 4. `dotnet clean labels.cs` removes its outputs; `dotnet clean file-based-apps` prunes cache folders unused for 30 days (`--days` changes that). 5. `dotnet project convert labels.cs` writes a folder with a copy of the file and a `.csproj` holding the equivalent items and properties, leaving the original untouched. ## The project-in-the-folder trap For backward compatibility, when a project file exists in the current directory, `dotnet run labels.cs` runs **that project** and passes `labels.cs` to it as a command-line argument. Use `dotnet run --file labels.cs` in any folder that also holds a `.csproj`. ## When to convert A file-based app suits scripts, utilities and samples. Convert when the tool needs several source files with shared types, test projects that reference it, or settings that do not fit a directive. Conversion is one command and keeps the directives' meaning, so starting small costs nothing. ## Restore, packages and shared settings A file-based app restores like any project: the first `dotnet run` downloads the packages named by `#:package`, and later runs reuse them. Because the virtual project is evaluated by MSBuild, files the SDK normally imports still apply: a `Directory.Build.props` above the file sets properties, and a `Directory.Packages.props` lets `#:package` omit its version. That is also the escape hatch for values a directive cannot express.

  • Why might dotnet publish fail or warn on a file-based app that runs fine?
    Publishing a file-based app defaults to Native AOT, which rejects or warns about code that needs runtime reflection or dynamic loading, while `dotnet run` uses the normal JIT build. Adding `#:property PublishAot=false` publishes a regular build instead.
  • How do you pass arguments that look like dotnet options to the app?
    Put them after `--`: `dotnet run labels.cs -- --verbose today.csv`. Everything after the separator goes to the program instead of being parsed by `dotnet run`.

  • dotnet run app.cs interprets the file like a script without compiling it.
  • #:package with no version always resolves the latest stable package.
  • Publishing a file-based app gives a framework-dependent build like a console project.
  • #: directives can appear anywhere in the file, even after code.
  • Moving to a .csproj means rewriting every directive by hand.

Assumes the .NET 10 SDK (10.0.4xx); file-based apps arrived in .NET 10, and #:include needs SDK 10.0.300 or later.