SolutionPackager tool

SolutionPackager is a tool that can reversibly decompose a Microsoft Dataverse compressed solution file into multiple XML files and other files. You can then easily manage these files by using a source control system. The following sections show you how to run the tool and how to use the tool with managed and unmanaged solutions.

Where to find the SolutionPackager tool

The SolutionPackager tool is distributed as part of the Microsoft.CrmSdk.CoreTools NuGet package. To install the program, follow these steps.

1. Download the NuGet package.
2. Rename the package filename extension from .nupkg to .zip.
3. Extract the contents of the compressed (zip) file.

Find the SolutionPackager.exe executable in the <extracted-folder-name>/contents/bin/coretools folder. Run the program from the coretools folder or add that folder to your PATH.

SolutionPackager command-line arguments

SolutionPackager is a command-line tool that can be invoked with the parameters identified in the following table.

Source control file formats

SolutionPackager supports two folder layouts when extracting and packing solutions.

XML format (legacy)

The original format. Solution metadata is stored in Other\Solution.xml and Other\Customizations.xml, and all component files are extracted into a flat folder hierarchy alongside those files. This format is the default format when extracting a .zip file without more configuration.

YAML source control format

Introduced alongside Dataverse Git integration, this format stores solution metadata as YAML files distributed across a structured folder hierarchy. It's the format written when you commit solutions using native Git integration in Power Apps.

Advantages over XML format

• Produces cleaner, more readable per-component diffs in source control
• Supports multiple solutions in a single repository folder
• Canvas app .msapp files and modern flows are only supported in this format
• Plug-in type name remapping is enabled by default

Required folder structure

<rootFolder>/
├── solutions/
│   └── <SolutionUniqueName>/
│       ├── solution.yml              (solution metadata)
│       ├── solutioncomponents.yml    (paths to all component files)
│       ├── rootcomponents.yml        (root-level components)
│       └── missingdependencies.yml   (dependency info)
├── publishers/
│   └── <PublisherUniqueName>/
│       └── publisher.yml             (publisher definition)
├── entities/                         (entity components, if present)
├── workflows/                        (classic workflows, if present)
├── modernflows/                      (Power Automate cloud flows, if present)
├── canvasapps/                       (canvas app .msapp files, if present)
└── [other component folders]/

More information: Solution YAML source control format reference

Format auto-detection rules

Packing a YAML format folder

The following command packs a YAML format folder.

SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo

Packing from a multi-solution folder

The following command packs a specified solution in a multi-solution folder.

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

Use the /map command argument

The following discussion details the use of the /map argument to the SolutionPackager tool.

Files that are built in an automated build system, such as .xap Silverlight files and plug-in assemblies, are typically not checked into source control. Web resources may already be present in source control in locations that aren't directly compatible with the SolutionPackager tool. By including the /map parameter, the SolutionPackager tool can be directed to read and package such files from alternate locations and not from inside the Extract folder as it would typically be done. The /map parameter must specify the name and path to an XML file containing mapping directives. Those directives instruct the SolutionPackager to match files by their name and path, and indicate the alternate location to find the matched file. The following information applies to all directives equally.

• Multiple directives may be listed including those directives that match identical files. Directives listed early in the file take precedence over directives listed later.

• If a file is matched to any directive, it must be found in at least one alternative location. If no matching alternatives are found, the SolutionPackager issues an error.

• Folder and file paths may be absolute or relative. Relative paths are always evaluated from the folder specified by the /folder parameter.

• Environment variables may be specified by using a %variable% syntax.

• A folder wildcard "**" may be used to mean "in any subfolder". It can only be used as the final part of a path, for example: "c:\folderA\**".

• File name wildcards may be used only in the forms "*.ext" or "*.*". No other pattern is supported.

  The three types of directives mappings are described here, along with an example that shows you how to use them.

Folder mapping

The following information provides detailed information on folder mapping.

Xml Format

<Folder map="folderA" to="folderB" />

Description

File paths that match "folderA" are switched to "folderB".

• The hierarchy of subfolders under each must exactly match.

• Folder wildcards aren't supported.

• No file names may be specified.

  Examples

  <Folder map="folderA" to="folderB" />  
  <Folder map="folderA\folderB" to="..\..\folderC\" />  
  <Folder map="WebResources\subFolder" to="%base%\WebResources" />  
  

File To file mapping

The following information provides more details on file-to-file mapping.

Xml Format

<FileToFile map="path\filename.ext" to="path\filename.ext" />

Description

Any file matching the map parameter is read from the name and path specified in the to parameter.

For the map parameter:

• A file name must be specified. The path is optional. If no path is specified, files from any folder may be matched.

• File name wildcards aren't supported.

• The folder wildcard is supported.

  For the to parameter:

• A file name and path must be specified.

• The file name may differ from the name in the map parameter.

• File name wildcards aren't supported.

• The folder wildcard is supported.

Examples

  <FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />  
  <FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />  
  <FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />  

  <FileToFile
    map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
    to="myplg\bin\Debug\myplg.1.0.0.nupkg" /> 

In the above NuGet package example, cr886_PluginPackageTest.nupkg is not overwritten if the file already exists in the specified location.

File to path mapping

The following provides detailed information on file-to-path mapping.

Xml Format

<FileToPath map="path\filename.ext" to="path" />

Description

Any file matching the map parameter is read from the path specified in the to parameter.

For the map parameter:

• A file name must be specified. The path is optional. If no path is specified, files from any folder may be matched.

• File name wildcards are supported.

• The folder wildcard is supported.

For the to parameter:

• A path must be specified.

• The folder wildcard is supported.

• A file name must not be specified.

  Examples

  <FileToPath map="assembly.dll" to="c:\path\folder" />  
  <FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />  
  <FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />  
  <FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />  

Example mapping

The following XML code sample shows a complete mapping file that enables the SolutionPackager tool to read any web resource and the two default generated assemblies from a Developer Toolkit project named CRMDevTookitSample.

<?xml version="1.0" encoding="utf-8"?>  
<Mapping>  
       <!-- Match specific named files to an alternate folder -->  
       <FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />  
       <FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />  
       <!-- Match any file in and under WebResources to an alternate set of subfolders -->  
       <FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />  
       <FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />  
</Mapping>  

Managed and unmanaged solutions

A Dataverse compressed solution (.zip) file can be exported in one of two types as shown here.

Managed solution
A completed solution ready to be imported into an organization. Once imported, components can't be added or removed, although they can optionally allow further customization. This is recommended when development of the solution is complete.

Unmanaged solution
An open solution with no restrictions on what can be added, removed, or modified. This is recommended during development of a solution.

The format of a compressed solution file will be different based on its type, either managed or unmanaged. The SolutionPackager can process compressed solution files of either type. However, the tool can't convert one type to another. The only way to convert solution files to a different type, for example from unmanaged to managed, is by importing the unmanaged solution .zip file into a Dataverse server and then exporting the solution as a managed solution.

The SolutionPackager can process unmanaged and managed solution .zip files as a combined set via the /PackageType:Both parameter. To perform this operation, it is necessary to export your solution twice as each type, naming the .zip files as follows.

The tool will assume the presence of the managed zip file in the same folder as the unmanaged file and extract both files into a single folder preserving the differences where managed and unmanaged components exist.

After a solution has been extracted as both unmanaged and managed, it is possible from that single folder to pack both, or each type individually, using the /PackageType parameter to specify which type to create. When specifying both files, two .zip files will be produced using the naming convention as above. If the /PackageType parameter is missing when packing from a dual managed and unmanaged folder, the default is to produce a single unmanaged .zip file.

Troubleshooting

Message displayed when using Visual Studio to edit resource files

If you use Visual Studio to edit resource fsiles created by the solution packager, you may receive a message when you repack similar to this: "Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process." This happens because Visual Studio replaces the resource file's metadata tags with data tags.

Workaround

1. Open the resource file in your favorite text editor and locate and update the following tags:

   <data name="Source LCID" xml:space="preserve">  
   <data name="Source file" xml:space="preserve">  
   <data name="Source package type" xml:space="preserve">  
   <data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">  
   
   

2. Change the node name from <data> to <metadata>.

   For example, this string:

   <data name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </data>  
   
   

   Changes to:

   <metadata name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </metadata>  
   
   

   This allows the solution packager to read and import the resource file. This problem has only been observed when using the Visual Studio Resource editor.

Error: "Cannot find required file …\Other\Customizations.xml" with a YAML folder

This error appears when you run SolutionPackager (or pac solution pack) against a folder that contains YAML files such as solution.yml, but those files are placed at the root of the folder rather than inside the required solutions/<SolutionUniqueName>/ subfolder.

Cause: The tool detects the YAML source control format by looking for a solutions/ subfolder containing *solution.yml files. When that directory is absent, the tool silently falls back to the XML (legacy) format and expects Other\Customizations.xml. The resulting error message refers to an XML file and doesn't mention YAML, which is misleading.

Fix: Reorganize the folder so that the YAML manifest files are under the correct paths:

<rootFolder>/
  solutions/<YourSolutionUniqueName>/   ← move solution.yml here
    solution.yml
    solutioncomponents.yml
    rootcomponents.yml
    missingdependencies.yml
  publishers/<YourPublisherUniqueName>/
    publisher.yml

If you obtained the folder from a Git integration commit or pac solution clone, the folder structure should already be correct. A folder that only contains the top-level YAML files without the solutions/ subdirectory represents an incomplete extract and can't be packed directly.

Warning: component declared in rootcomponents.yml has no source files

This warning appears when a component, such as a canvas app, is listed in rootcomponents.yml but no corresponding source files exist in the expected component folder (for example, canvasapps/<schema-name>/).

Effect: The tool still succeeds (exit code 0) and produces a valid .zip file, but the declared component is omitted from the packaged solution.

Cause: The folder was produced by a partial extract, or the component's source files weren't included in the repository. For example, only the solution manifest files were committed and not the canvas app itself.

Fix: Ensure all components declared in rootcomponents.yml have corresponding source files present in the folder. For canvas apps, the .msapp file must exist under canvasapps/<schema-name>/. If any files are missing, re-export the full solution from Dataverse and unpack it again, or use pac solution clone to obtain a complete extract.

See also

• Use Source Control with Solution Files
• sSolution concepts