CLR Probe: Read Live .NET Application State with NSP

The CLR probe gives your agents direct access to the live state of any .NET application running on the host machine. It works by injecting a managed C# bootstrapper DLL into the target process using the Windows CLR Hosting API, then communicating with that bootstrapper over a Memory-Mapped File (MMF) channel to read managed objects, field values, and method return values. No source code is needed, and the target application does not need to be restarted or modified.

Supported Applications

The CLR probe covers any application built on .NET 4.x or .NET 6+. Known supported applications include:

Productivity software: Microsoft Excel, Word, PowerPoint, and the broader Office suite
Developer tools: Visual Studio, Azure CLI tools
GCS and simulation: Mission Planner
Custom desktop apps: All WinForms applications, all WPF applications
Any .NET application targeting .NET Framework 4.x or .NET 6 and later

How the CLR Probe Works

The CLR probe uses a three-stage injection and extraction pipeline.

Inject the CLR bootstrapper — NSP uses the Windows CLR Hosting API to load a native bootstrapper DLL into the target process. The bootstrapper initialises a managed C# runtime environment inside the target and opens an MMF channel for communication with the NSP daemon.
Walk the CLR heap using managed reflection — Once the managed bridge is running inside the target process, it walks the CLR heap using reflection to discover managed object instances, read their field values, and resolve type metadata — all without requiring debug symbols or PDB files.
Transmit state over the MMF channel — Field values and type metadata are serialised and sent back to the NSP daemon through the MMF bridge, where they are normalised into SSF JSON and cached as a SubstrateState object.

.NET Version Compatibility

The CLR probe requires .NET Framework 4.8 or later installed on the host machine. This runtime ships pre-installed on Windows 10 and Windows 11, so most machines are already compatible. You can verify by running reg query "HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full" /v Release in a terminal.For applications targeting .NET 6 or later (the modern unified runtime), the probe uses the same MMF bridge approach but targets the CoreCLR runtime instead of the .NET Framework CLR. Both code paths produce identical SubstrateState output.

Prerequisites

Windows 10 or Windows 11 x64 — the Windows CLR Hosting API is Windows-only
.NET Framework 4.8 installed (pre-installed on Windows 10/11)
NSP daemon running (see Quickstart)

No changes to the target .NET application are required.

What the Probe Reads

Once attached, the CLR probe exposes the following data in every SubstrateState:

Data Type	Description
Managed objects	Live CLR heap instances for all application-owned types
Field values	Instance and static field values across the managed object graph
Type metadata	Class name, namespace, field names, and declared types
Method return values	Return values of selected property getters, captured on demand

Performance Characteristics

Metric	Value
Accuracy	>97%
Fast-path poll latency	~50 ms
Cold probe duration	3–90 s
Expected confidence range	`0.93 – 0.97`

Reading CLR App State

Once the daemon detects a .NET application and the cold probe completes, attach to it from the Python SDK using the application’s name.

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient() as client:
        # Attach to a running .NET application by name
        session = await client.attach("Microsoft Excel")

        # Read structured state with typed helpers
        workbook_name = session.get_str("workbook.active.name")
        sheet_count = session.get_int("workbook.active.sheet_count")
        active_cell = session.get_str("workbook.active.selection.address")

        print(f"Workbook: {workbook_name}")
        print(f"Sheets: {sheet_count}")
        print(f"Selected cell: {active_cell}")

asyncio.run(main())

You can attach to any CLR application by passing its app_name exactly as it appears in the GET /substrate/v1/apps response.

Verifying Probe Attachment

Call the apps endpoint after starting your .NET application to confirm the daemon has detected and attached to it:

curl http://localhost:7842/substrate/v1/apps

{
  "total": 1,
  "apps": [
    {
      "pid": 5120,
      "app_id": "excel-5120",
      "app_name": "Microsoft Excel",
      "runtime": "clr",
      "probe_status": "active",
      "confidence": 0.95,
      "object_count": 38,
      "action_count": 12
    }
  ]
}

If probe_status is "attaching", the cold probe is still running. Wait a few seconds and try again — CLR cold probes on large applications like Visual Studio can take up to 90 seconds on the first attach.

Get Started

The Daemon

Runtime Probes

Security

Guides

Supported Applications

How the CLR Probe Works

.NET Version Compatibility

Prerequisites

What the Probe Reads

Performance Characteristics

Reading CLR App State

Verifying Probe Attachment

​Supported Applications

​How the CLR Probe Works

​.NET Version Compatibility

​Prerequisites

​What the Probe Reads

​Performance Characteristics

​Reading CLR App State

​Verifying Probe Attachment

Supported Applications

How the CLR Probe Works

.NET Version Compatibility

Prerequisites

What the Probe Reads

Performance Characteristics

Reading CLR App State

Verifying Probe Attachment