Build a .NET Application Agent Using the CLR Probe

NSP’s CLR probe attaches to any running .NET process — WinForms apps, WPF apps, .NET 4.x / .NET 6+ binaries — using the Windows CLR Hosting API. No code changes to the target application are required. This guide uses Mission Planner (a C# ground control station) as the worked example, but the same patterns apply to any .NET app.

How the CLR Probe Works

When the NSP daemon detects a .NET process, it injects a managed C# bridge assembly into the target AppDomain via the CLR Hosting API. The bridge runs inside the target process and communicates back to the daemon through a Memory-Mapped File (MMF). This design means:

No process restart required — injection happens while the app is running.
Zero-copy communication — the MMF is shared memory; no serialization overhead.
Non-intrusive field reads — field values are read through managed reflection without pausing the JIT.

Prerequisites

.NET App Running

The target .NET application must already be running. The daemon detects it automatically within one scan cycle (default: 5 seconds).

NSP Daemon Running

Run axon-daemon.exe run or start the Windows Service. Ensure the daemon has permission to inject into the target process (run both as the same user, or as Administrator).

SDK Installed

pip install nelieo-nsp

No App Changes

You do not need to modify, rebuild, or restart the target .NET application.

Step 1 — Verify Detection

List tracked apps and check for your .NET process. The runtime field will be clr for any managed .NET target:

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient(api_key="sk_nsp_...") as client:
        apps = await client.list_apps()
        for app in apps:
            print(f"{app.app_name} | runtime={app.runtime} | conf={app.confidence:.2f}")

asyncio.run(main())
# Mission Planner | runtime=clr | conf=0.95

CLR confidence baselines typically start at 0.70–0.80 during the first probe while the bridge enumerates assembly types. Confidence reaches 0.95+ once the semantic engine has mapped the major state fields. This usually takes 15–45 seconds after the process is first detected.

Step 2 — Attach and Read Normalized State

The CLR probe normalizes extracted fields into the standard NSP state tree (SSF format). Use the same typed accessors you would with any other app:

async with nsp.NSPClient(api_key="sk_nsp_...") as client:
    session = await client.attach("Mission Planner")

    # Normalized state — available via standard accessors
    alt     = session.get_float("flight.altitude_m")
    lat     = session.get_float("flight.gps.latitude")
    lon     = session.get_float("flight.gps.longitude")
    mode    = session.get_str("flight.mode")
    armed   = session.get_bool("flight.is_armed")
    battery = session.get_float("flight.battery_voltage")

    print(f"Position: {lat:.6f}, {lon:.6f}  Alt: {alt:.1f}m")
    print(f"Mode: {mode}  Armed: {armed}  Battery: {battery:.1f}V")

Step 3 — Read .NET Fields Directly via `session.clr`

When normalized state doesn’t cover what you need, use session.clr — a CLRSessionProxy that gives you direct access to the CLR heap:

Read a single field
Read multiple fields at once
Heap snapshot

# Read a static or instance field from a specific .NET type
armed      = await session.clr.read_field("MAVLink.MAVLinkInterface", "IsArmed")
gps_status = await session.clr.read_field("MAVLink.MAVLinkInterface", "GPSStatus")
heading    = await session.clr.read_field("MissionPlanner.FlightData", "heading")

print(f"Armed: {armed}  GPS: {gps_status}  Heading: {heading}°")

# Batch read — one MMF round-trip for all fields
telemetry = await session.clr.read_fields(
    "MissionPlanner.FlightData",
    "alt", "groundspeed", "airspeed", "heading",
    "battery_voltage", "battery_remaining",
)
print(f"Alt={telemetry['alt']:.1f}m  GS={telemetry['groundspeed']:.1f}m/s")
print(f"Batt={telemetry['battery_remaining']:.0f}%")

# Walk the full CLR heap for a type namespace
objects = await session.clr.heap_snapshot(
    include_prefix="MAVLink",  # Only types whose name starts with "MAVLink"
    max_instances=32,
    timeout_ms=30_000,
)
for obj in objects:
    print(obj["type_name"], obj["fields"])
    # MAVLink.MAVLinkInterface  {'IsArmed': True, 'alt': 42.7, ...}

Step 4 — Invoke .NET Methods via `session.clr`

Call any public .NET method with typed arguments. Python values are automatically coerced to the matching .NET parameter types:

# Parameterless method call
status = await session.clr.invoke("MissionPlanner.MainV2", "GetStatusText")
print(f"GCS Status: {status}")

# String argument — coerced to System.String
await session.clr.invoke("MissionPlanner.GCS", "setMode", ["GUIDED"])

# Boolean argument — coerced to System.Boolean
await session.clr.invoke("MissionPlanner.MainV2", "doArm", [True])

# Double arguments — coerced to System.Double
await session.clr.invoke(
    "MissionPlanner.NavController",
    "SetWaypoint",
    [34.0522, -118.2437, 50.0],  # lat, lon, alt_m
)

Python bool, int, float, str, and list all coerce automatically to their .NET equivalents. Strings in ISO 8601 format coerce to DateTime; GUID-formatted strings coerce to Guid. Enums can be passed by name as a string.

Step 5 — Execute NSP Actions

The CLR probe also exposes higher-level NSP actions discovered from the app’s schema. Use session.execute() for these:

# List what actions are available
for name, schema in session.actions.items():
    print(f"{name}: reversibility={schema.reversibility}")

# Arm motors — reversible, no verify required
result = await session.execute("arm_motors", parameters={})
print(f"Arm command sent: {result.success}")

# Take off — irreversible; verify altitude reaches target
result = await session.execute(
    "take_off",
    parameters={"altitude_m": 50.0},
    verify=True,
    verify_expression="flight.altitude_m > 45.0",
    verify_timeout_ms=30000,  # 30s for takeoff to settle
)
print(f"Airborne: {result.success}")

Step 6 — Stream Telemetry in Real Time

async def monitor_flight():
    async with nsp.NSPClient(api_key="sk_nsp_...") as client:
        session = await client.attach("Mission Planner")
        print(f"Connected. Confidence: {session.confidence:.2f}")

        async with session.watch(auto_refresh_on_event=True) as stream:
            async for event in stream:
                if not any(k.startswith("flight.") for k in event.changed_keys):
                    continue

                alt   = session.get_float("flight.altitude_m")
                mode  = session.get_str("flight.mode")
                armed = session.get_bool("flight.is_armed")
                gs    = session.get_float("flight.groundspeed")
                batt  = session.get_float("flight.battery_remaining")

                print(f"  Alt={alt:.1f}m  GS={gs:.1f}m/s  Mode={mode}  Armed={armed}")

                # Safety: return to launch if battery is low
                if batt < 20.0 and armed:
                    print("⚠️  Battery low — commanding RTL")
                    await session.execute(
                        "set_mode",
                        parameters={"mode": "RTL"},
                        verify=True,
                        verify_expression="flight.mode == 'RTL'",
                    )

asyncio.run(monitor_flight())

Complete Example — Autonomous Waypoint Mission

import asyncio
import nelieo_nsp as nsp

WAYPOINTS = [
    (34.0522, -118.2437, 50.0),  # Start
    (34.0600, -118.2400, 60.0),  # WP1
    (34.0650, -118.2350, 60.0),  # WP2
    (34.0522, -118.2437, 50.0),  # Return home
]


async def run_mission():
    async with nsp.NSPClient(api_key="sk_nsp_...") as client:
        session = await client.attach("Mission Planner")
        print(f"Connected. Confidence: {session.confidence:.2f}")

        # 1. Arm the vehicle
        await session.clr.invoke("MissionPlanner.MainV2", "doArm", [True])
        await session.wait_for(
            lambda s: s.get_bool("flight.is_armed"),
            timeout=15.0,
        )
        print("Armed ✓")

        # 2. Switch to GUIDED mode
        await session.clr.invoke("MissionPlanner.GCS", "setMode", ["GUIDED"])

        # 3. Take off to 50 m
        await session.execute(
            "take_off",
            parameters={"altitude_m": 50.0},
            verify=True,
            verify_expression="flight.altitude_m > 45.0",
            verify_timeout_ms=30000,
        )
        print("Airborne ✓")

        # 4. Fly each waypoint in sequence
        for i, (lat, lon, alt) in enumerate(WAYPOINTS):
            print(f"→ Waypoint {i + 1}: ({lat:.4f}, {lon:.4f}, {alt}m)")
            await session.clr.invoke(
                "MissionPlanner.NavController",
                "SetWaypoint",
                [lat, lon, alt],
            )
            # Wait until altitude is within 5 m of target
            await session.wait_for(
                lambda s, a=alt: abs(s.get_float("flight.altitude_m") - a) < 5.0,
                timeout=60.0,
                fresh_probe=True,
            )

        # 5. Land
        print("Mission complete — landing")
        await session.clr.invoke("MissionPlanner.GCS", "setMode", ["LAND"])


asyncio.run(run_mission())

CLR Proxy Method Reference

session.clr.read_field(type_name, field_name)

Reads a single field from the first matching instance of type_name on the CLR heap.

value = await session.clr.read_field("MAVLink.MAVLinkInterface", "IsArmed")
# Returns: bool | int | float | str | None

session.clr.read_fields(type_name, *field_names)

Reads multiple fields in a single MMF round-trip. Returns a dict[str, Any].

vals = await session.clr.read_fields(
    "MissionPlanner.FlightData",
    "alt", "groundspeed", "battery_voltage",
)

session.clr.invoke(type_name, method_name, args=[])

Invokes a method on the first matching instance. Returns the method’s return value, coerced back to a Python type.

result = await session.clr.invoke("MissionPlanner.GCS", "setMode", ["AUTO"])

session.clr.heap_snapshot(include_prefix, max_instances, timeout_ms)

Walks the CLR heap and returns a list of objects whose type names start with include_prefix. Each object contains type_name and fields keys. This is an expensive operation — use sparingly.

objects = await session.clr.heap_snapshot(include_prefix="MAVLink", max_instances=32)

Get Started

The Daemon

Runtime Probes

Security

Guides

How the CLR Probe Works

Prerequisites

.NET App Running

NSP Daemon Running

SDK Installed

No App Changes

Step 1 — Verify Detection

Step 2 — Attach and Read Normalized State

Step 3 — Read .NET Fields Directly via `session.clr`

Step 4 — Invoke .NET Methods via `session.clr`

Step 5 — Execute NSP Actions

Step 6 — Stream Telemetry in Real Time

Complete Example — Autonomous Waypoint Mission

CLR Proxy Method Reference

​How the CLR Probe Works

​Prerequisites

.NET App Running

NSP Daemon Running

SDK Installed

No App Changes

​Step 1 — Verify Detection

​Step 2 — Attach and Read Normalized State

​Step 3 — Read .NET Fields Directly via session.clr

​Step 4 — Invoke .NET Methods via session.clr

​Step 5 — Execute NSP Actions

​Step 6 — Stream Telemetry in Real Time

​Complete Example — Autonomous Waypoint Mission

​CLR Proxy Method Reference

How the CLR Probe Works

Prerequisites

Step 1 — Verify Detection

Step 2 — Attach and Read Normalized State

Step 3 — Read .NET Fields Directly via `session.clr`

Step 4 — Invoke .NET Methods via `session.clr`

Step 5 — Execute NSP Actions

Step 6 — Stream Telemetry in Real Time

Complete Example — Autonomous Waypoint Mission

CLR Proxy Method Reference