SolutionPackager 工具

SolutionPackager 是一款可逆地將 Microsoft Dataverse 壓縮的解決方案檔案分解成多個 XML 檔案及其他檔案的工具。 您可以接著使用原始檔控制系統輕鬆地管理這些檔案。 以下部分介紹如何運行該工具，以及如何將該工具用於託管和非託管解決方案。

在何處查找 SolutionPackager 工具

SolutionPackager 工具作為 Microsoft.CrmSdk.CoreTools NuGet 套件的一部分發佈。 若要安裝程式，請執行下列步驟。

1. 下載 NuGet 套件。
2. 將套件副檔名從 .nupkg 重新命名為 .zip。
3. 解壓縮已壓縮 (zip) 檔案的內容。

在 <extracted-folder-name>/contents/bin/coretools 資料夾中找到SolutionPackager.exe 執行檔。 從 coretools 資料夾執行程式，或將該資料夾新增至您的 PATH。

SolutionPackager 命令行參數

SolutionPackager 是一個命令行工具，可以使用下表中標識的參數進行調用。

原始碼控制檔案格式

SolutionPackager 在解壓與打包解決方案時支援兩種資料夾配置。

XML 格式（舊有）

原始格式。 解決方案的元資料儲存在 Other\Solution.xml 和 Other\Customizations.xml中，所有元件檔案會與這些檔案一同解壓縮成一個平面資料夾階層。 此格式是解壓 .zip 檔案時的預設格式，無需額外設定。

YAML 原始碼控制格式

此格式與 Dataverse Git 整合同時推出，將解決方案元資料以 YAML 檔案形式儲存，分布於結構化資料夾階層中。 這是你在 Power Apps 中使用 Git 原生整合提交解決方案時寫的格式。

相較於 XML 格式的優點

• 在原始碼控制中產生更清晰且易讀的各元件差異
• 支援在同一儲存庫資料夾中存放多個解決方案
• Canvas 應用程式 .msapp 檔案與現代流程僅支援此格式
• 預設啟用了插件類型名稱重映射

所需資料夾結構

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

更多資訊： 解決方案 YAML 原始碼控制格式參考

格式化自動偵測規則

打包 YAML 格式資料夾

以下指令會打包一個 YAML 格式資料夾。

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

從多解決方案資料夾打包

以下指令將指定的解決方案打包到多解決方案資料夾中。

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

使用 /map 命令參數

以下討論詳細介紹了 SolutionPackager 工具的 /map 參數的使用。

在自動化建置系統中建立的檔案 (例如 .xap Silverlight 檔案和外掛程式組件) 通常不會簽入原始檔控制中。 Web 資源可能已存在於原始檔控制中與 SolutionPackager 工具不直接相容的位置。 通過包含 /map 參數，可以指示SolutionPackager 工具從備用位置讀取和打包此類檔，而不是像通常那樣從Extract資料夾內部讀取和打包。 /map 參數必須指定包含對應指示詞之 XML 檔案的名稱和路徑。 這些指示詞會指示 SolutionPackager 依其名稱和路徑來比對檔案，並指出要尋找相符檔案的替代位置。 以下信息同樣適用於所有指令。

• 可能會列出多個指示詞，包括比對相同檔案的指示詞。 檔案中前面列出的指示詞優先於後面列出的指示詞。

• 如果檔與任何指令匹配，則必須在至少一個備用位置找到該檔。 如果找不到任何相符替代項目，SolutionPackager 會發出錯誤。

• 資料夾和文件路徑可以是絕對路徑，也可以是相對路徑。 相對路徑一律從 /folder 參數指定的資料夾評估。

• 環境變數可以使用 %variable% 語法指定。

• 資料夾萬用字元「**」可表示「在任何子資料夾中」。 它只能作為路徑的最後部分，例如：「c：\folderA\**」。

• 檔案名稱萬用字元只能以「*.ext」或「*.*」的形式使用。 不支援其他模式。

  這裡描述了三種類型的指令映射，並附上了一個示範如何使用它們的範例。

資料夾對應

下列資訊提供有關資料夾對應的詳細資訊。

Xml 格式

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

說明

與「folderA」相符的檔案路徑會切換到「folderB」。

• 每一個的子資料夾階層必須完全符合。

• 不支援資料夾萬用字元。

• 不能指定任何檔名。

  Examples

  <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 的名稱不同。

• 不支援檔案名稱萬用字元。

• 支援資料夾萬用字元。

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

在上述 NuGet 套件範例中，如果指定位置中已存在 cr886_PluginPackageTest.nupkg，則不會覆寫該檔案。

檔案對路徑對應

下面提供了有關檔到路徑映射的詳細資訊。

Xml 格式

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

說明

與參數匹配 map 的任何檔都將從參數中指定的 to 路徑中讀取。

對於 map 參數：

• 必須指定檔名。 路徑是可選的。 如果未指定路徑，則可以匹配任何資料夾中的檔。

• 支援檔名通配符。

• 支援資料夾萬用字元。

對於 to 參數：

• 必須指定路徑。

• 支援資料夾萬用字元。

• 不得指定檔名。

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

示例映射

下面的 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 subfolders -->  
       <FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />  
       <FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />  
</Mapping>  

受管理和未受管理的解決方案

Dataverse 壓縮的解決方案 (.zip) 檔案可以匯出成此處顯示的兩種類型中的一個。

受管理的解決方案
準備導入到組織中的完整解決方案。 匯入後，元件無法新增或移除，但可選擇性地進行進一步自訂。 建議在解決方案開發完成時執行此作。

未受管理的解決方案
一個開放式解決方案，對可以添加、刪除或修改的內容沒有限制。 建議在開發解決方案時執行此作。

壓縮解決方案檔的格式將根據其類型（託管或非託管）而有所不同。 SolutionPackager 可以處理任一類型的壓縮解決方案檔。 然而，這個工具無法將一種類型轉換成另一種。 把解決方案檔案轉換成其他類型的唯一方式 (例如從未受管理轉換成受管理)，是透過將未受管理解決方案的 .zip 檔案匯入 Dataverse 伺服器，然後匯出解決方案為受管理的解決方案。

SolutionPackager 可以通過 /PackageType：Both 參數將非託管和託管解決方案 .zip 文件作為組合集進行處理。 要執行此作，必須將解決方案匯出為每種類型兩次，並按如下方式命名 .zip 檔。

該工具將假定託管 zip 檔與非託管檔位於同一資料夾中，並將這兩個檔提取到一個資料夾中，從而保留託管和非託管元件存在差異。

在解決方案解壓縮為未受管理和受管理之後，使用 /PackageType 參數指定要建立的類型，可從該單一資料夾壓縮兩個類型或個別壓縮每個類型。 指定兩個檔案時，會使用上述命名慣例產生兩個 .zip 檔案。 如果在從雙重託管和非託管資料夾打包時缺少 /PackageType 參數，則預設生成單個非託管 .zip 檔。

Troubleshooting

使用 Visual Studio 編輯資源檔案時顯示的訊息

如果你使用 Visual Studio 來編輯解決方案封包器建立的資源 fsiles，當你重新打包時可能會收到類似的訊息："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 將資源檔案的元資料標籤替換成資料標籤。

Workaround

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 資源編輯器時被觀察到。

錯誤：「找不到所需檔案 ...\Other\Customizations.xml」，YAML 資料夾中顯示此錯誤

當你對包含 YAML 檔案（如 pac solution pack，但這些檔案放在資料夾根部而非所需的solution.yml子資料夾內）執行 SolutionPackager（或 solutions/<SolutionUniqueName>/）時，就會出現這個錯誤。

原因： 該工具透過尋找 solutions/ 包含 *solution.yml 檔案的子資料夾來偵測 YAML 原始碼控制格式。 當該目錄缺失時，工具會靜默地退回到 XML（舊有）格式，並期望 Other\Customizations.xml。 產生的錯誤訊息指向一個 XML 檔案，卻未提及 YAML，這點具有誤導性。

修正方法： 重新整理資料夾，使 YAML 清單檔案位於正確的路徑下：

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

如果您已從 Git 整合認可或 pac solution clone 取得資料夾，則資料夾結構應該已經正確。 若資料夾只包含頂層 YAML 檔案而沒有子 solutions/ 目錄，代表不完整的解壓，無法直接打包。

警告：rootcomponents.yml 中宣告的元件沒有原始碼檔案

當某元件（如畫布應用程式）被列入 rootcomponents.yml ，但預期的元件資料夾中沒有對應的原始碼檔案時（例如， canvasapps/<schema-name>/） 會顯示此警告。

效果： 工具仍然成功（退出代碼 0）並產生有效 .zip 檔案，但已宣告的元件會被省略於套件解決方案中。

原因： 該資料夾是部分解壓產生的，或是元件的原始碼檔案未包含在儲存庫中。 例如，只有解決方案清單檔案被提交，而非 Canvas 應用程式本身。

修正： 確保在rootcomponents.yml中宣告的所有元件都有對應的來源檔案存在於該資料夾中。 對於 canvas 應用程式，檔案 .msapp 必須存在於 canvasapps/<schema-name>/。 若缺少任何檔案，請從 Dataverse 重新匯出完整解碼並重新解壓，或使用 pac solution clone 以取得完整擷取。

參見

• 將原始程式碼管理與解決方案檔結合使用
• 解決方案概念