Dataverse Configuration Migration Tool

This repository contains a custom .NET CLI tool designed to export and import configuration data into Microsoft Dataverse environments. It streamlines the migration of configuration data, supports schema validation, and offers extensibility for advanced scenarios.

Download latest release

Get latest version of the tool built on this release

Note

If you want to use the built version of the tool , appsettings.Production.json will need to be setup manually with your azure service principal credentials. Quick Guide to create an azure service principal

Why ❓

Configuration Migration Tool and the PowerPlatform Cli Tool (pac data import verb) seem to have it's limitations when automating in ci/cd. Also, these two only works on a windows machine.
This new tool enables you to:

• customize/extend the tool to your needs
• use in CD pipeline easily
• runs on windows and linux

⭐Features⭐

✔️ Import configuration data into Dataverse
✔️ Export configuration data from Dataverse
✔️ Schema validation and rule-based checks
✔️ Support for special characters and self-hierarchy imports
✔️ Extensible for custom validation and reporting
✔️ Many to Many Relationships supported
✔️ Owner,Team And Business Unit field is now supported. If by Unique Id is not found in target env, it matches by name otherwise it ignores the field. Caching is used to avoid unnecessary calls to dataverse.
✔️ Supports schemas and data files generated from :

• PowerPlatform CLI Export
• Configuration Migration tool

❌Field types not supported:

• MultiSelectOptionsets
• Image
• File

Getting Started

Prerequisites

• .NET 8.0 SDK
• Access to a Microsoft Dataverse environment

🛠️Building the Tool🛠️

1. Clone the repository:

   git clone https://github.com/dotnetprog/dataverse-configuration-migration-tool.git
   cd dataverse-configuration-migration-tool/src/Dataverse.ConfigurationMigrationTool/Dataverse.ConfigurationMigrationTool.Console

2. Build the project:

   dotnet build

Usage

Before running the tool, set your clientId, clientSecret and url securely using dotnet user-secrets:

cd src/Dataverse.ConfigurationMigrationTool/Dataverse.ConfigurationMigrationTool.Console
dotnet user-secrets set "Dataverse:ClientId" "<your-client-id>"
dotnet user-secrets set "Dataverse:ClientSecret" "<your-client-secret>"
dotnet user-secrets set "Dataverse:Url" "<your-env-url>"

Run the CLI tool with the required arguments (no need to pass clientId or clientSecret on the command line):

example

dotnet run --environment DOTNET_ENVIRONMENT=Development --project Dataverse.ConfigurationMigrationTool.Console -- import --data "path/to/data.xml" --schema "path/to/schema.xml"

💻 Command Line Arguments 💻

Verb: import

• --data : Path to the data xml file, you can use export-data command or the microsoft tool (see last section).
• --schema : Path to the schema XML file

Verb: export-data

• --schema : Path to the schema XML file
• --output : output file path to save the exported data. This file can be used for the import command.

🤝 Contributing 🤝

Contributions are welcome! To get started:

1. Fork the repository and create a new branch for your feature or bugfix.
2. Make your changes and add tests as appropriate.
3. Ensure all tests pass:

   dotnet test ../Console.Tests/Dataverse.ConfigurationMigrationTool.Console.Tests.csproj

4. Submit a pull request with a clear description of your changes.

Please review open issues and the todo list below for ideas on what to contribute.

🚀Continuous Delivery🚀

This repository includes example GitHub Actions workflows for building, testing, and deploying the tool:

• main-pipeline.yml: Handles build, test, artifact publishing, and triggers deployment workflows.
• cd-pipeline.yml: Example deployment workflow for importing configuration data into a Dataverse environment using published artifacts and environment secrets.

You can use these workflows as a starting point for your own CI/CD automation. See the workflow files for details on environment variables, secrets, and deployment steps.

</> Generating Schema and Data Files </>

To use the import or export-data command, you need a schema file and/or a data file. These can be generated from your Dataverse environment using the official Configuration Migration tool. For detailed instructions, refer to the Microsoft documentation:

• Create a schema and export configuration data

This guide explains how to:

• Create a schema file that defines the data to export
• Export configuration data from your environment

Note

the data_schema.xml and data.xml will be inside the exported zip. You need to extract those files and use them to import command as described above.