Running on .NET 11
Repl ships for net10.0 and net11.0 from 0.12.1. These notes are for developers who build or run a Repl application with the .NET 11 SDK. Some of the tools below predate .NET 11 (dotnet run -e, dnx) or ship on their own (dotnetup), and are here because .NET 11 developers meet them. Each point was checked with the .NET SDK 11.0.100; the platform is named where it matters.
C# 15 and union results
Section titled “C# 15 and union results”A net11.0 project compiles C# 15 by default, so it can declare a union without setting LangVersion; the same declaration does not compile in a net10.0 project with its default language version. A handler can return a union, and Repl processes its active case: see Union return values.
FORCE_COLOR
Section titled “FORCE_COLOR”The .NET 11 console logger (Microsoft.Extensions.Logging.Console) colors its output when FORCE_COLOR has any non-empty value, even 0, including on a redirected stream and ahead of NO_COLOR (checked on Linux). Repl applies the same rule to its own output, so one variable colors both. Forcing color onto a file or a pipe does not make Repl write terminal control sequences there (screen clearing, shell-integration marks, progress); the exact rules are in ANSI capability levels.
System.Console reads the same variable for the colors an application sets through Console.ForegroundColor. On Linux, with FORCE_COLOR set, they are written to a redirected stream when TERM names a terminal whose terminfo describes colors (checked with xterm-256color), and not when TERM is unset or dumb. On Windows they are not written to a redirected stream, whatever FORCE_COLOR says. Repl writes its colors as ANSI sequences itself, so its output does not depend on TERM’s terminfo.
dotnet watch
Section titled “dotnet watch”dotnet watch starts the application with its standard input, output and error attached to the terminal, not redirected (checked on Windows and Linux), so Repl detects a terminal and starts the interactive loop. But dotnet watch keeps the keyboard for its own keys, and the application does not receive what is typed: on Linux, none of the keys sent while the application was reading reached it, with or without --non-interactive.
Use dotnet watch for one-shot commands, which it runs again on each change, and dotnet run for the interactive loop:
dotnet watch run -- contact list --jsondotnet rundotnet run -e
Section titled “dotnet run -e”dotnet run -e NAME=value passes an environment variable to the application for that run, which is a quick way to try environment-driven behavior (checked on Windows and Linux):
dotnet run -e FORCE_COLOR=1 -- contact list > contacts.txtdotnet run -e NO_COLOR=1dotnetup installs and agent hosts
Section titled “dotnetup installs and agent hosts”dotnetup (in public preview) installs .NET per user, by default in %LOCALAPPDATA%\dotnetup\dotnet on Windows and ~/.local/share/dotnetup/dotnet on Linux; macOS was not checked. According to the dotnetup documentation, its access mode decides who finds that installation:
| Mode | What it changes | Default on |
|---|---|---|
none | No environment variable | Linux and macOS when dotnetup does not recognize the shell |
shell | PATH and DOTNET_ROOT in the shell profile only | Linux and macOS when dotnetup recognizes the shell |
everywhere | The system PATH, and DOTNET_ROOT for the user | Windows |
A host that was already running keeps its environment until it restarts.
With none or shell, an agent host or IDE that does not start from that shell does not find the dotnetup dotnet or dnx: it finds none, or another installation that comes first on its PATH. When no other .NET installation is present, a framework-dependent executable, such as a .NET global tool, also stops with “You must install .NET to run this application”. This was checked on Linux with dotnetup as the only installation.
The configurations below use the default folders above; if dotnetup installed .NET elsewhere (--install-path), use that folder instead. For an MCP server registered in such a host, use one of the first three entries below in the host’s configuration; the last section covers a tool built for an older .NET.
Run dnx through the dotnetup dotnet
Section titled “Run dnx through the dotnetup dotnet”The absolute path of the dotnetup dotnet finds its own runtime. dnx runs the newest stable version; to stay on one version, install the tool and use the next entry.
{ "mcpServers": { "myapp": { "command": "/home/me/.local/share/dotnetup/dotnet/dotnet", "args": ["dnx", "-y", "MyApp", "--", "mcp", "serve"] } }}{ "mcpServers": { "myapp": { "command": "C:\\Users\\me\\AppData\\Local\\dotnetup\\dotnet\\dotnet.exe", "args": ["dnx", "-y", "MyApp", "--", "mcp", "serve"] } }}Keep a global tool and set DOTNET_ROOT
Section titled “Keep a global tool and set DOTNET_ROOT”A framework-dependent executable, such as a global tool, runs when DOTNET_ROOT points to the installation.
{ "mcpServers": { "myapp": { "command": "/home/me/.dotnet/tools/myapp", "args": ["mcp", "serve"], "env": { "DOTNET_ROOT": "/home/me/.local/share/dotnetup/dotnet" } } }}{ "mcpServers": { "myapp": { "command": "C:\\Users\\me\\.dotnet\\tools\\myapp.exe", "args": ["mcp", "serve"], "env": { "DOTNET_ROOT": "C:\\Users\\me\\AppData\\Local\\dotnetup\\dotnet" } } }}Publish self-contained
Section titled “Publish self-contained”A self-contained build needs no .NET installation, and also works for a project packed as a tool. Use the published executable as command:
dotnet publish -c Release -r linux-x64 --self-contained # -r win-x64 on WindowsA tool built for an older .NET
Section titled “A tool built for an older .NET”A tool built for an older major version than the one installed, such as a net10.0 tool with only .NET 11 in the dotnetup folder, stops with “You must install or update .NET to run this application”, through dnx too. Install that runtime with dotnetup, target both net10.0 and net11.0, or let the tool run on the newer runtime: put --allow-roll-forward before the package name in the dnx arguments, or add "DOTNET_ROLL_FORWARD": "Major" to the global tool entry’s env. The error and both roll-forward options were checked on Linux with only the .NET 11 runtime installed.
See also
Section titled “See also”- Packaging & Distribution — global tools and MCP server registry entries
- Customization & Output — color and terminal control
- For Coding Agents
- Running on .NET 11 in the Repl repository