Skip to content

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.

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.

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 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:

Terminal window
dotnet watch run -- contact list --json
dotnet run

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):

Terminal window
dotnet run -e FORCE_COLOR=1 -- contact list > contacts.txt
dotnet run -e NO_COLOR=1

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:

ModeWhat it changesDefault on
noneNo environment variableLinux and macOS when dotnetup does not recognize the shell
shellPATH and DOTNET_ROOT in the shell profile onlyLinux and macOS when dotnetup recognizes the shell
everywhereThe system PATH, and DOTNET_ROOT for the userWindows

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.

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

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" }
}
}
}

A self-contained build needs no .NET installation, and also works for a project packed as a tool. Use the published executable as command:

Terminal window
dotnet publish -c Release -r linux-x64 --self-contained # -r win-x64 on Windows

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.