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}	選用。要處理的套件類型。預設值為 Unmanaged。因為可從 .zip 檔案或元件檔內讀取套件類型，在大部分情況下可以省略此引數。進行解壓縮且指定 Both 時，受管理和未受管理的解決方案 .zip 檔案必須存在且已處理成單一資料夾。進行壓縮且指定 Both 時，受管理和未受管理的解決方案 .zip 檔案會從一個資料夾產生。如需詳細資訊，請參閱本主題後面有關處理受管理和未受管理的解決方案的章節。
/allowWrite:{Yes\|No}	選用。預設值為 Yes。此引數只在解壓縮時使用。指定 /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 代碼。使用此引述時，從特定地區設定的字串資源解壓縮為中性 .resx 檔案。如果指定 `auto` 或只指定參數完整或簡短格式，則使用基礎地區設定或解決方案。您可以使用命令的簡短格式：/src。
/localize	選擇性。解壓縮或合併所有字串資源到 .resx 檔案。您可以使用命令的簡短格式：/loc。本地化選項支援 .resx 檔案的共用元件。詳細資訊：使用 RESX Web 資源

使用 /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 套件範例中，如果檔案已經存在於指定的位置，則不會覆寫 886_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 的開發人員工具套件專案讀取任何 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>

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

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

受管理的解決方案
已完成的解決方案準備匯入組織。當匯入，無法新增或移除元件，但它們可以選擇性允許進一步自訂。在解決方案開發完成時，這是建議選項。

未受管理的解決方案
開啟解決方案，沒有限制新增、移除或修改內容。在解決方案開發期間，這是建議選項。

根據其類型，受管理或未受管理，壓縮解決方案檔案的格式將會不同。 SolutionPackager 可以處理任何類型的壓縮解決方案檔案。不過，工具不能轉換類型。解決方案檔案轉換成其他類型的唯一方式，例如從未受管理轉換成受管理，是透過將未受管理的解決方案 .zip 檔案匯入 Dataverse 伺服器，然後匯出解決方案為受管理的解決方案。

SolutionPackager 可以透過 /PackageType:Both 參數，將受管理和未受管理的解決方案 .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 命令引數

資料夾對應

檔案對檔案對應

檔案對路徑對應

範例對應

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

疑難排解​​

因應措施

請參閱

其他資源

疑難排解