Skip to content
| Marketplace
Sign in
Visual Studio Code>Programming Languages>.NET File Apps ToolkitNew to Visual Studio Code? Get it now.
.NET File Apps Toolkit

.NET File Apps Toolkit

Poy Chang

| (0) | Free
Run, restore, convert and preview .NET 10+ file-based apps (single .cs files), with language-tagged comment rendering for /*markdown, /*yaml, /*json and more.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

.NET File Apps Toolkit

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": []
    }
  ]
}

Tagged comments

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
Tagged comment preview in a dark theme Tagged comment preview in a 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

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft