ContextQMD
Back to Uno

Dev Server

doc/articles/dev-server.md

6.6-release-branch-cut8.6 KB
Original Source

Dev Server

The Dev Server is the local development companion that enables productive inner-loop features in Uno Platform, such as Hot Reload, design-time updates, and IDE integration. It runs as a lightweight HTTP process and maintains a bidirectional channel with the IDE and the running application.

Overview

  • Provides a transport between the IDE and the running application to exchange development-time messages
  • Powers Hot Reload and Hot Design experiences by delivering code and XAML updates
  • Starts automatically and stays out of the way; you usually do not have to configure it

Prerequisites

  • Requires .NET SDK, same version as uno
  • Works in Debug builds, where connection information is embedded so the app can reach the Dev Server

When and how the Dev Server starts

[!NOTE] The Dev Server starts only when Uno Platform packages are referenced by your project(s).

[!NOTE] The Dev Server won't start until NuGet package restore has completed successfully (a failed or pending restore prevents startup).

  1. Open the solution: the IDE reserves a free TCP port and writes it to each project's .csproj.user file under the UnoRemoteControlPort property.
  2. Build/run in Debug: the app is built with the Dev Server connection information.
  3. Launch the app (Debug): the app connects back to the Dev Server.
  4. Develop: the IDE and app exchange development-time messages (e.g., Hot Reload updates).

Command-line (advanced usage for specific scenarios)

You can manage the Dev Server from the command line using the dotnet tool Uno.DevServer (command: uno-devserver):

  • uno-devserver start: Start the Dev Server for the current solution directory

  • uno-devserver stop: Stop the Dev Server attached to the current directory

  • uno-devserver list: List running Dev Server instances

  • uno-devserver disco: Inspect the environment — see Diagnostics (disco)

  • uno-devserver cleanup: Terminate stale Dev Server processes

  • uno-devserver login: Open the Uno Platform settings application

  • uno-devserver mcp status [<client>]: Inspect Uno MCP registration state across supported clients

  • uno-devserver mcp install <client> | --all-ides: Register the Uno MCP entries for a supported client (or all detected clients)

  • uno-devserver mcp uninstall <client> | --all-ides: Remove the Uno MCP entries for a supported client (or all detected clients)

    These commands accept additional flags: --workspace, --channel, --tool-version, --servers, --all-scopes, --dry-run, --json. When the target agent provides a CLI (Claude Code, Codex, Gemini), mcp install delegates to the agent's own mcp add command automatically, falling back to file-based registration when the CLI is not available. See The Uno Platform MCPs — Command reference for details.

  • --mcp-app: Run an MCP proxy mode for integration with MCP-based tooling

  • --port | -p <int>: Optional port value for MCP proxy mode

  • --mcp-wait-tools-list: Wait for the upstream Uno App tools to become available before responding to clients. Use this when working with MCP agents that do not react to tools/list_changed (for example, Codex or Claude Code).

  • --force-roots-fallback: Legacy explicit override. The DevServer auto-detects when the client does not advertise the MCP roots capability and exposes the uno_app_initialize tool automatically, so this flag is rarely needed.

  • --force-generate-tool-cache: Deprecated (no-op). Kept for backward compatibility.

  • --solution-dir <path>: Explicit solution directory Uno.DevServer should monitor. Useful when starting the DevServer manually (e.g., CI agents). Defaults to the current working directory when omitted.

For more information about Uno MCP registration, native-client alternatives, and supported MCP workflows, see The Uno Platform MCPs.

Hot Reload

The Dev Server enables Hot Reload for a faster inner loop:

  • C# Hot Reload for managed code changes
  • XAML and resource updates without restarting the app
  • Asset updates in supported scenarios

Security

  • Uses a random local port, making it hard to guess
  • Intended for local development only and relies on your local network security
  • Do not expose the Dev Server to untrusted networks

[!IMPORTANT] The Dev Server is a development-time facility. It is not required nor recommended for production deployments.

Troubleshooting

Common issues

[!TIP] Run uno-devserver disco to inspect your Dev Server environment at a glance. Look for <null> values — they indicate missing components. See Diagnostics (disco) for details.

  • The TCP port number used by the app to connect back to the IDE is located in the <UnoRemoteControlPort> property of the [ProjectName].csproj.user file. If the port number does not match with the one found in the Uno Platform - Hot Reload output window, restart your IDE.
  • If the Dev Server does not start, ensure NuGet restore has completed successfully and Uno Platform packages are referenced by your project(s).

Visual Studio

  • The Output window in Visual Studio includes an output category named Uno Platform. Diagnostic messages from the Uno Platform VS extension appear there. To enable logging, set MSBuild project build output verbosity to at least "Normal" (above "Minimal"). These changes should take effect immediately without a restart; if you do not see additional logs, try restarting Visual Studio. For more details on build log verbosity, refer to the official Visual Studio documentation.

    If you need to share logs when opening an issue on the GitHub Uno Platform repository, set verbosity to Diagnostic to provide the most detailed logs for investigation.

    Steps to change MSBuild output verbosity:

    1. Open Tools > Options > Projects and Solutions > Build and Run, then set MSBuild output verbosity to Diagnostic or the required level.

    2. Restart Visual Studio, re-open your solution, and wait a few seconds.

    3. Go to View > Output.

    4. In the Output window, select Uno Platform from the drop-down.

Visual Studio Code

  • The Output window in Visual Studio Code includes an output category named Uno Platform in its drop-down menu. Diagnostic messages from the Uno Platform VS Code extension appear there.

    Steps to see the Uno Platform output:

    1. In the status bar at the bottom left of VS Code, ensure NameOfYourProject.csproj is selected (by default NameOfYourProject.sln is selected).

    2. Wait a few seconds.

    3. Go to View > Output.

    4. In the Output window, select Uno Platform from the drop-down.

Rider

  • The Output window in Rider includes an output category named Uno Platform in its sidebar. Diagnostic messages from the Uno Platform Rider plugin appear there.

    Steps to see the Uno Platform output:

    1. In the sidebar at the bottom left of Rider, click on the Uno Platform logo.

    2. In the Output window, select LEVEL: Trace from the drop-down.

See also