This is Part 1 of a 3-part series on Dataverse solution deployments:

1. Dataverse solution component types (you are here)
2. Making Dataverse solution imports fast
3. Package Deployer for solutions, data, and migrations

The docs explain solutions as “containers for customizations.” That is correct but not useful when you need to understand why some imports are fast and others are painfully slow. Or why some components show clean diffs in source control and others are opaque blobs.

This post covers the two distinct component architectures inside Dataverse. They import differently, diff differently, and have different tradeoffs. Understanding the difference helps you make better decisions about ALM tooling and troubleshooting.

What is in a solution ZIP

A managed solution is a ZIP file. The most important files inside:

• solution.xml - the manifest. Lists RootComponents with their type codes and schema names. Contains solution metadata like version, publisher, and dependencies.
• customizations.xml - the definitions. This is where platform component definitions live. Entities, attributes, relationships, forms, views, sitemap fragments, ribbons, all packed into one XML file.
• Individual payload files - some components (plugins, web resources, SCF components) have separate files referenced from the manifest.

When you unpack a solution with Solution Packager, it splits customizations.xml into individual files organized by component type. Each entity gets a folder. Each form gets a file. This is what ends up in source control.

Managed vs unmanaged

Important: Unmanaged solutions are only supposed to be used for export to source control and hydrating developer environments. This post doesn’t consider deploying unmanaged solutions beyond developer environments as a valid option.

Dataverse uses a layering system for solution components. Every component exists in one or more layers.

• The System layer is at the bottom. It contains out-of-box definitions shipped by Microsoft.
• Managed layers stack above the system layer in installation order. Each managed solution gets its own layer.
• The Active (unmanaged) layer sits on top. This is where maker customizations go when someone edits a component directly in the environment.

All unmanaged solutions in the same environment share that one Active layer. Working in Solution A versus Solution B does not isolate makers from each other. Preferred solution changes where new components are added, not which unmanaged layer they land in.

When Dataverse needs to compute the current state of a component, it resolves layers top-down. For most component types, the top layer simply wins. Forms, site maps, and model-driven apps are the notable merge cases. If a managed layer removes a property, the value from the layer below can surface again.

This is why OverwriteUnmanagedCustomizations matters for import performance. When set to true, the import overwrites the active layer, which forces Dataverse to reprocess every component. When false, SmartDiff can skip unchanged components entirely. More on that in Part 2.

Layers versus built-in solutions

One thing that confuses almost everyone at first is that Dataverse mixes layer concepts and solution containers.

• System is the base platform layer.
• Active is the top unmanaged layer.
• Default Solution is the special built-in solution that exposes all components in the environment.
• Common Data Service Default Solution is the built-in maker default where new components land unless you choose another unmanaged solution.

Those are not interchangeable ideas. System and Active describe how Dataverse computes runtime behavior. Default Solution and Common Data Service Default Solution describe where components are surfaced or created.

This is also where Preferred solution fits in. Preferred solution is a per-maker routing setting. If you set it, newly created solution-aware components are added to that unmanaged solution instead of the Common Data Service Default Solution. If you do not set it, Dataverse uses the Common Data Service Default Solution by default.

There is also a hidden Basic solution. It is not part of the public maker model and it is not a place to author customizations. One of the reasons for it is Block unmanaged customizations. That feature is supposed to stop ordinary unmanaged maker edits in production environments. But the platform and some features still need ways to create certain components in runtime without treating them like ad hoc customizations in the Active layer.

Built-in Dataverse solutions and GUIDs

If you want to inspect them directly, query the solution table and filter by solutionid, uniquename, friendlyname, isvisible, and ismanaged.

What “managed” means for ownership

A managed component is owned by its solution publisher. Makers in the target environment can customize it (adding an active layer on top) but cannot delete it. Only uninstalling or upgrading the managed solution can remove managed components.

This is the mechanism that enables safe component removal during upgrades. The single-step upgrade (StageAndUpgradeRequest) compares the incoming solution against the installed version and deletes components that are no longer present.

Managed properties

Managed ownership is only half the story. Managed properties are the switches the original publisher sets to control how much downstream customization is allowed. They are configured while the component is still unmanaged in development, then enforced after the managed solution is installed elsewhere.

That matters because “managed” does not automatically mean “locked down.” A table can be managed but still allow new forms, new views, or label changes. Or it can be tightly restricted. If a downstream team says “we can’t change this managed component,” the next question is whether the publisher disabled that through managed properties.

Publisher strategy: pick one early

Use one publisher across related solutions unless you have a strong reason to split ownership. The publisher owns managed components, and that ownership association is not something you change later.

The prefix choice also sticks. Schema names, logical names, and choice value prefixes are created in the context of that publisher. If you later decide the component should really belong to a different publisher, you are usually looking at delete-and-recreate, plus data migration if the component stores data. Pick the publisher and prefix like you expect to live with them for years.

Platform components

These are the original component types. They are implemented directly in the Dataverse codebase and identified by fixed, well-known type codes. The full list is published in the SolutionComponent entity reference.

Examples: entities (type code 1), attributes (2), relationships (10), forms (60), views (26), plugins (90), web resources (61).

Type codes are static. They don’t change between environments.

Platform component definitions land in customizations.xml inside the solution ZIP. Solution Packager knows exactly how to decompose them into individual files because the schema is fixed and documented.

In source control, platform components are readable. You can diff a form XML and see which tabs or sections changed. You can review an entity definition and spot new attributes. Code review works.

Table segmentation keeps layers cleaner

For existing tables, include only the assets you actually changed. If you changed one column and one form, ship that. Do not drag the whole table into every update unless the table is brand new in the target environment.

Smaller table payloads create fewer unnecessary layers, fewer accidental dependencies, and fewer chances to stomp on someone else’s top-wins component or form merge. It also helps import performance, which is one of the reasons Part 2 keeps coming back to smaller, more focused updates.

SmartDiff for platform components

SmartDiff coverage on the platform side expands over time as Microsoft enables it for additional component types. When your import processes fewer components than the total in the solution, SmartDiff is working. When it processes all of them, either everything legitimately changed, OverwriteUnmanagedCustomizations is true, or the component type isn’t covered by SmartDiff yet.

SCF components

Solution Component Framework (SCF) is the newer architecture. Product teams at Microsoft use it to add new component types to Dataverse without changing the core platform code.

SCF components are registered via solutioncomponentdefinition metadata, brought to environments dynamically by Microsoft first-party solutions. Each product team decides what their component looks like in a solution export.

How SCF differs from platform components

Runtime-assigned type codes - SCF components use objecttypecode values typically above 1000. These codes are assigned at runtime and can differ between environments. Dataverse resolves SCF components by their unique component names on import, not by type code.

No static schema - Each component owner decides the export format. Some use JSON. Some use XML. There is no single schema reference for validation.

Lax import validation - SCF component types vary in how strictly they validate incoming payloads. Some accept values that only fail at runtime rather than at import time, so errors can surface later than you would expect.

Worse readability in source control - SCF component files are typically files with non-descriptive name and unnecessary folder nesting. JSON payloads with GUIDs and encoded properties. Not friendly for code review or conflict resolution.

SmartDiff for SCF components

SCF was designed with diff support built into the framework itself. SCF components get SmartDiff coverage automatically as new types are introduced. This is different from platform components where SmartDiff has to be enabled per type.

Discovering SCF components

To see which SCF component types exist in a given environment:

GET ORG/api/data/v9.2/solutioncomponentdefinitions?$select=name,objecttypecode

The response shows you every registered component type with its runtime type code. Compare across environments to see why type codes might differ.

Deployment methods

Today the platform supports multiple ways to deploy solutions:

• Maker UI - manual import through make.powerapps.com
• PAC CLI - pac solution import with various flags
• Azure DevOps tasks and GitHub Actions - wrappers over PAC CLI
• Power Platform Pipelines - managed by the platform, abstracts import details server-side
• Package Deployer - multi-solution orchestration with custom code hooks. You run Package Deployer yourself (locally, in a pipeline, or via PowerShell).
• Catalog - submit a Package Deployer package to the platform and let it handle execution. Installations go through the same internal service (TPS) that processes AppSource installs and first-party Microsoft updates, so your deployment is queued alongside platform servicing rather than competing with it. Useful when weekend servicing windows cause import conflicts. See Part 3 for details.
• Native Git integration - component-level sync between a dev environment and an Azure DevOps repo. Bypasses the solution import pipeline entirely. See Part 2.

All of these end up calling Dataverse APIs underneath (except native Git, which uses its own code path). The differences are in what parameters they pass, what defaults they use, and how much control you get.

Part 2 covers which import types exist and how to make them fast. Part 3 covers Package Deployer for teams that need orchestration, custom code, and data migrations.

This is Part 2 of a 3-part series on Dataverse solution deployments:

1. Dataverse solution component types
2. Making Dataverse solution imports fast (you are here)
3. Package Deployer for solutions, data, and migrations

If you search “slow solution import” and land here, you are in the right place. This post covers the four import types Dataverse supports, how SmartDiff skips unchanged components, real benchmark numbers comparing each method, and a troubleshooting checklist. Part 1 explains what is inside a solution. Part 3 covers Package Deployer for teams that need orchestration and custom code.

TL;DR

• Use single-step upgrade (StageAndUpgradeRequest / pac solution import --stage-and-upgrade) for routine managed deployments. It’s atomic, supports SmartDiff, and rolls back cleanly on failure.
• Reserve two-step “Stage for upgrade” only when you need a migration window between old and new versions (e.g., data transforms via Package Deployer’s RunSolutionUpgradeMigrationStep). More on that in Part 3.
• SmartDiff accelerates Update and single-step Upgrade by skipping unchanged components, but it is disabled when OverwriteUnmanagedCustomizations is true. If unmanaged drift is the problem, use Block unmanaged customizations instead of force-overwrite.
• Keep updates small and segmented. For existing tables, include only the changed assets rather than the whole table. Avoid Publish all customizations and convert-to-managed for managed deployments.
• If imports feel slow, update your tooling first. Newer Dataverse API endpoints (StageAndUpgrade, StageSolution) unlock SmartDiff and single-step upgrades. Older tools may still use the legacy two-step path. Then check msdyn_isoverwritecustomizations in msdyn_solutionhistory to rule out SmartDiff being disabled.

Which import method should I use?

For most teams shipping managed solutions, single-step upgrade is the default choice. It deletes removed components, supports SmartDiff, and completes as one transaction. Fall back to the two-step path only when you need both the old and new versions installed concurrently.

Solution import types

Each deployment client calls the Dataverse SOAP web service (legacy) or OData API. The main behaviors map to these request types:

SmartDiff applies to Update and Single Step Upgrade only when OverwriteUnmanagedCustomizations is set to false.

The screenshot below shows the Solution Import History page in Power Apps Maker. Use the Operation and Suboperation columns to identify the type of import. Refer to the table above for interpretation.

Terminology note

The word “stage” is heavily overloaded in this space:

SmartDiff

SmartDiff has been available since 2021 for the Update import type. In 2024, Microsoft extended it to single-step upgrades (StageAndUpgradeRequest). The SDK message itself shipped earlier (January 2021, org version 9.2.21013.00131), but SmartDiff did not apply to that path until the 2024 rollout.

How it works: When you import a solution, Dataverse stores a copy in blob storage. On the next import, it compares the incoming components against the stored version at the XML/metadata level. Components where nothing changed are skipped entirely. The platform generates a filtered import containing only the delta and processes that instead.

If you remember the now-deprecated solution patches (CloneAsPatch), SmartDiff achieves a similar goal, reducing the import to only changed components, but does so automatically without requiring you to manually create and manage patch solutions.

In practice, this can make updates and single-step upgrades dramatically faster when most components have not changed.

For classic platform components (entities, attributes, relationships, forms, views), SmartDiff is enabled individually per component type. The newer SCF components, those with type codes above 1000 registered via solutioncomponentdefinition, were designed with diff support built into the framework itself. SmartDiff coverage extends to them automatically as new SCF types are introduced.

Important: Setting OverwriteUnmanagedCustomizations to true disables SmartDiff. The check happens before any comparison. If the flag is true, Dataverse skips the optimization and processes all components unconditionally. Force-overwrite significantly slows managed solution imports. If the real problem is unmanaged drift in nondevelopment environments, use Block unmanaged customizations instead of leaving force-overwrite enabled.

Two-step upgrades and when they are still useful

Important: The two-step “Stage for upgrade” path is the slowest of all upgrade methods. It does not benefit from SmartDiff. The Maker UI uses synchronous DeleteAndPromote for the apply step, a blocking HTTP call with no progress feedback, though DeleteAndPromoteAsync is also available via the Web API for automation. Only use this path when you genuinely need the migration window, not for routine deployments.

How it works

The Maker UI “Stage for upgrade” button calls ImportSolutionAsync with HoldingSolution: true (not StageAndUpgradeAsync). This imports a temporary {SolutionName}_Upgrade holding solution injected above the base solution layer and below any solution sitting above it. Because importcontext = ImportHolding, SmartDiff does not apply. All components are processed unconditionally.

Applying the upgrade fires DeleteAndPromote, which removes the old base layer and any pending patches, then renames the _Upgrade solution by stripping the suffix. Every component is touched twice across the two phases with no optimization.

Why single-step is different

StageAndUpgradeRequest was designed differently. Instead of creating a separate layer and promoting it, it works like the Update path, modifying the existing solution layer in place and additionally deleting components no longer present in the new version. Because it shares the in-place update architecture, SmartDiff applies the same way it does to Update imports. No _Upgrade solution is created. If the operation fails, the transaction rolls back cleanly.

When to use two-step anyway

The two-step flow is the right choice when you need a controlled migration window. “Stage for upgrade” imports the new version but defers deletion of the previous version. Select this option when you need both old and new versions installed concurrently to run data migrations before completing the upgrade.

For example, you can stage the new version, run migrations or transform data (you can use Package Deployer’s RunSolutionUpgradeMigrationStep), then apply the upgrade. Part 3 covers this in detail.

Note: Package Deployer automatically detects whether your package has a meaningful implementation of RunSolutionUpgradeMigrationStep. If custom migration code is detected, PD switches to the two-step holding path and calls your migration code after the holding import completes but before DeleteAndPromote fires. You can confirm this from PD’s log output: User Provided Upgrade code is not detected in package. if allowed, Package Deployer will use one step upgrade pattern for this package.

Dependency cleanup

The two-step path also helps with dependency cleanup across solution layers. When removing a component referenced by higher layers, you need to control the upgrade order so the upper layer drops the dependency first. Part 3 covers the practical details.

Benchmark

The following numbers are from a real managed solution with 79 components, measured on a single environment. Each version contained one changed component (a single column label edit) against the prior version, so the SmartDiff delta was consistent across runs.

Reading the results

The msdyn_suboperation values map to: 1 = Install, 2 = HoldingImport / DeleteAndPromote, 3 = Update, 5 = Upgrade (atomic). Both Update (3) and Upgrade (5) produce importcontext = ImportUpgrade and benefit from SmartDiff. Install (1) and HoldingImport (2) do not.

SmartDiff impact (v1.0.0.7, control experiment): Same solution, same change size, same API action as v1.0.0.4. The only difference is OverwriteUnmanagedCustomizations=true. SmartDiff was completely absent from the importjob XML and all 79 components were processed: 414 s vs 95 s. The flag forces unconditional processing of every component.

Two-step penalty (v1.0.0.6): The holding import processed all 79 components with no SmartDiff (433 s), then DeleteAndPromote touched every component again (193 s). 626 s total, the slowest path. DeleteAndPromote was a synchronous blocking HTTP call with no progress feedback in the Maker UI. The API also exposes DeleteAndPromoteAsync for automation scenarios.

Package Deployer (v1.0.0.8): PD’s one-step upgrade path produced results identical to a direct StageAndUpgradeAsync call. 93 s, SmartDiff active, 28 of 79 components processed. PD ends up calling the same StageAndUpgrade API the direct path does, so there is nothing extra happening at the Dataverse import layer. In this benchmark, Package Deployer showed no measurable overhead.

Note: msdyn_solutionhistory alone cannot tell you which imports came from Package Deployer vs direct API calls. msdyn_packagename, msdyn_packageversion, and msdyn_correlationid are not populated by PD. PD writes to a separate packagehistory platform entity. See Part 3 for how to correlate them.

Note: Power Platform Pipelines abstracts the import entirely. The Maker Portal calls DeployPackageAsync { StageRunId } and the actual import action, OverwriteUnmanagedCustomizations, PublishWorkflows, and all other parameters are decided server-side by the Pipelines service.

Troubleshooting import performance

XrmToolBox Solution History tool

The most convenient way to troubleshoot slow imports. make.powerapps.com doesn’t expose per-component details, and parsing raw XML by hand is painful. The Solution History tool for XrmToolBox shows import history, SmartDiff status, component-level details, errors and warnings, and per-component processing timestamps parsed from importjob.

Solution history table

msdyn_solutionhistory records every import operation with timing, status, operation/suboperation, and whether customizations were overwritten.

The most useful fields for troubleshooting are msdyn_totaltime, msdyn_operation, msdyn_suboperation, and msdyn_isoverwritecustomizations. Note that msdyn_isoverwritecustomizations is a proper OData column. It is the reliable place to check whether a specific import ran with force-overwrite. The importjob XML does not include this parameter.

Import job detail

The importjob entity has a data column containing an XML blob with per-component details including timing. It also exposes importcontext (ImportInstall, ImportUpgrade, or ImportHolding).

If SmartDiff was used, the XML contains a SmartDiffApplied element. That is the most direct place to confirm whether the optimization kicked in.

Troubleshooting checklist

If imports are still slow after switching to single-step upgrade, check these in order:

1. Is msdyn_isoverwritecustomizations set to true in msdyn_solutionhistory? This is the #1 cause. It disables SmartDiff entirely.
2. Are you accidentally using the holding import path? Check msdyn_suboperation. Value 2 means HoldingImport.
3. Is SmartDiff actually applying? Look for SmartDiffApplied in the importjob XML.
4. Did someone recently enable a new language in the environment? After a language rollout, the first import of every solution is slower. Expected, one-off.

Tooling

Many organizations still run outdated tooling that doesn’t support modern import types.

• PAC CLI: Keep it updated. Older versions don’t support --stage-and-upgrade. Key flag defaults:
  • --activate-plugins controls PublishWorkflows. Defaults to false. Pass it explicitly if your solution has cloud flows or SDK steps.
  • --force-overwrite (OverwriteUnmanagedCustomizations) defaults to false. SmartDiff is on by default.
  • AsyncRibbonProcessing cannot be set via PAC CLI. No flag exists. Call the API directly if needed.
  • --skip-lower-version skips import if the same or higher version is already installed.
• Package Deployer PowerShell (Microsoft.PowerApps.PackageDeployment / Microsoft.PowerApps.PackageDeployment.PowerShell): keep up to date. Older releases predate the single-step upgrade pattern. If you hit trouble, upgrade the module before investigating further. Version 3.3.0.1039+ (Package Deployer 4.0.0.183+).
• Azure DevOps Tasks: If you use third-party tasks such as dyn365-ce-vsts-tasks, check which PowerShell and tooling versions they invoke.

Solution versioning and version-skip optimization

Power Platform Maker UI presents “Update,” “Upgrade,” and “Stage for Upgrade” options when the system already contains the same managed solution with a lower version number. If you import a solution with the same version number that already exists, the “Update” type is used. Lower versions can’t be uploaded through the UI (as of 2025), but it was recently allowed through CLI/API to enable rollback scenarios in Power Platform pipelines.

Skipping unchanged solutions

For projects with components segmented into multiple solutions, import speed can be improved by incrementing solution versions only when changes are detected in the solution project folder. Tools like GitVersion can determine the version at build time and overwrite the value in solution.xml. Solutions with matching versions can then be skipped entirely. Their ZIP files never even get uploaded. Smaller solution boundaries and smaller table payloads also reduce unnecessary layers before the import starts.

Package Deployer defaults to skipping same or lower versions (see version-skip logic in Part 3). For PAC CLI, use the --skip-lower-version flag.

Upload and validation via the staging endpoint

Solutions can be uploaded and validated before import using StageSolutionRequest. This uploads and validates the solution ZIP, returning validation results and an upload ID (StageSolutionResults.StageSolutionUploadId). The file is stored in the StageSolutionUpload entity.

You can then execute any of:

• Update via ImportSolutionAsyncRequest
• Two-step upgrade via ImportSolutionAsyncRequest with HoldingSolution=true followed by DeleteAndPromoteRequest
• Single-step upgrade via StageAndUpgradeAsyncRequest

Pass the StageSolutionUploadId via SolutionParameters.StageSolutionUploadId. Only Async message versions support this parameter.

This decouples validation from deployment. Both the Maker UI Update and Upgrade flows call StageSolution first. The file is uploaded, the component manifest (IsPresentInOrg per component) is returned, the UI renders a preview dialog, and only after confirmation does the import call fire with the upload ID.

PAC CLI 2.6.3 always calls StageSolution first, even for a plain pac solution import. The CLI uploads the full ZIP bytes, receives the upload ID, and passes it to the subsequent import request. The staging response is also used to resolve connection references and environment variables before the import fires.

At the API level, Dataverse exposes both ImportSolutionAsync (with an optional HoldingSolution parameter) and a dedicated StageAndUpgradeAsync action. Two separate API paths for upgrades.

Important: StageSolutionRequest is a validation-only endpoint. It does not import any solution and does not create a holding solution. It cannot create the two-solution state required for upgrade-time migrations. For migrations, use ImportSolutionAsyncRequest with HoldingSolution=true instead.

Import speed evolution

Dynamics CRM 2011 had no supported way of deleting components during upgrade. Developers used a “holding solution” trick: export, unzip, rename the solution unique name, import, delete the old one, re-import with the correct name, then remove the temporary solution.

Dynamics CRM 2016 introduced “Stage for upgrade” and “Apply solution upgrade.” This imports a temporary holding solution (with _Upgrade suffix) above the base solution layer and below other layers. Applying the upgrade fires DeleteAndPromoteRequest to remove the old version and any components not present in the new package. This process is very slow as it manipulates all components multiple times.

v9.0 added an “Upgrade” option in the UI that combined both steps in one click. Still a holding import followed by promote under the hood, but initiated as a single user action. If an error occurred during promote, it left the _Upgrade solution behind.

2021: Microsoft introduced SmartDiff for the Update import type (cloud SKU). The platform stores each imported solution in blob storage and compares incoming components at the XML/metadata level on subsequent imports. Only changed components are processed when SmartDiff is active.

Jan 2021 (org ≥ 9.2.21013.00131): The StageAndUpgradeRequest SDK message shipped as a single-step atomic upgrade path. At first it was plumbing only. SmartDiff did not yet apply to it.

Late 2023 / early 2024: PAC CLI exposed the --stage-and-upgrade switch (from version 1.28 onward), and Power Platform Build Tools / GitHub Actions added the flag. This made the one-step path practical for CI/CD.

2024: Microsoft began rolling out SmartDiff on the StageAndUpgrade path in waves. Before this, upgrades touched every component multiple times (holding import + DeleteAndPromote). After this, the one-step upgrade can skip unchanged components. Shan McArthur (Principal PM, Dataverse ALM) flagged an expected ~45 % improvement over the classic upgrade pattern.

How does native Git integration relate to this?

A common question is whether native Git integration makes the solution import pipeline irrelevant. It doesn’t, but the comparison is worth understanding.

Dataverse rolled out native Git integration for developer environments. It connects an environment to an Azure DevOps repository and syncs component metadata back and forth. Currently Azure DevOps only, GitHub support will come soon.

The important thing for this post is that Git pull doesn’t go through the normal solution import pipeline. It’s a completely separate code path:

1. The environment tracks every component with a path and content hash stored in internal Dataverse entities.
2. On pull, it compares environment hashes with hashes in the Git branch.
3. Only components that differ are fetched from Azure DevOps.
4. Changed components are applied individually, not through the solution import path.

You can see the feature’s footprint in live metadata: sourcecontrolconfiguration, sourcecontrolbranchconfiguration, sourcecontrolcomponent, sourcecontrolcomponentpayload, and stagedsourcecontrolcomponent.

It’s a change-set-first path, while ImportSolution and StageAndUpgrade are package-first paths.

For the inner dev loop this is a big productivity improvement. Save on one environment, commit to Git, pull to another dev environment. Only changed components move across.

SmartDiff and native Git pull are not the same thing. SmartDiff optimizes a full solution upgrade by skipping unchanged components inside a ZIP. Native Git pull never builds the full ZIP in the first place. They solve related problems at different layers.

Next

If you’re deploying a single solution, the default above is all you need. For multi-solution projects, data migrations, or custom code hooks during deployment, Part 3: Package Deployer for solutions, data, and migrations covers the orchestration layer that sits on top of the import API.

For avoiding servicing-window conflicts: Submit your Package Deployer package to the Catalog so the platform queues your deployment alongside its own updates instead of competing with them.

This is Part 3 of a 3-part series on Dataverse solution deployments:

1. Dataverse solution component types
2. Making Dataverse solution imports fast
3. Package Deployer for solutions, data, and migrations (you are here)

Package Deployer is the most advanced deployment option for Dataverse. If you are deploying a single solution with no special requirements, PAC CLI is simpler and does the job. Package Deployer is for when you outgrow that.

When and why Package Deployer

• Configuration data between environments - The most convenient way to move reference data, lookup values, and environment-specific settings alongside your solutions. CMT (Configuration Migration Tool) data packages are imported as part of the same deployment unit, so schema and data stay in sync.
• Conditional automation via pipeline parameters - Pass RuntimeSettings from the CLI without rebuilding the package. Your custom code can branch on these values: skip a data load, toggle a feature, set up connection, enable flows - whatever the target environment needs.
• Data migrations with stage-for-upgrade - When you need to move data from one column to another (e.g., different data type), combine Package Deployer with the Stage for Upgrade + Apply Upgrade pattern from Part 2. Stage the new solution version so both old and new columns are present, run your migration code in a Package Deployer hook, then apply the upgrade to remove the old column. This gives you a safe window to transform data in-place.
• Multi-solution deterministic ordering - You control which solutions import first, second, third.
• Custom code execution at every stage - Seven hooks in the lifecycle, from initialization to post-deployment.
• Explicit control over import type per solution - Force a specific import action, skip solutions conditionally, override flags per solution.

Default parameter values

Package Deployer’s defaults differ from PAC CLI in one way:

The PublishWorkflows difference matters if your solution contains cloud flows or SDK message steps. Both tools default to false for OverwriteUnmanagedCustomizations, so SmartDiff is enabled by default in both. The PreSolutionImport hook lets a package override both flags per-solution at runtime.

Automatic one-step vs two-step path selection

Package Deployer 4.0+ automatically decides between one-step and two-step upgrade at runtime. It inspects your package to see whether RunSolutionUpgradeMigrationStep contains real migration code. An empty override is treated as “no migration code” and the one-step path is chosen (provided the org supports single-step upgrades, version 9.2.21013.00131+). You can confirm the decision from PD’s log line User Provided Upgrade code is not detected in package.. Under the hood, PD sets USESTAGEANDUPGRADEMODE=true on the import request so ServiceClient issues a StageAndUpgradeRequest instead of a classic ImportSolutionRequest.

The two-step holding path is chosen when:

• Custom upgrade code is detected in the package, or
• forceupgradecodestep="true" is set on a solution in the import config XML, or
• One-step upgrade is explicitly disabled in the app configuration

When the two-step path runs, RunSolutionUpgradeMigrationStep is called after the holding import completes but before DeleteAndPromote fires. This is the migration window.

Package Deployer also does not change the underlying Dataverse rules covered in Part 1. Dependencies still have to resolve. Publisher ownership can still determine if you can perform operations. Managed properties decide how much a managed component can be customized downstream.

Version-skip logic

Package Deployer applies this decision matrix before every individual solution import:

Both SkipSameVersion and SkipLowerVersion are silent. They produce an info log entry and the deployment continues as successful. An operator cannot distinguish “was imported” from “was skipped” without reading Package Deployer logs. The OverrideSolutionImportDecision hook lets package code force-reimport the same version or skip a version that would otherwise be imported.

Configuration data and reference data

One of the most practical reasons to use Package Deployer is that it can move schema and reference data together. Package Deployer supports CMT (Configuration Migration Tool) data packages defined in ImportConfig.xml. The cmtdatafiles element lists data files with LCID (Locale ID) based language variants.

Import ordering: solutions first, then data. This ensures schema is in place before records are created.

Key properties for data import:

• DataImportBypass = true - skip all CMT data imports. Useful when deploying to environments that already have reference data. Set this in InitializeCustomExtension based on RuntimeSettings.
• OverrideDataImportSafetyChecks = true - skip duplicate detection and other safety checks during data import. Only use on clean/empty environments. Significant performance gain for initial data loads.

Data migrations during upgrades

The two-step holding path exists for a reason. When you need to transform data between solution versions, the migration window provided by RunSolutionUpgradeMigrationStep is the supported approach.

If a managed upgrade removes a custom table or column, the platform can remove that schema and the data stored in it. That is one of the main reasons to do migrations before DeleteAndPromote.

Cross-solution dependency cleanup or component deprecation

When removing a component referenced by higher layers, you need to control the upgrade order. Import affected solutions as holding and then apply upgrades top-down (reverse order) so the upper layer drops the dependency before the base layer is upgraded.

Example: a UI solution references a table you plan to drop from the Data Model solution. If you upgrade the Data Model first, the delete is blocked by dependencies from the UI solution.

In simpler cases, you do not always need to remove the dependency and the component in the same release. A safer pattern is to split the change across two deployments: in release N, remove the dependency and make the old component inert or clearly deprecated; in release N+1, remove the component once higher layers no longer reference it. That reduces upgrade coordination pressure and can avoid forcing a holding-upgrade sequence just to clean up one lingering dependency.

Package lifecycle and custom code hooks

If the built-in defaults above are not enough, this is where Package Deployer becomes more than a solution importer. A PD package contains an ImportConfig.xml manifest (lists solutions to import, CMT data files, and import settings) and a .NET assembly with a C# class that provides overridable hooks. Running pac package init scaffolds the project from a dotnet new template (shortName pp-pdpackage).

Package Deployer exposes seven overridable methods in a fixed execution order. Your package class inherits from the SDK’s ImportExtension base class (which implements IImportExtensions2 through IImportExtensions8). The scaffolded class called PackageImportExtension extends ImportExtension and is discovered at runtime via MEF ([Export(typeof(IImportExtensions))]). You override the methods you need.

1. InitializeCustomExtension

public override void InitializeCustomExtension()

Called first, before any solution import starts. Use it to read RuntimeSettings, configure flags, and set up your deployment context.

public override void InitializeCustomExtension()
{
    if (RuntimeSettings != null && RuntimeSettings.ContainsKey("SkipData"))
    {
        DataImportBypass = Convert.ToBoolean(RuntimeSettings["SkipData"]);
    }
}

Pass runtime settings from the CLI: --settings SkipData=true

Key properties you can set here:

• DataImportBypass - skip all CMT data imports
• OverrideDataImportSafetyChecks - skip safety checks on CMT data import (only for clean environments, speeds up data import)

2. OverrideSolutionImportDecision

public override UserRequestedImportAction OverrideSolutionImportDecision(
    string solutionUniqueName,
    Version organizationVersion,
    Version packageSolutionVersion,
    Version inboundSolutionVersion,
    Version deployedSolutionVersion,
    ImportAction systemSelectedImportAction)

From IImportExtensions3. Called after the version-skip check, once per solution. systemSelectedImportAction is the ImportAction value PD already picked (for example SkipSameVersion, SkipLowerVersion, or Import). Return a UserRequestedImportAction to override it:

• Default - accept the system decision
• Skip - skip this solution
• ForceUpdate - import even if the system would have skipped the same version (has no effect when the system chose SkipLowerVersion)

public override UserRequestedImportAction OverrideSolutionImportDecision(
    string solutionUniqueName,
    Version organizationVersion,
    Version packageSolutionVersion,
    Version inboundSolutionVersion,
    Version deployedSolutionVersion,
    ImportAction systemSelectedImportAction)
{
    // Skip satellite solutions in non-production environments
    if (solutionUniqueName.EndsWith("_Satellite")
        && RuntimeSettings != null
        && RuntimeSettings.ContainsKey("Environment")
        && RuntimeSettings["Environment"]?.ToString() != "Production")
    {
        return UserRequestedImportAction.Skip;
    }
    return UserRequestedImportAction.Default;
}

3. PreSolutionImport

public override void PreSolutionImport(
    string solutionName,
    bool solutionOverwriteUnmanagedCustomizations,
    bool solutionPublishWorkflowsAndActivatePlugins,
    out bool overwriteUnmanagedCustomizations,
    out bool publishWorkflowsAndActivatePlugins)

Called for each solution before its import starts. You can override OverwriteUnmanagedCustomizations and PublishWorkflows per solution.

public override void PreSolutionImport(
    string solutionName,
    bool solutionOverwriteUnmanagedCustomizations,
    bool solutionPublishWorkflowsAndActivatePlugins,
    out bool overwriteUnmanagedCustomizations,
    out bool publishWorkflowsAndActivatePlugins)
{
    // Keep SmartDiff enabled for all solutions
    overwriteUnmanagedCustomizations = false;
    // Activate flows only for the main solution
    publishWorkflowsAndActivatePlugins = solutionName == "CoreSolution";
}

4. RunSolutionUpgradeMigrationStep

public override void RunSolutionUpgradeMigrationStep(
    string solutionName,
    string oldVersion,
    string newVersion,
    Guid oldSolutionId,
    Guid newSolutionId)

The migration window. Called after the holding import completes but before DeleteAndPromote fires. This is the only time both old and new versions exist simultaneously in the environment.

Use it for data transformation, schema migration, or cleanup that depends on comparing old and new component states.

public override void RunSolutionUpgradeMigrationStep(
    string solutionName,
    string oldVersion,
    string newVersion,
    Guid oldSolutionId,
    Guid newSolutionId)
{
    if (solutionName == "DataModel" && new Version(oldVersion) < new Version("2.0.0.0"))
    {
        // Migrate data from old schema to new schema
        // Both old and new solution layers are active right now
        MigrateAccountCategories(oldSolutionId, newSolutionId);
    }
}

Important: If you implement this method with real code (not just an empty override), Package Deployer automatically switches to the two-step holding path for that solution. The one-step upgrade is not used. You can confirm this from PD’s log: User Provided Upgrade code is not detected in package. if allowed, Package Deployer will use one step upgrade pattern for this package.

5. BeforeImportStage

public override bool BeforeImportStage()

Called after all solutions are imported, before data and flat file imports begin. Return true to continue, false to abort all remaining data and file imports.

public override bool BeforeImportStage()
{
    // Guard: this package's CMT data assigns records to a shared team.
    // Validate that prerequisite before data import starts.
    var query = new QueryExpression("team")
    {
        ColumnSet = new ColumnSet("teamid"),
        TopCount = 1,
        Criteria = new FilterExpression
        {
            Conditions =
            {
                new ConditionExpression("name", ConditionOperator.Equal, "Operations")
            }
        }
    };
    if (CrmSvc.RetrieveMultiple(query).Entities.Count == 0)
    {
        PackageLog.Log("Required team 'Operations' is missing; aborting data import.", TraceEventType.Error);
        return false;
    }
    return true;
}

6. OverrideConfigurationDataFileLanguage

public override int OverrideConfigurationDataFileLanguage(
    int selectedLanguage,
    List<int> availableLanguages)

Override which CMT data language file to import. Return the LCID of the language you want. Called when the package contains language-specific configuration data files.

7. AfterPrimaryImport

public override bool AfterPrimaryImport()

Called after all solutions and data have been imported. Return true if successful, false to mark the deployment as failed. Use for post-deployment automation.

public override bool AfterPrimaryImport()
{
    CreateProgressItem("Activating post-import workflows");

    // Activate specific cloud flows by unique name
    var flowNames = new[] { "contoso_ApprovalFlow", "contoso_NotificationFlow" };
    foreach (var flowName in flowNames)
    {
        var query = new QueryExpression("workflow")
        {
            ColumnSet = new ColumnSet("workflowid"),
            Criteria = new FilterExpression
            {
                Conditions =
                {
                    new ConditionExpression("uniquename", ConditionOperator.Equal, flowName),
                    new ConditionExpression("statecode", ConditionOperator.Equal, 0) // inactive
                }
            }
        };
        var flow = CrmSvc.RetrieveMultiple(query).Entities.FirstOrDefault();
        if (flow != null)
        {
            CrmSvc.Update(new Entity("workflow", flow.Id)
            {
                ["statecode"] = new OptionSetValue(1),
                ["statuscode"] = new OptionSetValue(2)
            });
            RaiseUpdateEvent($"Activated flow: {flowName}", ProgressPanelItemStatus.Working);
        }
    }

    PackageLog.Log("AfterPrimaryImport complete.");
    return true;
}

Observability

Client-side logging

Package Deployer produces a structured SOLUTION_STATS log line for every solution after import completes:

SOLUTION_STATS=SOL:Bankaccountchangerequests|Result:Success|Operation:Import|IsUpgrade:True
  |OldVersion:1.0.0.7|NewVersion:1.0.0.8|ImportType:Async
  |RT:00:01:45.384   ← total round-trip (client wall time)
  |ST:00:01:39.865   ← server processing time
  |DPT:00:00:00.000  ← DeleteAndPromote time (0 = one-step, no separate promote)
  |WT:00:00:05.211   ← polling wait time
  |WTMB:00:00:00.000 ← metadata-blocked wait time (retries needed)

DPT=0 confirms the one-step path. WTMB shows whether metadata-contention retries occurred.

Dataverse logging entities

Package Deployer writes to two platform entities:

• package - a persistent “what’s installed” registry. One row per package, upserted on every deployment.
• packagehistory - a per-run audit log. One row per deployment with operationid, status, and timing.

Both are first-party platform tables (no msdyn_ prefix). Neither has a foreign key back to msdyn_solutionhistory. The msdyn_correlationid on solution history is all zeros for PD imports. To confirm a PD deployment, cross-reference packagehistory by time window.

Other notable behaviors

• Metadata-blocked retry: If the import is rejected because a concurrent metadata operation is holding a lock, PD retries up to 10 times with 60-second waits. The retry count and wait can be tuned via the SolutionImportBlockedRetryCountOverride and SolutionImportBlockedWaitOverride settings.
• Stale _Upgrade recovery: Before starting an upgrade, PD queries for a pre-existing {uniqueName}_Upgrade holding solution. If one is found, PD deletes it before proceeding, then re-imports from scratch. This prevents interrupted upgrades from blocking the next deployment.
• Post-loop PublishAll: If the package contains unmanaged solutions, PD issues a PublishAllXmlRequest after all imports complete.
• Orchestration queuing (PD 4.0+): Packages can be submitted as a single async job via QueuePackageDeployment. Falls back to the per-solution loop if unsupported.
• AsyncRibbonProcessing: PD can pass AsyncRibbonProcessing=true per-solution when configured (org ≥ 9.1.0.15400). PAC CLI has no flag for this.

Package Deployer ships as .NET Framework (net462) assemblies, Windows-only. The modern .NET version of PAC CLI (net10.0) dropped Package Deployer and CMT entirely rather than porting them. If you need to run Package Deployer or CMT data imports on Linux or macOS (e.g., containerized CI agents), TALXIS CLI (txc) solves this by IL-patching the original net462 assemblies with Mono.Cecil at startup so they load on modern .NET cross-platform. Commands: txc deploy package <package> for Package Deployer, txc data package import <path> for CMT data packages.

Catalog: platform-managed Package Deployer

Instead of running Package Deployer yourself, you can submit a package to the Power Platform Catalog and let the platform execute it. The catalog uses the same backend service (Trusted Publisher Service / TPS) that processes AppSource installs and first-party platform updates.

If your CI/CD pipelines run during weekends or off-hours, they can collide with platform servicing windows. First-party updates are deployed on a schedule and your concurrent ImportSolution calls compete for the same metadata locks, leading to retries, failures, and much longer deployment times. Catalog deployments enter the same internal queue, so they’re scheduled alongside platform updates rather than fighting them.

Submitting a package

Every catalog item is a Package Deployer package. If you already have a .pdpkg.zip, you can submit it directly. If you only have a solution ZIP, the platform can convert it into a PD package for you (via the Maker UI or the mspcat_PackageStore entity with operation: Create Package).

Submit via CLI:

pac catalog submit --path ./submission.json

The submission metadata JSON references your package file and includes publisher info, description, and deployment type (template or managed).

Or via SDK: use the mspcat_SubmitCatalogApprovalRequest message. Submissions go through an approval workflow (configurable, auto-approve is possible).

Installing a catalog item

pac catalog install -cid MyCatalogItem -te https://target-org.crm.dynamics.com/

Or via SDK: mspcat_InstallCatalogItemByCID message. You can pass RuntimeSettings (same pipe-delimited format as PD’s RuntimeSettings):

var request = new mspcat_InstallCatalogItemByCIDRequest
{
    CID = "MyCatalogItem@2.0.0.0",
    DeployToOrganizationUrl = "https://target-org.crm.dynamics.com/",
    Settings = "SkipData=true|Environment=Production"
};

Version pinning is supported: MyCatalogItem@2.0.0.0 installs that specific version.

Tracking installation status

The mspcat_InstallHistory entity tracks each deployment: Requested → Pending → In Progress → Completed / Failed. Check via:

pac catalog status --tracking-id <guid> --type Install

When to use Catalog over running PD yourself

• You want the platform to handle execution, retries, and queuing - no pipeline agent needed.
• You want to avoid import conflicts with platform servicing windows.
• You’re distributing packages to multiple environments or tenants within your organization.
• You want an approval workflow before deployments.

That wraps up the series. Part 1 covers what’s inside a solution ZIP and the two component architectures. Part 2 covers import types, SmartDiff, and how to diagnose slow imports. This post covered the orchestration layer on top of all that. If you’re deploying anything beyond a single solution, Package Deployer is worth the setup cost.

Full article

Full article

Full article

Full article

Full article

Full Article

Full article