SolutionPackager 是一款可逆地將 Microsoft Dataverse 壓縮的解決方案檔案分解成多個 XML 檔案及其他檔案的工具。 您可以接著使用原始檔控制系統輕鬆地管理這些檔案。 以下部分介紹如何運行該工具，以及如何將該工具用於託管和非託管解決方案。
Important
封裝和解除封裝解決方案已不再推薦使用 SolutionPackager 工具。 SolutionPackager 工具的功能已整合進 Power Platform CLI 中。 該 pac solution 指令包含許多動詞，包括 unpack、 pack、 clone，且 sync 包含與 SolutionPackager 工具相同的底層功能。
在何處查找 SolutionPackager 工具
SolutionPackager 工具作為 Microsoft.CrmSdk.CoreTools NuGet 套件的一部分發佈。 若要安裝程式，請執行下列步驟。
- 下載 NuGet 套件。
- 將套件副檔名從 .nupkg 重新命名為 .zip。
- 解壓縮已壓縮 (zip) 檔案的內容。
在 <extracted-folder-name>/contents/bin/coretools 資料夾中找到SolutionPackager.exe 執行檔。 從 coretools 資料夾執行程式，或將該資料夾新增至您的 PATH。
SolutionPackager 命令行參數
SolutionPackager 是一個命令行工具，可以使用下表中標識的參數進行調用。
| Argument | Description |
|---|---|
| /動作：{提取|打包} | 必須的。 要執行的動作。 這項操作可以是將解決方案 .zip 檔案提取到資料夾中，或者將資料夾打包成 .zip 檔案。 |
| /zipfile： <文件路徑> | 必須的。 解決方案 .zip 檔案的路徑和名稱。 解壓縮時，檔案必須存在且可讀取。 打包時，檔將被替換。 |
| /folder： <資料夾路徑> | 必須的。 資料夾的路徑。 提取時，將創建此資料夾並填充元件檔。 打包時，此資料夾必須已存在，並且包含以前提取的零部件檔。 |
| /packagetype： {未管理|託管 |兩者} | 選擇性。 要處理的包的類型。 預設值為 Unmanaged。 在大多數情況下，可以省略此參數，因為可以從 .zip 檔或元件文件內部讀取包類型。 進行解壓縮且指定 Both 時，受管理和未受管理的解決方案 .zip 檔案必須存在且已處理成單一資料夾。 進行壓縮且指定 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 屬性的檔。 若未指定，具有唯讀屬性的檔案不會被覆寫或刪除。 |
| /errorlevel： {關閉|錯誤|警告|信息|詳細} | 選擇性。 預設值為 Info。 此參數指示要輸出的記錄資訊的級別。 |
| /map： <文件路徑> | 選擇性。 包含檔案映射指令的 .xml 檔案的路徑和名稱。 在解壓縮期間使用時，一般從 /folder 參數指定的資料夾內讀取的檔案，是從對應檔中指定的替代位置讀取。 在打包操作時，與指令相符的檔案不會被寫入。 |
| /nologo | 選擇性。 可在執行階段抑制橫幅廣告。 |
| /log： <文件路徑> | 選擇性。 日誌檔的路徑和名稱。 如果該檔已存在，則會將新的日誌記錄資訊附加到該檔中。 |
| @ <檔案路徑> | 選擇性。 包含工具的命令行參數的檔案的路徑和名稱。 |
| /sourceLoc： <字串> | 選擇性。 此參數會生成範本資源文件，並且僅在 extract 時有效。 可能的值為 auto 或用於表示您要匯出的語言的 LCID/ISO 編碼。 使用此參數時，給定區域設置中的字串資源將提取為中性 .resx 檔。 如果指定 auto 或只指定參數完整或簡短格式，則使用基礎地區設定或解決方案。 您可以使用命令的簡稱：/src。 |
| /本地化 | 選擇性。 將所有字串資源提取或合併到 .resx 檔中。 您可以使用命令的簡稱：/loc。 本地化選項支援 .resx 檔案的共用元件。 詳細資訊：使用 RESX Web 資源 |
| /解決方案名稱： <名稱> | 選擇性。 當來源資料夾內含多個方案時，請在 solutions/*/solution.yml 下指定要打包或提取的唯一方案名稱。 當偵測到多個解決方案時，必須使用。 只適用於 YAML 版本控制格式。 你可以使用指令的簡短形式：/sn。 |
| /remapPluginTypeNames | 選擇性。 當指定時，外掛模組的完全限定類型名稱將根據解決方案中包含的組件進行重新映射。 預設啟用於 YAML 版本控制格式中。 你可以用指令的簡短形式：/fp。 |
原始碼控制檔案格式
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]/
Important
YAML 格式會因包含 solutions/ 檔案的子資料夾 *solution.yml 而自動偵測。
如果你的 YAML 清單檔案（solution.yml、 solutioncomponents.yml、 等等）放在資料夾根部，而不是在 下方 solutions/<SolutionUniqueName>/，工具就不會偵測到 YAML 格式。 工具會回退至 XML 路徑，並回報一個關於缺少 Customizations.xml 的誤導性錯誤。 請參閱 故障排除說明 ，了解如何解決此問題。
更多資訊： 解決方案 YAML 原始碼控制格式參考
格式化自動偵測規則
| 狀況 | 所用格式 |
|---|---|
solutions/*/solution.yml 找到 — 僅有一個解 |
YAML 格式，從資料夾推斷解決方案名稱 |
solutions/*/solution.yml 找到——多種解決方案 |
YAML 格式，其中 /SolutionName 參數必須 |
無 solutions/ 子目錄存在 |
XML 格式（舊有） |
打包 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 檔案：AnyName.zip
受管理的 .zip 檔案：AnyName_managed.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
在您喜歡的文字編輯器中打開資源檔，然後找到並更新以下標籤：
<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 資源編輯器時被觀察到。
錯誤：「找不到所需檔案 ...\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 以取得完整擷取。