While working on a Dynamics 365 solution migration, I came across a scenario that appeared to contradict one of the platform's most well-known rules.
"Unmanaged customizations always take precedence over managed solutions."
At first glance, the behavior didn't make sense. After investigating further, it became clear that Dataverse's solution layering model is more sophisticated than most documentation suggests.
This article walks through the scenario, explains what actually happens behind the scenes, and clarifies why the unmanaged layer didn't "lose"; it simply ceased to exist.
The Scenario
Imagine the following environments:
DEV -> TEST
Step 1 – Import as an Unmanaged Solution
In the development environment, I created a new custom field.
Solution A (Unmanaged)
Account
+ new_testfieldI exported this solution as Unmanaged and imported it into the TEST environment.
At this point, the layer stack looked exactly as expected.
Unmanaged
------------
new_testfield
------------
SystemSo far, everything was normal.
Step 2 – Package the Same Component as Managed
Later, I created another solution.
Instead of creating a new field, I simply included the same table and field in another solution.
Solution B
Account
+ new_testfieldThis time, I exported it as a Managed Solution and imported it into the TEST environment using Stage for Upgrade.
After the upgrade was completed, I opened the Solution Layers expecting to see:
Unmanaged
------------
Managed
------------
SystemInstead, I found this:
Managed
------------
SystemThe unmanaged layer had completely disappeared.
At first glance, this seems to violate the well-known rule that unmanaged customizations always have the highest priority.
So what actually happened?
The Common Misconception
Many developers imagine solution layers like this:
Unmanaged
Managed
Systemwhere every imported solution permanently exists as another layer.
That isn't how Dataverse works.
An unmanaged import is not another installed solution sitting above managed solutions.
Instead, unmanaged customizations represent the current editable definition of a component.
A better mental model is:
Current Customization rather than Installed Unmanaged Solution
This distinction is the key to understanding the behavior.
What Happens Internally?
Every Dataverse component contains much more than just its metadata.
Internally, Dataverse tracks information such as:
- Component identifiers
- Solution component records
- Publisher information
- Dependency relationships
- Solution ownership
- Layer metadata
When the field was first imported as an unmanaged solution, Dataverse created the component and stored its current definition.
There wasn't a managed package behind it.
The unmanaged customization effectively became the authoritative definition of that component.
Importing the Managed Solution
When the managed solution was imported later, Dataverse compared the incoming component against the existing one.
It recognized:
- The schema name matched.
- The publisher matched.
- The component lineage matched.
- The component already existed.
Instead of creating another competing copy, Dataverse performed component ownership reconciliation.
Rather than ending up with:
Unmanaged
------------
new_testfield
Managed
------------
new_testfield
Dataverse effectively transformed the component into:
Managed
------------
new_testfieldThe unmanaged ownership was no longer required.
Why Doesn't Dataverse Keep Both?
Imagine if Dataverse allowed both the unmanaged and managed ownership models to remain for the same component.
Now consider what would happen if you later uninstalled the managed solution. Should the field disappear? Probably not, because the unmanaged customization still owns it.
On the other hand, imagine removing the unmanaged customization. Should the managed version continue to exist? If both ownership models were retained, the platform would effectively have two independent owners for the same component.
This raises several questions. Which owner should Dataverse use when tracking dependencies? Which one is responsible for uninstalling the solution? How should the platform determine the component's lifecycle when ownership is split?
To avoid this complexity, Dataverse prefers a single ownership model whenever possible. When a managed solution contains what appears to be the same component, Dataverse evaluates several characteristics to determine whether it can safely reconcile the ownership:
- Schema Name – Confirms that the component being imported is the same logical component.
- Publisher – Ensures the component originates from the same solution publisher.
- Component Lineage – Verifies that the component shares the same identity throughout its lifecycle and isn't a different component with similar metadata.
- Metadata – Confirms that the component definition (such as properties and configuration) is identical, with no local overrides or conflicting changes.
If these characteristics match, there is little value in retaining redundant unmanaged ownership. Instead of maintaining duplicate ownership models, Dataverse reconciles the component and treats the managed solution as the authoritative owner.
As a result, the unmanaged ownership becomes redundant and is removed, leaving a single managed representation of the component.
This Is NOT the Same as Overriding a Managed Component
This is where the famous statement:
"Unmanaged customizations always win."
Let's consider a different scenario.
Suppose the managed solution already exists. You then open the target environment and modify the field's display name.
Managed layer:
Display Name = Customer RatingLocal unmanaged customization:
Display Name = Client RatingNow the layers become:
Unmanaged Override
------------------
Display Name = Client Rating
Managed Base
-------------
Display Name = Customer Rating
Here, the unmanaged layer remains because it contains a genuine override of the managed component, which requires Dataverse to preserve both layers, as they represent different values.
Why My Scenario Was Different
In my case, both definitions were identical.
The unmanaged component and the managed component described exactly the same field. There were no local modifications. No overridden properties. No conflicting metadata.
Because there was nothing to override, Dataverse optimized the component ownership and removed the redundant unmanaged layer.
The managed solution became the sole owner.
The Role of "Stage for Upgrade"
This behavior is particularly noticeable during a solution upgrade.
An upgrade import is much more than a standard solution import.
Internally, Dataverse performs operations such as:
- Installing a holding solution
- Comparing incoming components
- Reconciling dependencies
- Updating solution ownership
- Cleaning obsolete solution references
- Optimizing solution layers
As part of this cleanup, redundant unmanaged ownership may be removed when the managed solution fully represents the same component.
When Would the Unmanaged Layer Stay?
The unmanaged layer would remain if there were actual customizations in the target environment.
For example:
- Install the managed solution.
- Modify the field directly in the target environment.
- Publish the customization.
Now the unmanaged layer contains real overrides and cannot simply disappear.
Similarly, if any metadata differs between the managed definition and the local customization, Dataverse preserves the unmanaged layer because it represents meaningful changes.
The Real Rule
Many people summarize solution layering with:
Unmanaged always has the highest priority.
A more accurate statement would be:
When multiple layers define different values for the same component, unmanaged customizations override managed layers.
Notice the important condition:
Both layers must actually exist.
In my scenario, Dataverse determined that there was no override. There were simply two representations of the exact same component. Instead of maintaining duplicate ownership, it reconciled them into a single managed component. The unmanaged layer didn't lose. It simply became unnecessary.
Key Takeaway
This behavior often surprises even experienced Dynamics 365 developers because Microsoft's documentation focuses heavily on layer priority, but spends very little time explaining component ownership.
The key lesson is this:
- Unmanaged layers only exist when there is something to override.
- Identical managed and unmanaged definitions do not necessarily result in two layers.
- During managed solution upgrades, Dataverse may reconcile ownership and remove redundant unmanaged customizations.
Understanding this distinction makes many seemingly "strange" solution-layering behaviors much easier to explain.
- The unmanaged layer wasn't ignored.
- It wasn't overridden.
- It wasn't a lower priority.
- It simply ceased to exist because Dataverse no longer needed it.
