Add managed C# AppMap agent (under managed/)

[evlawler]

What this is

This PR brings the fully managed C# AppMap agent into appmap-dotnet under a new managed/ subdirectory. It's a from-scratch port of the appmap-java architecture — a managed agent that rewrites methods at runtime via Harmony, rather than instrumenting IL from a C++ CLR-profiler plugin.

The motivation (vs. the existing C++ prototype): being fully managed makes it cross-platform (not Linux-only) and considerably easier to evolve, while emitting the same AppMap JSON (format v1.2) as appmap-java.

Layout

Everything lands under managed/ — the existing C++ prototype and its CI are untouched, so the two implementations sit side by side for comparison. (The agent's own CI workflows are at managed/.github/workflows/ and therefore do not auto-run in this repo.)

Project	Role
managed/src/AppMap.Agent	Config, recorder, event model, serializer, Harmony instrumentation, SQL + built-in hooks
managed/src/AppMap.Attributes	[Labels] attribute for application code
managed/src/AppMap.StartupHook	DOTNET_STARTUP_HOOKS entry point
managed/src/AppMap.AspNetCore	HTTP server events, request + remote recording
managed/src/AppMap.SystemWeb	The same for classic ASP.NET (.NET Framework)
managed/src/AppMap.Testing.{Xunit,NUnit}	One AppMap per test
managed/test/AppMap.Agent.Tests	Serializer / config / value-capture unit tests
managed/examples/{HelloAppMap,PetClinic}	Smallest recorded app; ASP.NET Core + EF Core web app (HTTP + SQL)
managed/harness/	Records an unmodified real app (eShopOnWeb) and CLI-validates the maps

See managed/README.md for build/usage and managed/DESIGN.md for the design.

Status

Draft, opened for @dividedmind to review the approach. Imported as-is from the prototyping repo; happy to reshape placement, naming, or split it up based on feedback.

[evlawler]

@dividedmind — when you have a moment, could you take an early look at the approach here? Keeping it as a draft on purpose: this is a gut-check on direction, not a final PR.

The short version: a fully managed C# AppMap agent (Harmony-based runtime rewriting, porting the appmap-java architecture) landed under managed/, alongside the existing C++ prototype — nothing in the C++ path or its CI is touched. Motivation is cross-platform support and easier evolution vs. the CLR-profiler plugin, emitting the same AppMap JSON as appmap-java.

Mainly looking for feedback on placement/naming and whether this direction is worth pursuing. Happy to reshape or split it up. See the PR description, managed/README.md, and managed/DESIGN.md for details. Thanks!

---

Generated by Claude Code

[dividedmind]

I really like the general idea of a managed recording agent – if it's indeed feasible. Couple of notes/nitpicks from a quick review:

• The GitHub action workflows contain a lot of test code. Ideally, the test code should live in structured scripts so they could more easily be iterated on and run manually; github action should only have the minimal code to call out to them and to bind them together.
• I'd prefer for this to live in a separate "orphan" branch (or a separate repository altogether) – with complete history if it's not too WIPpy – instead of being shoehorned into a subdirectory like this.
• Using AppMap shouldn't require modifying production code (with the exception of labels – ideally they could be applied with no importing AppMap to the project, or if that's not feasible in a non-hacky idiomatic way, importing just a minimal annotation-only library – like appmap-java's com.appland.appmap.annotation – I see there's AppMap.Attributes here, good). The PetClinic example here explicitly pulls in UseAppMap in the server startup. Instead it should be automatically injected where needed (for example on building/running an AspNetCore server) when running with appmap configured (perhaps through a runner script – which seems to be missing here too? – or whatever is idiomatic). ZeroTouchWeb actually demonstrates this but is missing labels (and the runner script). Explicit UseAppMap should be de-emphasized (but still useful and documented, among others perhaps with the additional comment in the example, for more complicated cases that need more control). Runner script (or, eg. dotnet tool entry point – again, whatever's idiomatic) that sets the environment accordingly should be implemented; it's possible that it would not work correctly in more complicated pipelines so non-script way should also be documented, but it's an important ad-hoc easy entry point that should work for most users.
• Similar concern for System.Web or tests – running with the runner or prepared environment should automatically inject and hook whatever's feasible (subject to configuration) – if not feasible, explicitly call out this gap. In particular especially the tests should be hooked and recorded unmodified. (The Attributes library could expose eg. an annotation to attach to tests to explicitly control/skip AppMap recording, but it should be entirely optional to use it.)

[evlawler]

Thanks @dividedmind — this was really useful, and I've acted on all of it. Summary of where each point landed:

Placement → orphan branch, full history. Moved out of the managed/ subdirectory entirely. The claude/exciting-ritchie-ksbydi branch now holds the managed agent at the repo root with its complete 34-commit history (all authored, not squashed — the progression is reasonably clean, not WIPpy). Heads up: this PR auto-closed the moment the branch became an orphan — an orphan branch shares no merge-base with master, so a PR against master is degenerate and GitHub closed it. That's expected and matches your intent: this is meant to live as a branch, not merge into master. Happy to promote it to a separate repo (e.g. getappmap/appmap-dotnet-managed) whenever you'd prefer — just say the word and it can be pushed there with history intact.

CI is now thin. Workflows only build/test and call out to scripts/ci/* (runner-smoke.sh, windows-pdb-smoke.ps1, system-web-iis-smoke.ps1, check-windows-maps-on-linux.sh), so the test logic runs and iterates locally. See 40aa95b.

Zero-touch is now the front door. Added src/AppMap.Runner — an appmap-dotnet runner (dotnet tool) that sets DOTNET_STARTUP_HOOKS + ASPNETCORE_HOSTINGSTARTUPASSEMBLIES and execs your command, no app changes:

appmap-dotnet -- dotnet run     # one AppMap per request
appmap-dotnet -- dotnet test    # one AppMap per test

The examples are now zero-touch (6258e02): PetClinic no longer calls UseAppMap in startup; labels come only from the annotations-only AppMap.Attributes package (like com.appland.appmap.annotation), and ZeroTouchWeb gained the labels it was missing. Explicit UseAppMap is kept and documented for the advanced/more-control cases, just de-emphasized. The non-script env-var path is documented too, for awkward pipelines.

Tests record unmodified (e6eae4a): the xUnit/NUnit execution pipeline is hooked, so appmap-dotnet -- dotnet test records one AppMap per test with no edits to the test project. The [AppMap] attribute is now purely optional, for control/skip.

System.Web gap called out explicitly (705b732): DOTNET_STARTUP_HOOKS is .NET Core 3.0+, so there's no process-wide managed injection point on .NET Framework — the runner can't auto-attach there. The README documents this as a "Known zero-touch gap", with the no-code-change fallback being config-level (the web.config module registration), exercised end-to-end on a real IIS Express host in CI.

Take a look at the branch when you have a chance — glad to spin up the separate repo, or adjust anything else.

---

Generated by Claude Code