dotnet-nitro 0.1.3

Dotnet Nitro

Fast partial builds and headless debugging for .NET — like HotReload, but it actually works.

nitro is a dotnet global tool that watches your solution, rebuilds only what changed, and relaunches your app in seconds. It also ships a headless DAP debugger (nitro debug) designed for scripting and AI agents.

Install

dnx dotnet-nitro

or

dotnet tool install -g dotnet-nitro

Getting Started

1. Start the watcher

Navigate to your solution root (where the .sln is) and run:

cd MyApp/
dnx dotnet-nitro

nitro auto-detects your project — no config needed if you have a single solution. It will:

• Prompt you to pick a launch profile (from launchSettings.json)
• Build and start your app
• Watch for file changes and rebuild/relaunch automatically

2. Edit a file

Save any .cs, .razor, .cshtml, or .csproj file. nitro detects the change within the polling interval (default: 2s) and runs:

dotnet build <ChangedProject> --no-dependencies

Only the changed project is compiled. Dependencies are left alone. Your app restarts in under a second on large solutions.

3. Check the TUI

The terminal shows a scrolling log and a status bar at the bottom:

──────────────────────────────────────────────────────────────
⠙ RUNNING  ● App  [MyApp | Development]  PID 12345  http://localhost:5000
[S]top [R]elaunch [F]ull rebuild [Space]Check [P]artial [A]uto [W]arnings [D]ebug [Q]uit

Watch Mode

Basic usage

dnx dotnet-nitro                         # auto-detect from CWD
dnx dotnet-nitro --host MyApp.sln        # explicit solution
dnx dotnet-nitro --output bin/Release    # custom output dir
dnx dotnet-nitro --exe MyApp.exe         # custom exe name
dnx dotnet-nitro --interval 5            # poll every 5 seconds

Multiple profiles

If your launchSettings.json has multiple profiles, dotnet-nitro shows an interactive picker on startup. Press L at any time to switch profiles without restarting dotnet-nitro.

External mode (LAN access)

Press E to toggle external mode. dotnet-nitro rewrites localhost bindings to 0.0.0.0 and displays the machine's outbound IP so other devices on the network can reach your app.

Keyboard shortcuts

Verification build

20 seconds after a successful launch, dotnet-nitro runs a full dotnet build of the host project in a temp directory (without disturbing the running app). If cross-project errors are found, the app is stopped and the status shows VERIFY FAILED. Toggle this with V.

Debug Mode

dnx dotnet-nitro debug attaches netcoredbg to your app, hits breakpoints, captures variable snapshots, and exits — no IDE required. Output is JSON, designed for scripts and AI agents.

Auto-detection

nitro debug Program.cs:42     # finds running app automatically

If your app is not running, dnx dotnet-nitro debug builds and launches it first, then attaches. Same inference rules as watch mode.

Breakpoint syntax

Breakpoints are positional args — no JSON, no config files.

dnx dotnet-nitro debug File.cs:LINE
dnx dotnet-nitro debug File.cs:LINE?CONDITION
dnx dotnet-nitro debug File.cs:LINE#HITS
dnx dotnet-nitro debug File.cs:LINE?CONDITION#HITS
dnx dotnet-nitro debug Namespace.Class.Method          # function breakpoint

Examples

# Break at line 42 of Program.cs
dnx dotnet-nitro debug Program.cs:42

# Break at line 88 only when x > 5
dnx dotnet-nitro debug OrderService.cs:88?x>5

# Break on the 2nd hit of line 88
dnx dotnet-nitro debug OrderService.cs:88#2

# Multiple breakpoints + function breakpoint
dnx dotnet-nitro debug Program.cs:42 OrderService.cs:88 OrderService.PlaceOrder

# Attach to a specific PID
dnx dotnet-nitro debug --pid 12345 Program.cs:42

# Catch all user-unhandled exceptions
dnx dotnet-nitro debug --exception UserUnhandled

# List running managed (.NET) processes
dnx dotnet-nitro debug --list

Target options

--pid <id>            Attach to this PID directly
--process <name>      Find process by name
--dll <path>          Launch a DLL (instead of attach)
--exception <filter>  Exception filter (repeatable): UserUnhandled, All
--timeout <seconds>   Session timeout, default: 30
--list                List running managed processes and exit

Output format

{
  "snapshots": [
    {
      "index": 0,
      "reason": "breakpoint",
      "location": "OrderService.cs:88",
      "function": "OrderService.PlaceOrder",
      "stack": [
        { "function": "OrderService.PlaceOrder", "location": "OrderService.cs:88" },
        { "function": "Program.Main", "location": "Program.cs:12" }
      ],
      "locals": {
        "order": { "Id": 1, "Total": 99.9, "Status": "Pending" },
        "retries": 2
      },
      "exception": null
    }
  ],
  "terminated": false,
  "elapsed_ms": 1234
}

On error:

{ "error": "process_not_found", "message": "No running process named 'MyApp'" }

How it works

Partial builds

On each file-change cycle, dotnet-nitro identifies which .csproj owns the changed files and runs:

dotnet build <project.csproj> --no-dependencies --nologo -o <outputDir>

When multiple projects change simultaneously, they are sorted topologically (dependencies first) and built in sequence.

Project inference

dotnet-nitro finds your project the same way the dotnet CLI does:

1. Single .sln in CWD → use it
2. No .sln, single .csproj in CWD → use it
3. Multiple → error: use --host to specify

Dependency graph

dotnet-nitro parses <ProjectReference> entries from every .csproj at startup to build a dependency graph used for topological sorting. No MSBuild is invoked for this step.

FAQ

Q: Why not dotnet watch? dotnet watch restarts the entire build on every change. dotnet-nitro only rebuilds the project that changed. On a 30-project solution, this makes a huge difference.

Q: Why not HotReload? HotReload can't patch all types of changes (added methods, changed generics, static constructors). dotnet-nitro doesn't try — it just relaunches, which always works.

Q: Is state lost on each relaunch? Yes, by design. Consistent, predictable behavior beats clever patching.

Q: Does it work with ASP.NET Core? Yes. It reads launchSettings.json and sets ASPNETCORE_URLS and ASPNETCORE_ENVIRONMENT from the selected profile.

Q: Does it work without a launchSettings.json? Yes. dotnet-nitro falls back to launching the exe with no extra configuration.

DEV

git tag 0.1.2
dotnet pack -c Release
dotnet tool install dotnet-nitro --version 0.0.0-preview.0.3 --add-source .\Source\dotnet-nitro\nupkg\ --verbosity detailed