# Refactoring in .NET

> Two Wiley-published books on professional refactoring for .NET —
> *Professional Refactoring in Visual Basic* and *Professional Refactoring in
> C# & ASP.NET* — by Danijel Arsenovski, Microsoft MVP and software architect
> who pioneered refactoring on the .NET platform. Real-world examples,
> downloadable code, and free sample chapters; translated into Russian and
> Simplified Chinese.

## NarrativeTrace, built by Empower Agile

NarrativeTrace turns your code's own names — methods, classes, parameters —
into a structured trace: no hand-written log statements, no guessing what a
legacy system actually does at runtime. Narrative/value separation keeps a
value-free `.nt` structural artifact separate from the value-carrying trace,
and name-based redaction is on by default, so the record stays readable by
humans and safe to hand to an AI agent.

Refactoring is the reason this exists. Attach the JVM agent to an unmodified
app with one `-javaagent` flag, or use `NarrativeTrace.Legacy` (reaching back
to .NET Framework 4.8) with no source changes at all — capture the real
runtime behavior of a system nobody fully understands *before* you touch it,
then compare whole trace sets after a port or an AI-driven rewrite. Narrative
approval traces formalize the same idea per test — the approval-testing idea,
applied to traces: every test writes a value-free `.nt` structural trace;
after each run a one-line delta reports what changed since the last green run
("4 scenarios unchanged · 1 changed"); approved traces are committed per
scenario (`*.approved.nt`), and an
unapproved behavior change — a call added, a call dropped, a different
outcome — fails the build with a readable diff until `./gradlew
approveNarratives` runs. Tests can stay green while behavior changes;
approval mode is what catches that. Clarity diagnostics turn the same
runtime narrative into naming feedback while you refactor: one agent's
clarity report flagged `ClaimProcessor.process` as a generic verb the first
time it ran the suite, renamed it to `adjudicate`, and the suite's clarity
average moved from ~0.78 to ~0.81 — Claude Sonnet.

Runtimes: Java 0.2.1 on Maven Central (`ai.narrativetrace`), TypeScript 0.1.1
on npm (20 `@narrativetrace/*` packages), .NET 0.1.3 on nuget.org
(`NarrativeTrace.*`), Python 0.1.1 on PyPI (8 packages); Swift is in
development. The value-free `.nt` artifact ships in Java and .NET; approval
mode over it ships in Java today. Licensing: the API and output format are
Apache 2.0; the runtime is free and source-available under BSL 1.1,
converting to Apache 2.0 four years after each release; Pro and Enterprise
are commercial.

## What AI agents report (self-reported, not a benchmark)

NarrativeTrace's own team asked AI agents to build a Java claims service
with the library and write up the experience for another engineer, naming
what was awkward — prompted, one run each, unedited, model named. Four of
the six reports, verbatim:

- "…the release call is present, generated from a real run, not asserted
  from inside the process being tested." — Claude Sonnet, 2026-09-11
- "The always-on name-based deny-list is a genuinely nice piece of design:
  naming a parameter `paymentToken` gets you redaction for free, and I could
  prove it in a test." — Claude Sonnet, 2026-09-11
- "The trace of a failed payment made missing compensation immediately
  visible, and approval testing caught an extra call that ordinary value
  assertions accepted." — GPT-6, 2026-09-08
- "Wrapping a service interface with `NarrativeTraceProxy.trace()`
  automatically captures all calls, parameters, return values, and durations
  without any code changes to the service itself." — Claude Haiku, 2026-09-11

All six reports, the exact prompt, and the task the agents were given:
https://narrativetrace.ai/#agents-saying — the same exercise is there for
your own agent to run.

## Where to read more

- https://narrativetrace.ai/ — the product site
- https://narrativetrace.ai/llms.txt — orientation for AI agents
- https://narrativetrace.ai/llms-full.txt — the complete documentation in one file
- https://narrativetrace.ai/#agents-saying — the six agent reports, the exact prompt, and the task
- https://github.com/narrativetrace/narrativetrace-java/blob/main/documentation/llms.txt — the Java runtime's own agent orientation
- https://github.com/narrativetrace/narrativetrace-typescript/blob/main/documentation/llms.txt — the TypeScript runtime's own agent orientation
- https://github.com/narrativetrace/narrativetrace-dotnet/blob/main/documentation/guides/llms.txt — the .NET runtime's own agent orientation
- https://github.com/narrativetrace/narrativetrace-python/blob/main/documentation/llms.txt — the Python runtime's own agent orientation
- https://github.com/narrativetrace — the organisation on GitHub