SolutionPackager 工具

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

這很重要

封裝和解除封裝解決方案已不再推薦使用 SolutionPackager 工具。 SolutionPackager 工具的功能已整合進 Power Platform CLI 中。 該 pac solution 指令包含許多動詞,包括 unpack、 pack、 clone,且 sync 包含與 SolutionPackager 工具相同的底層功能。

在何處查找 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 是一款命令列工具。 你可以使用下表描述的參數來呼叫它。

Argument 描述
/動作:{提取|打包} 必要的。 要執行的動作。 這項操作可以是將解決方案 .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 時,工具會覆蓋或刪除設定為唯讀屬性的檔案。 若未指定,工具不會覆寫或刪除帶有唯讀屬性的檔案。
/errorlevel: {Off|Error|Warning|Info|Verbose} 選擇性。 預設值為 Info。 此參數指示要輸出的記錄資訊的級別。
/map: <文件路徑> 選擇性。 包含檔案映射指令的 .xml 檔案的路徑和名稱。 在擷取期間使用時,原本應從 /folder 參數所指定資料夾內讀取的檔案,此工具會改從對應檔中指定的替代位置讀取。 在打包操作中,工具不會寫入與指令相符的檔案。
/nologo 選擇性。 可在執行階段抑制橫幅廣告。
/log: <文件路徑> 選擇性。 日誌檔的路徑和名稱。 如果該檔已存在,則會將新的日誌記錄資訊附加到該檔中。
@ <檔案路徑> 選擇性。 包含工具的命令行參數的檔案的路徑和名稱。
/sourceLoc: <字串> 選擇性。 此參數會生成範本資源文件,並且僅在 extract 時有效。

可能的值為 auto 或用於表示您要匯出的語言的 LCID/ISO 編碼。 使用此引數時,此工具會將指定地區設定的字串資源擷取為中性 .resx 檔案。 如果你指定 auto 或只用該參數的長格式或短格式,則會使用基底地區設定或方案。 您可以使用命令的簡稱:/src。
/本地化 選擇性。 將所有字串資源提取或合併到 .resx 檔中。 您可以使用命令的簡稱:/loc。 本地化選項支援 .resx 檔案的共用元件。 欲了解更多資訊,請參閱 使用 RESX 網路資源。
/解決方案名稱: <名稱> 選擇性。 當來源資料夾內含多個方案時,請在 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]/

這很重要

存在包含 *solution.yml 檔案的 solutions/ 子資料夾表示是 YAML 格式。 如果你把 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」。

  • 每個資料夾下方的子資料夾階層必須完全一致。

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

  • 你無法指定檔案名稱。

    範例

    <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 的 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 檔案。

故障排除

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

如果你使用 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 將資源檔案的元資料標籤替換成資料標籤。

因應措施

  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 檔案(例如 solution.yml)的資料夾執行 SolutionPackager(或 pac solution pack),但將這些檔案放在資料夾根目錄,而不是放在必要的 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 以取得完整擷取。

也請參閱