Legacy .NET migration: 5 lessons learned the hard way

I was a junior developer at DoveVivo when I was handed the last mile of a big migration: a huge legacy ASP.NET monolith being modernized onto .NET Framework 4.8 (yes, it's ancient; still, it was one of the last version the classic Microsoft Framework and a LTS release, although .NET 5 was just released and still needed security patches: the choice was obvious) with the security and stability fixes and improvements the old code was missing. The architecture was decided before I arrived, by a senior colleague who had the whole picture clear. I didn't. Not yet at least.

The funny part? I didn't even know why the migration mattered until late in the project. Nobody told me the real driver, so I'll tell you: it was never about modernizing for fun. It was uptime.

The monolith stopped the server for minutes at every release. Clients lost access, every single time. And daily users kept growing. That is the pressure that made this migration urgent — and I learned it during the later stages, when I was already in the middle of the work.

The drowning part

Taking over at 90% done meant I was the one talking directly to stakeholders. Suddenly every day brought a new "small" request: button colors, page layout tweaks, a bug in a feature that, I found out later, was almost unused.

I chased them all; each one improving the website but delaying the release. I had no clear priorities no definition of done, and I could feel the finish line moving away. Does it sound familiar?

Finally, I did the smartest thing available to a confused junior: I asked the senior how to handle it. That conversation is where these five lessons come from. Each one is a question I now ask myself before starting any implementation.

1. Ask why before you're in the middle of it

The real goal here was uptime, and I learned it late. If I had asked on day one "why does this migration matter?", every decision in the last mile would have made sense sooner. Never assume the stated task is the real problem, since it usually is not. The business goal shapes the technical answer; find it first to improve the business's overall efficiency.

2. Agree on what "Done" means

Button colors and layout tweaks kept arriving because we had no shared definition of done. Once "done" was explicit this scope, this release, this date the small requests got planned for later effectively stop delaying the finish line. If you cannot describe the completed state in one sentence, you are not ready to start.

3. Ask what is actually urgent

To a stakeholder, every request feels urgent. To the business, uptime beats button colors every time.

If everything is urgent, nothing is.

Learn to sort requests by business impact, not by who asked loudest. It takes one honest conversation to align priorities; while it takes weeks to undo the damage of chasing the wrong one.

4. Ask yourself: does this actually matter?

I once chased a bug in a feature almost nobody used. The honest question: "who does this serve?" would have saved me days. Before committing to a task, force yourself to consider two or three alternatives and evaluate which one fits the real problem. Not the one that was asked. The one that matters.

5. Ask for a second pair of eyes early

I asked the senior when I was already drowning. The lesson is not to ask when it gets bad but it's to ask before it gets bad. Write a short document: the problem, your understanding of it, your proposed solution. Then ask: "does this make sense?" few minutes of someone else's time can save days of yours and your company's. Their experience is a resource, not a last resort.

The honest results

The project shipped. Operational costs went up, as expected, and what changed: releases that used to block access for minutes went out without freezing the platform. Response time felt faster although we didn't measure it back then, and honestly, that is on us. Observe and measure your systems so you can improve them. Users kept growing, around 200 more in a month, roughly doubling but it's unlikely the migration caused that growth; however, I can proudly say the platform could absorb it without the old release interruptions.

Would I do it differently? Yes: ask why on day one, define done out loud, and treat the senior's brain as a resource and not a last resort.