Introduction
A few months back, a client came to us with what they called a "simple migration project." Their .NET app was running fine on-premises, and they wanted to move it to Azure to take advantage of cloud platform. Three months later, we are still working on authentication, rewriting configuration management, and rebuilding their entire deployment pipeline.
I've worked on such projects for in-house as well as client-facing projects. The main reason this happens is that most .NET developers have never worked on Azure .NET migration projects, and if they have worked, then the scope of the last project they participated in had a completely different requirement.
So wherever you are in your .NET Azure migration journey, these are the five things I have seen teams miss the most, and should be taken care of.
.NET Azure Migration: Top 5 Things to Take Care of
These five areas cover framework compatibility, authentication, configuration management, database migration, and deployment pipelines, in a .NET Azure migration project.
1. Framework Compatibility: Know What You're Actually Moving Before You Move It
If your application runs on an older .NET Framework, you can't just deploy it to Azure App Service and expect it to work. APIs like System.Web, HttpModules, and HttpHandlers don't exist in modern .NET versions. They were never ported over. So if your app uses them, any feature that depends on those APIs will break, and that's not something you can configure your way out of.
So, before you start a .NET Azure migration, run Microsoft's App Compatibility Toolkit across the codebase. It will tell you what breaks and what needs to be rewritten. While you're at it, check your third-party NuGet packages too. A library that hasn't been updated in years may not support .NET 8, 9, or .NET 10 at all, and you want to know that in week one rather than the week before go-live.
The key decision here is whether to upgrade to modern .NET first and then migrate, or move as-is and deal with the compatibility issues later. I've seen teams choose the second option thinking they'll fix it in Azure. Most of them are still fixing it.
2. Windows Authentication Stops Working in the Cloud
Authentication is one of those things that never gets planned properly before a .NET Azure migration. And it always comes up early.
Windows Authentication works fine on-premises because your app and the domain are on the same network. Move the app to Azure App Service and that connection is gone. Suddenly nothing authenticates the way it used to.
The fix here is Microsoft Entra ID (formerly Azure Active Directory). Use it for user-facing authentication and managed identities for service-to-service calls. Once it's in place, it's actually a better setup than most on-premises auth configurations. Getting there, though, is tough.
The reason it takes longer than expected is that authentication is rarely contained to one place in a .NET application. Over the years, it gets added to scheduled jobs, background services, internal API calls. Nobody documents it. So teams keep discovering new dependencies in places they did not expect, and that is what stretches a two week job into five.
So, before migration starts, map every place in the application that touches authentication or identity. Calls that use domain credentials, services that run as a specific Windows account, and integrations that rely on pass-through authentication. Find them all upfront.
3. Configuration Management Needs a Rethink, Not a Patch
web.config works fine on-premises and nobody questions it. I never questioned it either, until we moved a client application to Azure and realized half their secrets were sitting in config files committed to source control.
In most .NET apps, connection strings, API keys, environment-specific settings live in config files. Managing it on premise is easy. In Azure it is a security problem on top of a migration problem, and both hit you at the same time.
Azure Key Vault is where secrets should live. Azure App Configuration handles environment-specific values. In modern .NET, plugging both in does not take long. In older .NET Framework applications it takes more effort, and teams usually have not accounted for that time in the plan.
The other thing that always gets missed is web.config transforms. Things like web.Release.config and web.Staging.config were built around IIS deployments. They do not carry over to Azure the same way. If your environment promotion process depends on them, you need a new approach before go-live. I have seen this discovered during a staging deployment, two days before a client go-live. It is not a difficult fix but finding it that late makes it one.
4. Database Migration Is Its Own Project
I have watched .NET Azure migration projects reach 80% and sit there for months. The database is almost always the reason.
The way it usually happens is that the database gets added as one item in the migration plan, somewhere near the end. The assumption is that it will follow the application once everything else is ready. What teams find out is that SQL Server to Azure SQL is not a backup and restore job.
Deprecated T-SQL syntax, linked servers, SQL Agent jobs, CLR assemblies, each of these is a separate problem with its own solution. When nobody has looked at them before the migration starts, they all show up at the same time, and everything stalls.
Azure SQL Managed Instance is the safer choice if you want fewer compatibility surprises. Azure SQL Database is cheaper but has limitations that will affect some applications. That choice needs to be made before the project starts, not when you are already mid-migration and running behind.
If your application uses Entity Framework, test against Azure SQL early, in an actual cloud environment, not just locally. One more thing worth doing is adding connection stability to your data access layer. Cloud databases handle sudden connection drops differently than on-premises SQL Server, and an application that has never had to deal with that will throw errors that are hard to trace back to the real cause. We spent two days on one such issue on a project last year before we found it.
Give the database its own timeline and its own owner from the start. Every team that doesn’t take full ownership of database migration leads to project delays.
5. Old Deployment Pipelines Do Not Belong in a Cloud Environment
Almost every .NET application being migrated has a deployment pipeline that was built for IIS. Legacy MSBuild scripts, old TFS release definitions, sometimes just a manual process that someone turned into a script years ago and nobody has touched since.
These were never designed for Azure. Patching them into working is possible, but in my experience it always takes longer than rebuilding properly, and you end up with something fragile that the next person on the team is afraid to touch.
Azure DevOps Pipelines and GitHub Actions are both solid choices. Set them up properly from the start, with environment approvals, test gates, and deployment slots. That way you can validate a release before it goes to production. Teams that skip this and plan to add it later, never really get around to it.
If containerization is part of the plan, and I would recommend it for anything being significantly refactored, the Docker pipeline needs to be in scope from day one. I have seen it treated as a follow-up item on more than one project, and it always comes back as unplanned work at the worst time.
Teams that finish .NET Azure migration projects on time treat the CI/CD rebuild as core migration work. The ones that do not end up deploying manually for longer than anyone planned.
Conclusion
None of these five things are hard to solve. What makes them expensive is finding them late.
Every Azure .NET migration project I have seen go well had one thing in common. The team assessed framework compatibility, authentication, configuration, database, and deployment pipeline before writing a single line of migration code. Not as a formality, but because that work is what made the rest of the project predictable.
The ones that dragged on were the ones built on assumptions. And in a .NET Azure migration, assumptions always catch up with you.
If you are working with a .NET Development company on this, ask them how many production migrations they have actually delivered. Not internal projects, not proofs of concept. Real proof of work with actual users. That one question will tell you more about them than anything else.
Top comments (0)