Document .NET 11 file-based apps: DLL includes, dotnet reference, and Native AOT reuse

[Copilot]

The file-based apps article was missing coverage of several new .NET 11 capabilities: splitting apps into multiple files, reusing Native AOT build outputs, dotnet reference support, and including compiled DLL references.

#:include enhancements

• Added *.dll → Reference item-type mapping so file-based apps can reference prebuilt libraries directly:

  #:include ./libs/MyLibrary.dll

• Documented that #:sdk, #:property, and #:package can now appear as duplicates across included files as long as their values match, enabling self-contained library files with their own dependencies.

dotnet reference support

• Added guidance on managing #:project references via the CLI instead of editing directives by hand:

  dotnet reference add --file app.cs ../SharedLibrary/SharedLibrary.csproj
  dotnet reference list --file app.cs
  dotnet reference remove --file app.cs ../SharedLibrary/SharedLibrary.csproj
  

Native AOT build output reuse

• Added a new "Reuse Native AOT build outputs" subsection describing cached launches (dotnet run --file app.cs, dotnet run app.cs, dotnet app.cs), fallback behavior when cached output doesn't match current arguments, dotnet format support for file-based apps, and how the SDK artifacts layout affects output location.

Each new capability is called out with a version note indicating .NET 11+ availability.

• Fixes Add detail for new features in file-based apps #55890

---

Internal previews

File	Preview link
docs/core/sdk/file-based-apps.md	Learn preview

Build report

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

One moderate issue and three documentation gaps remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

docs/core/sdk/file-based-apps.md:286

• dotnet run app.cs isn't always a file-based-app launch: the earlier run section says that when a project file exists in the current directory, this form runs that project and passes app.cs as an argument. Listing it unqualified as a cached file-based-app launch is misleading; qualify it with the no-project-file condition or use dotnet run --file app.cs here.

The native AOT command-line path can reuse existing build outputs when it runs an unchanged file-based app. Supported cached launches include `dotnet run --file app.cs`, `dotnet run app.cs`, and `dotnet app.cs`. If the cached output doesn't match the current command arguments, the CLI falls back to the managed path.

docs/core/sdk/file-based-apps.md:88

• The dotnet reference support isn't limited to #:project: .NET 11 also supports file-based-app references through #:ref, and the CLI can add, list, and remove those references. Because the new section omits that path, users can't discover how to compose multiple file-based apps; please document #:ref and a corresponding --file example, and update the supported-directives list.

Instead of manually editing `#:project` directives, you can use the `dotnet reference` command to manage project references in a file-based app. Use the `--file` option to specify the file-based app:

> [!NOTE]
> `dotnet reference` support for file-based apps is available in .NET 11 and later.

docs/core/sdk/file-based-apps.md:294

• The new sentence introduces the “SDK artifacts layout” without linking to or explaining how to enable it, and it conflicts with the earlier description of the default output as <temp>/dotnet/runfile/... (line 196). Link to the artifacts output layout article and use the same default-path terminology so readers can configure and locate the output.

When a repository enables the SDK artifacts layout, file-based app outputs are placed under that repository's artifacts directory instead of the default per-user cache.

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

[wadepickett]

@meaghanlewis, Great work. Approved, assuming the one open item already identified for version scoping is addressed. I will watch for any re-approval needed..