使用 SolutionPackager 工具压缩和提取解决方案文件

此主题适用于 Dynamics 365 Customer Engagement (on-premises)。 有关此主题的 Power Apps 版本，请参阅： SolutionPackager 工具

SolutionPackager 是一种工具，它可以可逆地将 Dynamics 365 Customer Engagement （on-premises） 压缩解决方案文件分解为多个 XML 文件和其他文件，以便源代码管理系统可以轻松管理这些文件。 以下部分介绍如何运行该工具，以及如何将该工具用于托管和非托管解决方案。

在何处查找 SolutionPackager 工具

SolutionPackager 工具作为 Microsoft.CrmSdk.CoreTools NuGet 包的一部分分发。 有关如何下载它的信息，请参阅 Dataverse 开发工具 。

SolutionPackager 命令行参数

SolutionPackager 是一个命令行工具，可以使用下表中标识的参数进行调用。

论点	DESCRIPTION
/动作：{提取|打包}	必填。 执行操作。 该操作可以是将解决方案 .zip 文件提取到文件夹，也可以将文件夹打包为 .zip 文件。
/zipfile： <文件路径>	必填。 解决方案 .zip 文件的路径和名称。 提取时，文件必须存在并将从中读取。 打包时，文件将被替换。
/folder： <文件夹路径>	必填。 文件夹路径。 提取时，将创建此文件夹并填充组件文件。 打包时，此文件夹必须已经存在，并且包含以前提取的组件文件。
/packagetype: {Unmanaged|Managed|Both}	可选。 要处理的包的类型。 默认值为 Unmanaged。 在大多数情况下，可以省略此参数，因为可以从 .zip 文件或组件文件内部读取包类型。 当解压缩并同时指定这两个属性时，托管和非托管解决方案 .zip 文件必须在同一个文件夹存在和处理。 如果指定了 packing 和 Both，则托管和非托管解决方案 .zip 文件将从一个文件夹生成。 有关更多信息，请参阅本主题后面的有关使用托管和非托管解决方案的部分。
/allowWrite:{Yes|No}	可选。 默认值为“是”。 此参数仅在提取期间使用。 指定 /allowWrite：No 时，该工具将执行所有作，但会阻止写入或删除任何文件。 提取操作可以在不重写或删除任何现有文件的情况下进行安全评估。
/allowDelete:{Yes|No|Prompt}	可选。 默认值为 Prompt。 此参数仅在提取期间使用。 指定 /allowDelete：Yes 时，将自动删除 /folder 参数指定的文件夹中存在的任何意外文件。 指定 /allowDelete：No 时，不会发生任何删除。 指定 /allowDelete：Prompt 后，系统会通过控制台提示用户允许或拒绝所有删除作。 请注意，如果指定了 /allowWrite：No，则即使还指定了 /allowDelete：Yes，也不会发生删除。
/clobber	可选。 此参数仅在提取期间使用。 指定 /clobber 时，将覆盖或删除设置了 read-only 属性的文件。 如果未指定，则不会覆盖或删除具有 read-only 属性的文件。
/errorlevel: {Off|Error|Warning|Info|Verbose}	可选。 默认值为 Info。 此参数指示要输出的日志记录信息的级别。
/map： <文件路径>	可选。 包含文件映射指令的 .xml 文件的路径和名称。 在提取期间使用时，通常从 /folder 参数指定文件夹内部读取的文件会从映射文件指定的其他位置读取。 在打包操作期间，不会写入符合指令的文件。
/nologo	可选。 在运行时禁止显示横幅。
/log： <文件路径>	可选。 日志文件的路径和名称。 如果该文件已存在，则会将新的日志记录信息附加到该文件中。
@ <文件路径>	可选。 包含工具的命令行参数的文件的路径和名称。
/sourceLoc： <字符串>	可选。 此参数会生成模板资源文件，并且仅在 extract 时有效。 可能的值为auto或您要导出的语言的LCID/ISO代码。 当使用此参数时，提取给定区域设置的字符串资源作为 neutral .resx 文件。 如果指定 auto 开关，或只是长或短格式的开关，则会使用基础区域设置或解决方案。 您可以使用命令的简称：/src。
/本地化	可选。 将所有字符串资源提取或合并到 .resx 文件中。 您可以使用命令的简称：/loc。

使用 /map 命令参数

以下讨论详细介绍了 SolutionPackager 工具的 /map 参数的使用。

在自动构建系统中生成的文件（例如 .xapSilverlight 文件和插件程序集）通常不被提交到源代码管理中。 Web 资源可能已存在于源代码管理中与 SolutionPackager 工具不直接兼容的位置。 通过包含 /map 参数，可以指示 SolutionPackager 工具从备用位置读取和打包此类文件，而不是像通常那样从 Extract 文件夹内部读取和打包。 /map 参数必须指定 XML 文件的名称和路径，该文件包含映射指令，这些指令指示 SolutionPackager 按名称和路径匹配文件，并指示查找匹配文件的备用位置。 以下信息同样适用于所有指令。

• 列表中可能包含这些可匹配相同文件的指令。 文件前面列出的指令优先于后面列出的指令。

• 如果文件与任何指令匹配，则必须在至少一个备用位置找到该文件。 如果未找到匹配的备选方案，SolutionPackager 将发出错误。

• 文件夹和文件路径可以是绝对路径，也可以是相对路径。 相对路径始终从由 /folder 参数指定的文件夹计算。

• 环境变量可以使用 %variable% 语法指定。

• 文件夹通配符 “**” 可用于表示 “在任何子文件夹中”。 它只能用作路径的最后一部分，例如：“c：\folderA\**”。

• 文件名通配符只能以 “*.ext” 或 “*.*” 的形式使用。 不支持其他模式。

  这里描述了三种类型的指令映射，并提供了一个展示如何使用它们的示例。

文件夹映射

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

xml 格式
<Folder map="folderA" to="folderB" />

DESCRIPTION
匹配 “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" />

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

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

DESCRIPTION
与参数匹配 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 的 Developer Toolkit 项目中读取任何 Web 资源和两个默认生成的程序集。

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

托管和非托管解决方案

Dynamics 365 Customer Engagement （on-premises） 压缩解决方案 （.zip） 文件可以导出为两种类型之一，如下所示。

托管解决方案
准备导入到组织中的完整解决方案。 导入后，无法添加或删除组件，尽管它们可以选择允许进一步自定义。 建议在解决方案开发完成时执行此作。

非托管解决方案
一个开放式解决方案，对可以添加、删除或修改的内容没有限制。 在开发解决方案时，建议这样做。

压缩解决方案文件的格式将根据其类型（托管或非托管）而有所不同。 SolutionPackager 可以处理任一类型的压缩解决方案文件。 但是，该工具无法将一种类型转换为另一种类型。 将解决方案文件转换为其他类型（例如，从非托管转换为托管）的唯一方法是将非托管解决方案 .zip 文件导入 Dynamics 365 Server，然后将解决方案导出为托管解决方案。

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

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

该工具将假定托管 zip 文件与非托管文件位于同一文件夹中，并将这两个文件提取到一个文件夹中，从而保留托管和非托管组件存在差异。

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

故障排除

如果使用 Visual Studio 2012 编辑解决方案打包程序创建的资源文件，则在重新打包时可能会收到类似于以下内容的消息： “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 将资源文件的元数据标记替换为数据标记。

解决方法

1. 在您喜欢的文本编辑器中打开资源文件，然后找到并更新以下标签：

   <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. 将节点名称从 <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 资源编辑器时观察到此问题。

另请参阅

团队开发解决方案工具
将源代码管理与解决方案文件结合使用
解决方案简介