How do you plan and execute a large refactoring in a production .NET system without stopping feature delivery?

1. Sources

2. Finding hotspots

# Most frequently changed files in the last year
git log --since="12 months ago" --format=format: --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20

Combine with size/complexity (lines, cyclomatic complexity) and defect history. High churn + high complexity + many bugs = refactor first. Tools like CodeScene automate this.

3. Characterisation tests

• Record what the code does now, right or wrong.
• Approval/snapshot libraries (Verify is common in .NET; Snapshooter and others exist) write the first output to a file and fail when it changes.
• Feed them real inputs (sampled, anonymised production requests) for broad coverage quickly.
• Bugs found are logged and fixed separately, so the refactoring itself stays behaviour-preserving.

4. Parallel change for a database column

Every deploy is backward compatible, so rollback is always possible. The same pattern works for API fields and message schemas.

5. Strangler fig with YARP

{
  "ReverseProxy": {
    "Routes": {
      "orders": { "ClusterId": "new",    "Match": { "Path": "/orders/{**rest}" } },
      "legacy": { "ClusterId": "legacy", "Match": { "Path": "{**catch-all}" }, "Order": 1000 }
    },
    "Clusters": {
      "new":    { "Destinations": { "d1": { "Address": "https://orders-new.internal/" } } },
      "legacy": { "Destinations": { "d1": { "Address": "https://legacy.internal/" } } }
    }
  }
}

Routes move to the new cluster one at a time; the catch-all keeps everything else on the legacy app until it can be retired. Microsoft's migration guidance for ASP.NET Framework → ASP.NET Core uses this approach (with System.Web adapters for shared session/auth).

6. Shadow comparison

• Run the new implementation alongside the old, return the old result, log differences.
• Sample traffic if the new path is expensive; never let the shadow path's failures affect users (catch and log).
• Don't shadow side-effecting operations (payments, emails) without making the candidate side-effect free.

7. Keeping momentum and knowing when to stop

• Track progress visibly (endpoints migrated, % traffic on new path, lines of legacy remaining).
• Each new feature in the area goes through the new structure.
• Stop when the hotspot pain is gone; perfection isn't the goal.
• Delete old paths and flags promptly: lingering flags are debt.

8. Try it yourself

1. Run the hotspot command above on your repo and pick the top candidate.
2. Write three characterisation tests for it from real inputs.
3. Introduce an interface in front of it and register a shadow decorator (as in the code example) behind a flag.
4. Plan a parallel change for one column rename as four separate deploys.
5. Set up YARP locally to route one path to a new app and everything else to an old one.

// Branch by abstraction with a shadow comparison.
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;

IPriceCalculator calculator = new ShadowPriceCalculator(
    primary: new LegacyPriceCalculator(),
    candidate: new RulesPriceCalculator(),
    logger: NullLogger<ShadowPriceCalculator>.Instance);

Console.WriteLine(calculator.Price(new PriceRequest("SKU-1", 3, "GOLD")));

public sealed record PriceRequest(string Sku, int Quantity, string Tier);

public interface IPriceCalculator { decimal Price(PriceRequest request); }

public sealed class LegacyPriceCalculator : IPriceCalculator
{
    public decimal Price(PriceRequest r) => r.Quantity * 10m * (r.Tier == "GOLD" ? 0.9m : 1m);
}

public sealed class RulesPriceCalculator : IPriceCalculator
{
    private static readonly Dictionary<string, decimal> TierDiscount = new() { ["GOLD"] = 0.10m };
    public decimal Price(PriceRequest r) =>
        r.Quantity * 10m * (1 - TierDiscount.GetValueOrDefault(r.Tier));
}

// Returns the legacy result (behaviour unchanged) and logs any difference.
public sealed class ShadowPriceCalculator(
    IPriceCalculator primary, IPriceCalculator candidate, ILogger<ShadowPriceCalculator> logger) : IPriceCalculator
{
    public decimal Price(PriceRequest request)
    {
        var expected = primary.Price(request);
        try
        {
            var actual = candidate.Price(request);
            if (actual != expected)
                logger.LogWarning("Price mismatch for {Sku}: legacy {Legacy}, new {New}", request.Sku, expected, actual);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "New calculator failed for {Sku}", request.Sku);
        }
        return expected;
    }
}

Requires Microsoft.Extensions.Logging.Abstractions. In production, register the shadow decorator behind a feature flag and sample traffic if the candidate is expensive.