A practical guide to relative paths on solution mapping files

Every time I start a new Dataverse project, I find myself struggling to remember the exact syntax and structure of mapping files. Yet, these files are absolutely essential for proper Application Lifecycle Management (ALM). Without them, you'll end up with duplicated source code in your repository, broken builds, and a messy development workflow.

So I'm writing this as a personal reference—a memento I can return to whenever I need to set up mapping files correctly. If you're reading this and facing the same challenge, hopefully it helps you too.

🏗️ Project Structure Overview

The typical folder organization I use for my Dataverse projects is the following:

📂 ... other folders such as .github, .vscode, docs ...
📂 solutions
   📂 master
      📂 src
         📂 ...solution components folders...
      📄 map.xml
      📄 master.cdsproj
📂 src
   📂 Plugins
      📄 ...
   📂 WebResources
      📂 ava_
         📂 images
         📂 pages
         📂 scripts
📂 ... other folders such as test ...

This structure separates concerns effectively:

• solutions/: Contains Dataverse solution definitions and metadata
• src/: Houses source code for plugins, web resources, and other custom components

📦 Understanding Solution Organization

The solutions folder contains a subfolder for each Dataverse solution I use in my project (can be 1 called master for simple projects, or more than one for moderately complex projects).

Each solution folder typically contains:

• src/: Unpacked solution components (entities, forms, views, etc.)
• map.xml: File mapping configuration (the focus of this post)
• {solutionname}.cdsproj: MSBuild project file for the solution

🗺️ The Critical Role of Map.xml Files

For each solution containing WebResources or Plugin Packages/Plugin Assemblies, it is a best practice to create a map.xml file that can be used:

• while running pac solution sync, to avoid storing in the repo twice the source code of WebResources, and the compiled .dll (or .nupkg) of a Plugin Assembly / Plugin Package
• while running dotnet build to rebuild the solution, to instruct the solution package on where to retrieve the missing WebResources/Plugin Assemblies/Plugin Packages

🤔 Why Use Mapping Files?

Mapping files solve several critical problems in Dataverse development:

1. Avoid Code Duplication: Without mapping, your repository would contain both source files (in src/) and processed files (in solutions/master/src/WebResources/), leading to redundancy and potential conflicts.

2. Streamline Build Process: During dotnet build, the system knows exactly where to find source files to include in the solution package.

3. Maintain Clean Repository: Source control focuses on actual source code rather than generated artifacts.

4. Enable Automated Builds: CI/CD pipelines can reliably build solutions without manual intervention.

🔍 Anatomy of a Web Resources Map File

A typical map file for web resources looks like this:

<?xml version="1.0" encoding="utf-8"?>
<Mapping>
    <!-- Map the web resources folder relative to the solutions\master\obj\debug\metadata\src\WebResources folder -->
    <Folder map="WebResources\ava_" to="..\..\..\..\..\src\WebResources\ava_" />
</Mapping>

🔢 Understanding the Five Parent Directory Navigation (../)

The to part of the different types of mappings you can apply to a map.xml file is taken into consideration only during the build process.

dotnet build tries to rebuild the solution recreating all content of the src folder into the obj\Debug\Metadata folder.

This means that, in the mapping file, you must consider yourself to be within that folder when the actual mapping starts.

%base%\solutions\master\obj\Metadata\WebResources
⬇️ cd .. (1)
%base%\solutions\master\obj\Metadata
⬇️ cd .. (2)
%base%\solutions\master\obj
⬇️ cd .. (3)
%base%\solutions\master
⬇️ cd .. (4)
%base%\solutions
⬇️ cd .. (5)
%base%
⬇️ cd src\WebResources
%base%\src\WebResources

💭 Final Thoughts

There you have it—my personal cheat sheet for Dataverse mapping files. I hope that by writing this down, I'll finally stop second-guessing myself every time I start a new project. Those five ../ always trip me up, but now I have a clear explanation of why they're needed and how they work.

The key thing I want to remember for next time: mapping files aren't just nice-to-have—they're absolutely critical for proper ALM. Without them, you're setting yourself up for repository chaos and build headaches down the road.

If future me (or anyone else) is reading this while staring at a broken build or wondering why pac solution sync isn't working, just remember: check your map.xml file, count those parent directory navigations, and make sure your source paths actually exist. Trust me, it's usually one of those three things.

Comments

[Piyush Parate]

Hi Riccardo,

That was a helpful note for me too — you're absolutely right. The map.xml file often causes confusion, especially with the use of "../".

Thanks for comprehensive note :-)

I have one question about map.xml plugin assemblies. Suppose our TARGET environment has a solution with a plugin assembly containing just one plugin. In DEV, we add a second plugin to the same assembly. If we move the updated solution(containing plugin assembly) through the pipeline, will the second plugin be deployed to TARGET?

I recall facing an issue where the new plugin didn’t move. If you've seen this before, do you know what might cause it?

[Riccardo Gregori]

Hi,
thanks for your comment!
The plugin step is a solution component by itself, must be included in the solution in order to be deployed to the target environment.