DEV Community

Cover image for A practical guide to relative paths on solution mapping files
Riccardo Gregori
Riccardo Gregori

Posted on • Edited on

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 ...
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

πŸ”’ 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.

Sample

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
Enter fullscreen mode Exit fullscreen mode

πŸ’­ 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.

Top comments (2)

Collapse
 
piyush_parate_96b73559d21 profile image
Piyush Parate • Edited

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?

Collapse
 
_neronotte profile image
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.