Using Map file in ALM

To ensure a healthy code state, a developer needs to ensure that every part of the implementation that is deployed to downstream environments is healthy. Within the Power Platform we can, for example, use map files in ALM. This blog post will explain what map files are and how we can use it.

Background

When it comes to development in general, binaries should not be stored in the repository. This does also apply to Power Platform development as a best practice. In addition, in Power Platform ALM everything evolves around environments and solutions instead of repositories. Which makes this harder to follow since, depending on whether we follow an environment-centric or source code-centric approach, we might create our solution from an environment instead of a repository.

During implementation, developers usually deploy versions of pro-code components (like Plugins or Webresources) to the development environment, which are not ready to be deployed to downstream environments.

What should be deployed to downstream environments should always be in a state where it is working as expected and has at least been tested by unit tests and the developer. In a better world, we would also have automated integration test and UI tests.

This means in a source code-centric approach, we would like to make sure that what we save in our repository (and therefore from what we create our solution) has no binaries, and the binaries will be created “on the fly” in our pipeline. Whereas in an environment-centric approach, the version in our development environment is always the correct one when doing our export.

Since the source code-centric approach is the recommended one this blog post will focus on the solution to our problem for this approach.

There are different approaches to make this possible. For example

• Map files – Can be used in a source code-centric approach
• Deploying the latest version to the development environment before creating the export – can be used in an environment-centric approach

This blog post will explain how the map file approach works.

Map files

Let’s talk a bit more about map files. Those are XML files that define which Plugin DLLs and Webresources are found in a solution and where they are saved on the local disc.

When presented to the Platform, DLLs and Webresources in a solution will be suppressed.

Map files aren’t a new thing. They are usable since a long time in the solution packager. But there are other ways of using them as well.

We can present map files in the unpack and pack step of the Power Platform Build tools.

The Documentation of the mentioned steps do not describe the map file usage. The Power Platform Build Tools do use the PAC CLI. There, we can see that the unpack and pack steps of the CLI have the option to present map files. When you configure the unpack and pack steps of the Build Tools, the ADO UI will also show the option to use map files.

Another command where we can use map files is the clone command of PAC. Clone is a more recent addition to the options we have for a healthy ALM.

With a clone, a developer can create a copy of a solution to his/her local disc. The generated copy can work with a normal msbuild command. This allows us to work with Power Platform in a more pro-dev way.

This can in general, be used in a pipeline instead of unpacking as well. More to that in a later post.

Implement

Now that we know what map files are, let’s see how we create and use one.

When it comes to creating the map files we have three approaches at hand.

• Folder mapping – With this approach, we can map a complete folder. This is often used for Webresources
• File to File mapping – Here we can map one file to another (source to target). This is often used for Plugin DLLs
• File to Path mapping – A specific file will be searched in the mapped folder.

Create a map file

Let’s assume we have one Plugin Assembly, DemoPlugin.dll and the path in our repository would look like the following when unpacked

PowerPlatformSolutionsDemoSolutionPluginAssembliesDemoPlugin.dll

The paths depend on your project structure and whether you use Azure DevOps or GitHub.

The following is an example xml file which works for the demo setup in ADO

<?xml version="1.0" encoding="utf-8"?>

<Mapping>

    <FileToFile map="D:a1sPowerPlatformSolutionsDemoSolutionPluginAssembliesDemoPlugin.dll " to="D:a1sdevelopmentBack-endPluginsDemoPluginbinreleaseDemoPlugin.dll " />

</Mapping>

This file will map our DemoPlugin.dll from the solution to the DLL on the local machine. When used in a pipeline that means where the agent would access it after building our solution and therefore generating all DLL files (and Webresources).

I usually store a map file per solution in my repository.

Use a map file

Now that we have created the map file, we must use it. As mentioned this can be done in different steps in a pipeline.

If it should be used in either the unpack or pack step we only have to add another row of configuration to the yaml description of those steps.

MapFile: ' $(build.sourcesdirectory)PowerPlatformSolutionsMappingsDemoSolution.xml'

This path also does depend on the setup of your pipeline and repository.

Conclusion

Initially, it might be a bit confusing to wrap your head around map files. But they can be a great tool to improve your application Lifecycle Management.

When you have used it the first time it does make a lot of sense and isn’t hard to implement there after.

I hope this blog post was useful. Please feel free to give me Feedback and don’t hesitate to contact me in case you have any question.

The post Using Map file in ALM appeared first on Benedikt's Power Platform Blog.

Original Post https://benediktbergmann.eu/2025/03/31/using-map-file-in-alm/