Run and manage .NET 10+ file-based apps directly from Visual Studio Code. The extension also recognizes explicitly tagged C# block comments and provides Markdown hover/preview and syntax highlighting for embedded code.
Website · 繁體中文 · Releases
Installation
Download the latest dotnet-file-apps-toolkit.vsix, then run Extensions: Install from VSIX... in the VS Code Command Palette. Alternatively, run this from the download directory:
code --install-extension ./dotnet-file-apps-toolkit.vsix
Each stable GitHub Release includes the VSIX, release notes, and SHA256SUMS. The download link becomes available after the first stable release. Repeat the installation with a newer VSIX to update manually.
Once published to the Visual Studio Marketplace, you can also install by searching for PoyChang.dotnet-file-apps-toolkit. The repository's Marketplace workflow is opt-in; a prepared manifest does not mean the listing is already live.
Requirements
| Component |
Requirement |
| Visual Studio Code |
1.100 or later |
| .NET SDK |
10.0.100 or later |
| Workspace |
Trusted for commands that execute the .NET SDK |
The extension host must be able to access the dotnet executable. Set dotnetFileAppsToolkit.dotnetPath if it is not on PATH.
.NET file-based apps
Create a standalone .cs file, for example:
#:property PublishAot=false
Console.WriteLine("Hello from a file-based app!");
By default, the toolkit recognizes files beginning with #: directives or a dotnet shebang. The File Detection setting can also recognize standalone top-level C# files outside project folders, or restrict recognition to files you explicitly enable.
Use the editor title actions, Command Palette (.NET File Apps), or the commands below:
| Command |
Operation |
| Run File |
Run the selected file with dotnet run --file |
| Run with Arguments… |
Run with separately parsed application arguments (no shell expansion) |
| Run with Launch Profile… |
Select a Project or Executable profile from Properties/launchSettings.json or <AppName>.run.json |
| Restore / Build / Clean File |
Run the corresponding file-based .NET CLI operation |
| Publish Executable… |
Publish to a selected output folder |
| Pack as Tool |
Package the file as a .NET tool; #:property PackAsTool=false disables this action |
| Clean File-Based App Cache… |
Confirm and remove cached artifacts unused for at least 30 days by default |
| Manage File-Based App Directives… |
Add/update #:package references or inspect/edit existing #:sdk, #:property, #:project, and #:include directives |
| Manage Project References… |
List, add, or remove #:project references with the .NET 11 SDK or later |
| Format File… |
Format the file-based app with the .NET formatter (requires .NET 11 SDK or later) |
| Convert to Project… |
Create a project folder and keep the original file unchanged |
| Check .NET SDK |
Show the SDK selected for the file's folder |
| More Actions… |
Open the file's action picker |
| Copy Tagged Comment Body |
Copy the exact body at the cursor to the clipboard |
| Extract Tagged Comment to File… |
Confirm and write a dedented standalone file; the body is never executed |
The toolkit prompts before saving unsaved changes by default. Published file-based apps use Native AOT by default; this requires the platform's native toolchain. Add #:property PublishAot=false to publish a framework-dependent app instead.
Directive edits are applied to the open document after confirmation; adding a package does not restore it or run the app.
The dotnet-file-app task type is available for tasks.json (run, restore, build, clean, publish, and pack):
{
"version": "2.0.0",
"tasks": [
{
"type": "dotnet-file-app",
"action": "build",
"file": "${workspaceFolder}/hello.cs",
"problemMatcher": []
}
]
}
Only explicit /*tag block comments are interpreted; ordinary and XML documentation comments are left alone. Tags are case-insensitive.
/*markdown
## Deployment
Run the **deploy** script after validating the configuration.
*/
/*yaml
environment: production
features:
- validate
*/
/*json
{
"enabled": true
}
*/
/*markdown supports a rendered hover and a full preview panel. Use Preview Tagged Comments from the editor, the Command Palette, or the link at the bottom of the hover to open the preview.
Because VS Code hovers cannot be styled by extensions, the hover draws tables with box-drawing characters (tables wider than about 60 columns keep the native layout) and marks simple > quotes with a theme-colored bar. Command links and raw HTML written in the comment are still never executed or rendered.
The preview's Copy button and the Copy Tagged Comment Body command copy the exact source body. Extract Tagged Comment to File… uses the normalized body, asks before creating or overwriting a file, and never executes it.
Preview screenshots
| Dark theme |
Light theme |
 |
 |
Supported tags and aliases:
| Language |
Tags |
| Markdown |
markdown, md |
| YAML |
yaml, yml |
| JSON |
json |
| SQL |
sql |
| XML |
xml |
| Bash |
bash, sh, shell |
| PowerShell |
powershell, ps1 |
| C# |
csharp, cs |
| JavaScript |
javascript, js, cjs, mjs |
| TypeScript |
typescript, ts, cts, mts |
| HTML |
html, htm |
| CSS |
css |
| Python |
python, py |
| C++ |
cpp, c++, cxx |
| TOML |
toml |
| INI |
ini, cfg, conf |
| Dockerfile |
dockerfile, docker |
| CSV |
csv |
The preview renders Markdown and syntax-highlighted code using bundled grammars for all listed code tags. In the native C# editor, VS Code's TextMate injection grammar provides embedded scopes when the corresponding language grammar is installed. Depending on the active C# semantic-highlighting provider and theme, color decorations may be used to restore code colors and to color /*markdown bodies like a .md file (plain text uses the editor foreground instead of the comment color).
YAML/JSON validation is opt-in. Enable dotnetFileAppsToolkit.comments.validation.enabled to publish source-mapped syntax diagnostics and add a collapsible structure outline to the preview; the outline shows keys and value types, not scalar values.
Settings
| Setting |
Default |
Description |
dotnetFileAppsToolkit.enabled |
true |
Enable toolkit commands and editor actions. |
dotnetFileAppsToolkit.fileDetection |
strict |
strict, standalone, or manual file-app detection. |
dotnetFileAppsToolkit.dotnetPath |
dotnet |
.NET executable path used by the extension host (machine setting). |
dotnetFileAppsToolkit.autoSaveBeforeRun |
prompt |
prompt, always, or never before CLI actions. |
dotnetFileAppsToolkit.codeLens.enabled |
false |
Show Run File and More Actions CodeLens at the top of recognized file-based apps. |
dotnetFileAppsToolkit.run.args |
[] |
Default Run File arguments; each entry is passed as one argument. |
dotnetFileAppsToolkit.comments.enabled |
true |
Enable tagged-comment scanning, hover, decorations, and preview. |
dotnetFileAppsToolkit.comments.highlight.enabled |
true |
Enable editor color and Markdown emphasis decorations. |
dotnetFileAppsToolkit.comments.highlight.strategy |
auto |
auto, injection, decorations, or off. |
dotnetFileAppsToolkit.comments.markdown.hover |
true |
Show rendered Markdown hover. |
dotnetFileAppsToolkit.comments.previewOnOpen |
false |
Automatically open previews for files with tagged comments. |
dotnetFileAppsToolkit.comments.unknownTagDiagnostic |
false |
Report unknown language tags as information diagnostics. |
dotnetFileAppsToolkit.comments.validation.enabled |
false |
Validate tagged YAML/JSON and show an expandable structure preview. |
Compatibility and limitations
| Environment |
Behavior |
| VS Code 1.100+ |
Supported |
| .NET SDK 10.0.100+ |
File-based app commands supported |
| .NET SDK 10.0.300+ |
Adds the SDK's #:include support for source files |
| .NET SDK 11+ |
Adds the SDK's #:include DLL and file-based dotnet reference command support |
| Windows, Linux, macOS |
Covered by CI; the .NET SDK and platform requirements still apply |
| Remote workspace |
Commands run through the extension host where dotnet is installed |
| Virtual workspace |
Not supported for file-based app commands |
Additional notes:
- The TextMate injection grammar is a static VS Code contribution. It cannot be disabled by this extension's settings, including
comments.enabled, highlight.enabled, and strategy off; those settings control the extension's own decorations and preview behavior.
auto chooses injection for high-contrast themes and when semantic highlighting is disabled. When a C# semantic token provider is present, it may add bundled Light+/Dark+ color decorations. Those colors are not derived from every user's custom theme.
/*markdown bodies get .md-style colors (headings, emphasis, inline code, links, lists, quotes, fenced code, inline HTML) only through color decorations: strategy decorations, or auto with a C# semantic token provider or C# extension. Otherwise the body keeps the comment color and only gets bold, italic, inline-code, and link emphasis (none with strategy off).
- Tagged JSON uses the editor foreground for structural separators and the theme's bracket-pair colors for matched
{} and [] pairs. This also applies in injection mode, follows editor.bracketPairColorization.enabled, and does not change JSON editing behavior inside the comment.
- Content on the same line as the closing
*/ is not included by the native injection grammar; the preview and decorations can still highlight it.
- The .NET SDK/MSBuild currently rejects some special characters in source file names, including
;, %, and '. Spaces and Unicode names are supported; shell metacharacters are passed without shell expansion.
- Native AOT publishing needs a native toolchain (on Windows, Visual Studio's Desktop development with C++ workload). Use
PublishAot=false to avoid it.
- Every command that starts the .NET SDK, including run, build, publish, convert, pack, project references, format, cache cleanup, and Check .NET SDK, is unavailable in Restricted Mode. MSBuild files, and a
global.json whose sdk.paths selects an SDK inside the folder, can run code from the workspace. Workspace values of dotnetPath and run.args are also ignored there. Review and trust a workspace before running its code.
- The preview sanitizes rendered content and only allows remote images in a trusted workspace.
Development
npm ci
npm run lint
npm run check-types
npm run test:unit
npm run test:publishing
npm run test:integration
npm run vsix
Linux integration tests require a display server such as Xvfb. npm run test:integration runs the main suite, then a separate suite in Restricted Mode with workspace trust enabled.
Website and publishing
The static website lives in docs/. Run npm run build:site to stage it with shared images in out/site/, then serve that directory with a local static HTTP server. No framework or additional dependencies are required.
See PUBLISHING.md for GitHub Pages setup, version-tag releases, Marketplace publisher registration, and OIDC Trusted Publishing. Website changes deploy from main; stable vX.Y.Z tags build tested VSIX releases.
License
MIT