SolutionPackager 工具

项目
05/12/2023

SolutionPackager 是一种工具，可以将 Microsoft Dataverse 压缩解决方案文件可逆地分解为多个 XML 文件和其他文件。然后，您可以使用源代码管理系统轻松地管理这些文件。以下章节说明如何运行工具并使用具有托管和非托管解决方案的工具。

在何处查找 SolutionPackager 工具

SolutionPackager 工具作为 Microsoft.CrmSdk.CoreTools NuGet 数据包的一部分分发。要安装此程序，请执行以下步骤。

下载 NuGet 包。
将包文件扩展名从 .nupkg 重命名为 .zip。
提取压缩 (zip) 文件的内容。

您将在 <extracted-folder-name>/contents/bin/coretools 文件夹中找到 SolutionPackager.exe 可执行文件。从 coretools 文件夹运行程序，或将该文件夹添加到您的 PATH 中。

SolutionPackager 命令行参数

SolutionPackager 是指可以用下表中的参数调用的命令行工具。

参数	说明
/action: {Extract\|Pack}	必需。执行操作。操作可以是将解决方案 .zip 文件提取至文件夹，或者将文件夹添加至 .zip 文件中。
/zipfile: <file path>	必需。解决方案 .zip 文件的路径和名称。当解压缩时，文件必须存在并且能够读取。当压缩时，此文件可以替换。
/folder: <folder path>	必需。文件夹的路径。当解压缩时，此文件夹可以使用组件文件创建并填充。当压缩时，该文件夹必须存在并包含以前提取的组件文件。
/packagetype: {Unmanaged\|Managed\|Both}	可选。处理的压缩包的类型。默认值为非托管。此参数在大部分情况下可以忽略，因为压缩包类型可以从 .zip 文件或内部组件文件中读取。当解压缩并同时指定这两个属性时，托管和非托管解决方案 .zip 文件必须在同一个文件夹存在和处理。压缩并同时指定两个文件时，托管和非托管解决方案 .zip 文件会从一个文件夹产生。有关详细信息，请参阅本主题后面关于使用托管和非托管解决方案工作的部分。
/allowWrite:{Yes\|No}	可选。默认值为“是”。此参数只在提取时使用。当指定 /allowWrite:No 时，此工具将会执行所有操作，但是不能够编写或删除任何文件。提取操作可以在不重写或删除任何现有文件的情况下进行安全评估。
/allowDelete:{Yes\|No\|Prompt}	可选。默认值为 Prompt。此参数只在提取时使用。当指定 /allowDelete:Yes 时，将自动删除 /folder 参数未按预期指定的文件夹中的任何文件。当指定 /allowDelete:No 时，删除不会发生。当指定 /allowDelete:Prompt 时，控制台会提示用户允许或拒绝所有删除操作。如果指定 /allowWrite:No，则不会发生删除操作，即使 /allowDelete:Yes 同样被指定。
/clobber	可选。此参数只在提取时使用。当指定 /clobber 时，具有只读属性集的文件会被覆盖或删除。若没有被指定，具有只读属性集的文件不会被覆盖或删除。
/errorlevel: {Off\|Error\|Warning\|Info\|Verbose}	可选。默认值为“Info”。此参数指示可输出的日志信息的等级。
/map: <file path>	可选。 .xml 文件的路径和名称包含文件映射指令。在提取期间使用时，通常从 /folder 参数指定文件夹内部读取的文件会从映射文件指定的其他位置读取。在执行压缩操作时，匹配指令的文件不会写入。
/nologo	可选。运行时不显示横幅。
/log: <file path>	可选。记录文件的路径和名称。如果此文件已经存在，新的日志信息会被添附到这个文件里。
@ <file path>	可选。文件的路径和名称包含该工具的命令行参数。
/sourceLoc: <string>	可选。此参数生成一个模板资源文件，仅提取时有效。可能的值为想要导出语言的 `auto` 或 LCID/ISO 代码。当使用此参数时，提取给定区域设置的字符串资源作为 neutral .resx 文件。如果指定 `auto` 开关，或只是长或短格式的开关，则会使用基础区域设置或解决方案。可以使用命令的短格式：/src。
/localize	（可选）提取或合并所有字符串资源到 .resx 文件。可以使用命令的短格式：/loc。本地化选项支持 .resx 文件的共享组件。详细信息：使用 RESX Web 资源

使用 /map 命令参数

以下讨论详述对 SolutionPackager 工具使用 /map 参数。

在自动构建系统中构建的文件，如 .xap Silverlight 文件和插件组件，通常不会检查源控制。在与 SolutionPackager 工具不直接兼容的位置上，Web 资源也许已经存在于源控件中。由于包含 /map 参数，SolutionPackager 工具可以执行从其他位置读取和压缩这类文件的命令，而不是像通常那样从提取文件夹内部读取和压缩。 /map 参数必须指定包含映射指令的 XML 文件的名称和路径。这些指令指示 SolutionPackager 通过文件的名称和路径来匹配文件，并指示查找匹配文件的备用位置。此信息同样适用于所有指令。

可以列出多个指令，包括匹配相同文件的指令。文件中先列出的指令优先于后来列出的指令。
如果一文件与任一指令匹配，则至少可以在一个可选择位置找到该文件。如果未找到其他匹配文件，SolutionPackager 将发出错误。
文件夹和文件路径可以是绝对或相对的。相对路径总是从 /folder 参数指定的文件夹中评估。
可以使用 %variable% 语法指定环境变量。
文件夹通配符“**”可用于表示“在任何子文件夹中”。它只能用作路径的最后一部分，例如：“c:\folderA\**”。
文件名称通配符只能以“*.ext”或“*.*”形式使用。不支持其他格式。

此处描述了三种指令映射类型，以及显示如何使用它们的示例。

文件夹映射

以下信息提供有关文件夹映射的详细信息。

Xml 格式

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

描述

匹配“folderA”的文件路径将被转换为“folderB”。

每一个子文件夹的层次结构必须准确匹配。
不支持文件夹通配符。

不可以指定任何文件名。

示例

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

文件到文件映射

以下信息提供有关文件到文件映射的更多详细信息。

Xml 格式

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

描述

匹配 map 参数的任意文件将从 to 参数中指定的名称和路径读取。

对于 map 参数：

必须指定一个文件名。路径是可选的。如果未指定路径，任意文件夹中的文件都可以匹配。
不支持文件名通配符。
支持文件夹通配符。

对于 to 参数：
必须指定文件名和路径。
此文件名可能与 map 参数中的名称不同。
不支持文件名通配符。
支持文件夹通配符。

示例

  <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" />

请注意，在上面的 NuGet 包示例中，如果指定位置中已存在 cr886_PluginPackageTest.nupkg，则系统不会覆盖该文件。

文件到路径映射

下面提供有关文件到路径映射的详细信息。

Xml 格式

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

说明

匹配 map 参数的任意文件都可从 to 参数中指定的路径读取。

对于 map 参数：

必须指定一个文件名。路径是可选的。如果未指定路径，任意文件夹中的文件都可以匹配。
不支持文件名通配符。
支持文件夹通配符。

对于 to 参数：

必须指定路径。
支持文件夹通配符。
不得指定文件名。

示例

  <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" />

映射示例

以下 XML 示例代码显示完整的映射文件，该文件能够使 SolutionPackager 工具读取任意网络资源以及名为 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 sub-folders -->  
       <FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />  
       <FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />  
</Mapping>

托管和非托管解决方案

一个 Dataverse 压缩解决方案 (.zip) 文件可以按照此处所示的两种类型导出。

托管解决方案
完整解决方案做好导入组织的准备。组件一旦导入不能再添加或删除，但组件可以选择进一步自定义。建议在完成此解决方案的开发后使用。

非托管解决方案
开放式解决方案对于可以添加、删除或修改什么没有限制。建议在解决方案开发期间使用。

无论是托管还是非托管类型，压缩解决方案文件的格式都不同。 SolutionPackager 能够处理任何类型的压缩解决方案文件。然而，此工具无法将一种类型转换为另一种类型。唯一可以将解决方案文件转换成不同类型的方式，例如从非托管转换成托管，是将非托管的解决方案 .zip 文件导入到 Dataverse 服务器，然后将其输出为托管解决方案。

通过 /PackageType:Both 参数，SolutionPackager 能够将托管和非托管的解决方案 .zip 文件作为组合处理。要执行此操作，每个类型的解决方案需要输出两次，并按如下所示命名 .zip 文件。


非托管 .zip 文件：AnyName.zip	托管 .zip 文件：AnyName_managed.zip

此工具将同一个文件夹下托管 zip 文件看做非托管文件，并将两个文件提取至单个文件夹下，同时保存托管和非托管组件的不同之处。

在解决方案作为托管和非托管文件被提取之后，可以从同一文件夹压缩两个文件或分别压缩每个类型，使用 /PackageType 参数指定创建哪个类型。当两个文件同时被指定时，可以使用上述命名惯例生产两个 .zip 文件。当从一双重托管和非托管文件夹打包时，如果这个 /PackageType 参数丢失，则默认生成单个非托管 .zip 文件。

疑难解答

如果使用 Visual Studio 编辑解决方案打包器创建的资源文件，可能在重新打包时收到如下消息：“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.”这是由于 Visual Studio 将资源文件的元数据标记替换为数据标记导致的。

解决办法

在您常用的文本编辑器中打开该资源文件，并找到和更新以下标记：

<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">

将节点名从 <data> 更改为 <metadata>。

在本例中，字符串如下：
```
<data name="Source LCID" xml:space="preserve">  
  <value>1033</value>  
</data>  
```
更改为：
```
<metadata name="Source LCID" xml:space="preserve">  
  <value>1033</value>  
</metadata>  
```
这允许解决方案包读取和导入资源文件。只有在使用 Visual Studio 编辑器时才观察到此问题。

另请参阅

使用具有解决方案文件的源代码控制

 解决方案概念

通过

SolutionPackager 工具

在何处查找 SolutionPackager 工具

SolutionPackager 命令行参数

使用 /map 命令参数

文件夹映射

文件到文件映射

文件到路径映射

映射示例

托管和非托管解决方案

疑难解答​​

解决办法

另请参阅

其他资源

疑难解答