Single-Stage Upgrade Vs Multi-Stage Upgrade In Dynamics 365
Single-Stage Upgrade vs Multi-Stage Upgrade in Dynamics 365: Common Issues and How to Fix Them
When managing enterprise-level solution deployments in Microsoft Dynamics 365, it’s common to encounter situations where components appear differently between pre-production and production environments. These mismatches often cause confusion — especially when components removed in pre-prod still appear in production after importing the latest solution.
In this blog, we will break down how Single-Stage Upgrade and Multi-Stage Upgrade behave, why these issues happen, and how to fix them. Screenshot placeholders are included so you can insert your own evidence later.
Introduction
Dynamics 365 solution layering is powerful but sometimes tricky. When you deploy managed solutions from pre-production to production, certain components — like views, tables, or sitemap items — may not update or delete as expected.
This usually happens due to:
-
Dependency behaviors
-
Solution layering
-
Differences between Update, Single-Stage Upgrade, and Multi-Stage Upgrade
Understanding these differences is critical for clean and predictable deployments.
Scenario 1: Views Still Exist in Production Even After Removing Them in Pre-Production
Example:
A table contains 6 views.
You remove one view in pre-production and deploy the solution to production as an Update.
But the old view still shows up in production.
Why this happens
-
The view is also referenced in another managed solution in production.
-
An Update import never deletes components.
-
Because another solution holds a reference, Dynamics 365 does not remove the view layer.
-
Even with a Single-Stage Upgrade, the view may remain due to dependency layers.
How Multi-Stage Upgrade solves this
A Two-Stage Upgrade (Holding + Final):
-
Holding Stage
-
Removes components only from the target solution layer.
-
Does not touch components referenced by other solutions.
-
-
Final Upgrade Stage
-
Cleans up the component layers properly.
-
Ensures production matches the pre-production state.
-
This approach guarantees your solution layer is updated cleanly, even when shared dependencies exist.
Scenario 2: Table Deletion Fails Due to Sitemap & Model-Driven App Dependencies
Example:
You try to delete a table. In pre-prod, you already:
-
Removed the table from the sitemap
-
Removed it from the model-driven app
-
Exported and imported the solution
But in production, the table still remains unchanged.
Why Update import does nothing
-
Update does not delete components.
-
It only adds or modifies existing components.
-
Actual deletion requires an Upgrade.
Why Single-Stage Upgrade often fails
During a Single-Stage Upgrade, the system:
-
Attempts to delete the table.
-
Finds that in production there are still dependencies (sitemap, app modules, etc.)
-
Dependency validation fails — so the deletion is aborted.
Even though you cleaned dependencies in pre-prod, production still holds references due to solution layering.
Two ways to fix this
✔ Option 1: Multiple Updates + One Upgrade
-
Import solution as Update (to remove sitemap/app references)
-
Repeat until all dependency layers are removed
-
Then perform a Single-Stage Upgrade
But this is risky and time-consuming.
✔ Option 2: Multi-Stage Upgrade (Recommended)
-
Import as Holding (Stage 1)
The platform removes your solution layer’s references in the correct order. -
Confirm dependencies are removed
-
Import Final Upgrade (Stage 2)
The table is now safely deleted with zero dependency errors.
This is the most reliable and Microsoft-recommended method.
Root Causes of Version Mismatches Between Pre-Prod and Production
These issues typically happen because:
-
Components are referenced by multiple managed solutions.
-
Production contains old layers from past deployments.
-
Update imports never delete components.
-
Single-Stage Upgrade struggles with dependency-heavy components.
-
Admins often skip Multi-Stage Upgrade because it’s not widely understood.
Recommended Deployment Strategy
To avoid unexpected behavior:
✔ Use Multi-Stage Upgrade whenever removing components
Especially for tables, columns, views, app modules, forms, or anything with dependencies.
✔ Use Update only when making safe, additive changes
e.g., adding fields, updating business rules, modifying command bars, etc.
✔ Before removing tables or views
-
Remove from all app modules
-
Remove from the sitemap
-
Remove from any dependency components
-
Validate using the Solution Layers option in each environment
Screenshot Placeholders (Insert Your Own Evidence)
Conclusion
Solution management in Dynamics 365 can become challenging when dealing with deletions, dependencies, and multiple solution layers. A Multi-Stage Upgrade is the safest and most reliable way to ensure Production aligns with Pre-Production.
By following the right import type — Update, Single-Stage Upgrade, or Multi-Stage Upgrade — you can avoid mismatches, dependency failures, and lingering components in production.
single-stage-upgrade-vs-multi-stage-upgrade-in-dyn