Rajeev Pentyala – Microsoft Power Platform

Microsoft Power Platform CLI is a developer Command Line Interface, that empowers developers and ISVs to perform various operations related to environment lifecycle, authentication, and work with Dataverse environments, solution packages, portals, code components, and so on.

In this article lets learn how to use Pack and Unpack Solution Commands with map xml file.

Getting started with CLI:

• There are 2 ways to install and use CLI.
  • Standalone Power Platform CLI :
    • Download and install Microsoft Power Platform CLI
    • Standalone CLI is supported only on Windows 10 and Windows 11.
  • Using Power Platform Tools for Visual Studio Code:
    • Follow steps specified here.
    • Power Platform Tools for Visual Studio Code is available on Windows 10, Windows 11, Linux, and MacOS.

Understanding Unpack and Pack commands:

• Solutions are the mechanism for implementing application lifecycle management (ALM).
• Its imperative to version control the Solution components to platforms such as Azure DevOps, Git Hub to maintain healthy ALM.
• With the help of Unpack and Pack commands we can commit the Solution Components which enables version control.

Using Unpack command:

• Lets you unpack solution zip files after they’ve been exported to the filesystem.
• First export the solution to your machine.
  • In my case, I have ‘almplugins_1_0_0_0‘ solution exported and placed in ‘D’ drive.

• To use ‘Unpack’, open the Command Prompt in ‘Admin Mode’ and run following command.

pac solution unpack -z D:\Practice\CLI\almplugins_1_0_0_0.zip -f D:\Practice\CLI\almpluginsunpacked.

• Once the command executed successfully, Solution components unpack to “D:\Practice\CLI\almpluginsunpacked” path as specified in unpack command.
  • Note: My ‘almplugins_1_0_0_0.zip‘ solution had only a ‘Plug-in assembly’ and ‘Plugin Steps’ hence you would see only those designated folders.
  • If the solution contains other components like Entities, Security Roles, Flows, etc. other relevant folders gets generated.

Using pack command:

• Lets you pack files on a filesystem into a solution zip file.
• Now, lets pack the Solution Components from the almpluginsunpacked folder using following pack command.

pac solution pack -z D:\Practice\CLI\almpluginpacked.zip -f D:\Practice\CLI\almpluginsunpacked.

• Once the command executed, you would find a new zip folder with name (i.e.,almpluginpacked.zip), specified in ‘pack’ command.

Now that you got some knowledge on usage of unpack and pack. Now lets use them with map xml file.

Why we need map xml:

• Files that are built in an automated build system, such as plug-in assemblies, are typically not checked into source control.
• If you open the almpluginsunpacked folder generated by unpack, there will be .dlls which are not supposed to be presented.

• Also, while packing the solution components using ‘pack’, you would want the latest .dlls from your Plugin VS project to be packed.
• map xml helps in above 2 scenarios. Lets see the usage of map xml in next section.

• map xml have Folder mapping and File To file mapping options. In this article, I will go with ‘File To File’ mapping. Sample map xml looks as below.

<?xml version="1.0" encoding="utf-8"?>
<Mapping>
    <FileToFile map="PFESamplePlugins.dll" to="..\..\src\\Plugins\bin\**\PFE.Sample.Plugins.dll" />

    <FileToPath map="WebResources\*.*" to="..\..\src\WebResources\dist\**" />
    <FileToPath map="WebResources\**\*.*" to="..\..\src\WebResources\dist\**" />
</Mapping>

unpack command with map xml:

• As my almplugins_1_0_0_0 solution has 2 Plug-in assemblies, I got following 2 folders by executing unpack command.

• If I go deep in to folders, there are alm-plugins2.dll and almplugins.dll as they were unpacked from almplugins_1_0_0_0 solution.

• Lets run unpack again with map.xml.

Prepare map xml

• My Plug-in projects folder structure is as follows.

• Path of my alm-plugins2.dll will be C:\Users\rajeevpe\Source\repos\alm-plugins-v2\alm-plugins2\bin\Release\alm-plugins2.dll
• Path of my alm.plugins.dll will be C:\Users\rajeevpe\Source\repos\alm-plugins-v2\alm-plugins\bin\Release\alm.plugins.dll
• The map.xml structure will be as below

<?xml version="1.0" encoding="utf-8"?>
<Mapping>
    <FileToFile map="D:\Practice\CLI\almpluginsunpacked\PluginAssemblies\**\alm-plugins2.dll" to="C:\Users\rajeevpe\Source\repos\alm-plugins-v2\alm-plugins2\bin\Release\alm-plugins2.dll" />
    <FileToFile map="D:\Practice\CLI\almpluginsunpacked\PluginAssemblies\**\almplugins.dll" to="C:\Users\rajeevpe\Source\repos\alm-plugins-v2\alm-plugins\bin\Release\alm.plugins.dll" />    
</Mapping>

• Save the map xml file with above content and execute following unpack command.

pac solution unpack -z D:\Practice\CLI\almplugins_1_0_0_0.zip -f D:\Practice\CLI\almpluginsunpacked\. -m D:\Practice\CLI\map.xml

• This time, map file was considered by unpack command and skipped the generation of dlls in unpack folder location.

pack command with map xml:

As we have seen, unpack with map file would not generate dlls in to unpacked folder. The objective of map file during pack is to consider the latest .dlls from your Plugin VS project location.

Since we already prepared map xml file, we can refer the same in pack command as below.

pac solution pack -z D:\Practice\CLI\almplugins_1_0_0_0.zip -f D:\Practice\CLI\almpluginsunpacked\. -m D:\Practice\CLI\map.xml

• If you notice, .dlls were mapped (i.e., copied) from plug-in VS projects location and packed in to a zip folder which can imported to target environments.

Hope you gained some knowledge on usage of pack and unpack commands using map xml file. In this article I only considered Plug-ins but map file can be used with Web resources as well.

Following articles provides more details.

• CLI pac solution command
• Using map file

Note:

• Azure DevOps pipeline’s ‘Power Platform Pack Solution’ and ‘Power Platform UnPack Solution’ tasks uses PAC CLI and at the time of writing this article, both ‘Power Platform Pack Solution’ and ‘Power Platform UnPack Solution’ tasks does not support map xml.

🙂