DataMigrationToolbyXTB 1.2026.6.2

DataMigrationToolbyXTB

An XrmToolBox tool that migrates records from one Dataverse environment to another while preserving the record GUID. A record that does not exist on the target is created with the same Id; a record whose Id already exists on the target is updated.

This is ideal for moving configuration / reference data (and any GUID-sensitive records) between DEV → TEST → PROD without breaking the lookups and references that depend on those Ids.

The tool's display name in XrmToolBox is DataMigrationToolbyXTB; the compiled assembly is DataMigrationToolbyXTB.dll.

Features

• Two-environment workflow – select a Source and a Target connection independently, using the standard XrmToolBox connection picker.
• Entity picker from the Default solution – loads the entities contained in the source environment's Default solution into a dropdown.
• FetchXML-driven selection – you supply the FetchXML that decides exactly which records are migrated. A starter template is generated automatically when you pick an entity.
• GUID preserved – records keep their primary key across environments (create-with-Id / update-by-Id).
• Schema-aware writes – read-only columns (calculated/rollup, audit, and other non-writable system fields) and link-entity (AliasedValue) columns are skipped automatically so writes don't fail.
• Optional ownership – migrate ownerid (off by default).
• Optional status – migrate statecode / statuscode using SetStateRequest (a proper, supported state transition), applied after the record is written (off by default).
• N:N associations – optionally replicate many-to-many relationship links (the rows behind an associated view subgrid) on the target via Associate. You pick which relationships to include per entity.
• Robust paging – source queries are paged automatically (handles > 5000 records).
• Progress, cancel, and a full log – created / updated / failed counts plus per-record errors.

Requirements

• XrmToolBox (current release – runs on .NET Framework 4.8).
• Permissions on both environments: read on the source, create/update (and, for status migration, the relevant state-transition privileges) on the target.

Build

Open MigrateData.sln in Visual Studio 2022 and build, or from a developer prompt:

& "C:\Program Files\Microsoft Visual Studio\2022\Professional\MSBuild\Current\Bin\MSBuild.exe" `
    MigrateData.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU"

A Debug build copies DataMigrationToolbyXTB.dll (+ .pdb) into DataTransPorter\bin\Debug\Plugins\ via the post-build step.

The XrmToolBox host assemblies (XrmToolBox.Extensibility, XrmToolBox.ToolLibrary, McTools.Xrm.Connection, McTools.Xrm.Connection.WinForms) are referenced with Private=False – they are provided by the host at runtime and are not copied to the output, which avoids version conflicts.

Install into XrmToolBox (manual / local)

Copy DataMigrationToolbyXTB.dll into your XrmToolBox Plugins folder, then restart XrmToolBox:

%APPDATA%\MscrmTools\XrmToolBox\Plugins

The tool appears in the tool list as DataMigrationToolbyXTB.

Publish to the XrmToolBox Tool Library (public)

XrmToolBox's in-app Tool Library (Configuration ▸ Tool Library) is fed from NuGet.org. A package is auto-discovered and installable for everyone when it:

1. is tagged XrmToolBox,
2. ships the tool assembly under lib\<tfm>\Plugins\ (third-party dependency DLLs, if any, go in a sub-folder named exactly like the tool DLL), and
3. declares a dependency on the XrmToolBox package (the host-version marker).

This repo already contains everything for that: DataMigrationToolbyXTB.nuspec and pack-and-publish.ps1.

One-time setup

1. Create a free NuGet.org account and an API key: https://www.nuget.org/account/apikeys (scope it to Push new packages and package versions).
2. Edit DataMigrationToolbyXTB.nuspec and set:
   • <id> – must be globally unique on NuGet.org (currently DataMigrationToolbyXTB). It must not collide with another package, and the tool DLL name (DataMigrationToolbyXTB.dll) must not collide with another installed tool.
   • <authors>, <projectUrl>, <iconUrl>, <license> – your details. (<iconUrl> must point at a publicly reachable copy of images\icon.png, e.g. the raw URL in your GitHub repo.)
   • The icon (images\icon.png) and tool tile images are already wired in.

Build, pack and publish

# build + pack only (inspect artifacts\*.nupkg first)
.\pack-and-publish.ps1

# build + pack + publish to NuGet.org
.\pack-and-publish.ps1 -Push -ApiKey oy2xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

After NuGet finishes indexing (a few minutes) the tool shows up in the Tool Library; users click Install. There is no separate approval step, but the package must pass NuGet's validation and follow the three rules above.

Publishing requirements checklist

• ✅ Tagged XrmToolBox (first tag).
• ✅ Tool DLL in lib\net48\Plugins\ (the pack script + nuspec do this).
• ✅ Dependency on XrmToolBox (host-version marker).
• ✅ Assembly is not strong-named (this project isn't).
• ✅ Unique NuGet id and unique tool DLL name.
• ✅ Host assemblies (XrmToolBox.Extensibility, McTools.Xrm.Connection, Xrm SDK) are not bundled — they're referenced with Private=False and provided by the host at runtime.

Releasing updates

NuGet package versions are immutable — you cannot overwrite a published version. To update, bump <version> in the nuspec and AssemblyVersion/AssemblyFileVersion in Properties\AssemblyInfo.cs (keep them equal; date-based 1.YYYY.M.rev is the XrmToolBox convention), re-run pack-and-publish.ps1 -Push -ApiKey …, and XrmToolBox offers the update automatically.

XrmToolBox Tool Library validation checklist

How this package/tool satisfies the official Tool Library checklist:

The images are stored as source PNGs under images\ (icon.png, tool-large.png, tool-small.png); the 80×80 and 32×32 are base64-embedded in MyPlugin.cs. Regenerate by replacing the PNGs and updating the two …ImageBase64 strings.

Usage

1. 1. Select Source – choose the environment to read records from. (The connection you are already on when you open the tool is used as the source by default.)
2. 2. Select Target – choose the environment to write records to.
3. 3. Load Entities – populates the dropdown with entities from the source Default solution.
4. Pick an entity. A default FetchXML template is placed in the editor, and the entity's many-to-many relationships load into the N:N associations list.
5. 4. FetchXML – edit the FetchXML to select exactly the records you want to migrate. Use Count source records to preview how many records match.
6. (Optional) In the N:N associations list, check any relationships whose links you want replicated on the target.
7. 5. Migrate Data – confirm the prompt. Each record is created (same GUID) or updated; then, for each checked relationship, the links are replicated via Associate. The log shows a summary.

Options

FetchXML examples

Migrate every record of the chosen entity:

<fetch>
  <entity name="mash_service">
    <all-attributes />
  </entity>
</fetch>

Migrate a filtered subset:

<fetch>
  <entity name="mash_service">
    <all-attributes />
    <filter type="and">
      <condition attribute="statecode" operator="eq" value="0" />
      <condition attribute="mash_category" operator="eq" value="100000001" />
    </filter>
  </entity>
</fetch>

Use <all-attributes /> (rather than naming columns) so every migratable field is carried over. Columns that cannot be written (calculated, rollup, audit, etc.) are filtered out automatically against the target schema.

How GUID preservation works

For each source record the tool:

1. Builds a target Entity with Id = source.Id and the migratable attributes.
2. Calls Retrieve(target, id, ColumnSet(false)) to check existence.
   • Not found (ObjectDoesNotExist, 0x80040217) → Create(entity) – Dataverse honours the supplied Id, so the record is created with the same GUID.
   • Found → Update(entity).

Notes & limitations

• Reference order – references (lookups) resolve by GUID. If a record points to another record that has not been migrated yet, that write fails. Migrate parent/lookup entities first, or run the migration twice (leave Continue on error on for the first pass).
• N:N associations – only links where the migrated record is one side are replicated, and the other side must already exist on the target (otherwise that link is reported as failed). Links that already exist on the target are detected and counted as "already linked" (idempotent). Self-referential N:N is handled best-effort using the Referencing role.
• Status – statecode/statuscode are never written as part of the create/update; they are applied separately via SetStateRequest. A status reason of -1 lets the platform pick the default status for the chosen state.
• Owner / business unit – owning business unit/team/user are system-managed and are never copied; only ownerid is migrated, and only when the option is enabled.
• Counting loads the matching records to count them; for very large tables prefer a tight FetchXML filter.

Project layout