建立 Package Deployer 工具的套件

發行項
06/27/2024

Package Deployer 可讓系統管理員在 Microsoft Dataverse 執行個體上部署套件。 Package Deployer 套件可以包含下列任何或所有項目：

一個或多個 Dataverse 解決方案檔案。
一般檔案或是從 Configuration Migration Tool 匯出的設定資料檔案。如需此工具的詳細資訊，請參閱使用 Configuration Migration Tool 在執行個體與組織之間移動設定資料。
可以在套件部署到 Dataverse 執行個體之前、期間或之後執行的自訂程式碼。
套件所特有、可在部署程序開始和結束時顯示的 HTML 內容。此內容對於提供套件中所部署解決方案及檔案的描述可能很有幫助。

Note

有另一種稱為外掛程式套件的套件類型。這種套件適用於外掛程式相依元件，但與 Package Deployer 套件沒有任何關聯性。

先決條件

確定您已準備好所有要包含在套件中的解決方案及其他檔案。
Visual Studio 2019 或更新版本，或 Visual Studio Code。

程序概觀

若要建立 Package Deployer 套件，請執行下列步驟。

建立 Visual Studio 或 MSBuild 專案
將解決方案及其他檔案新增至專案
更新提供的 HTML 檔案 (選用)
指定套件的設定值
定義套件的自訂程式碼
建置和部署套件

本文詳細介紹了這些步驟。

建立套件專案

第一個步驟是為套件建立 Visual Studio 或 MSBuild 專案。若要這樣，您必須在開發電腦上安裝兩個可用的工具擴充功能之一。如果使用的是 Visual Studio Code，請安裝 Microsoft Power Platform CLI。否則，如果使用 Visual Studio 2019 或更新版本，請安裝 Visual Studio 的 Power Platform Tools。

選取下方相應的索引標籤，了解如何使用所需的工具擴充功能來建立專案。這兩個工具都會以相似格式來輸出專案。

Power Platform CLI
Power Platform Tools

執行 pac 套件單位命令來建立初始套件。其他資訊：pac 套件

pac package init help
pac package init --outputDirectory DeploymentPackage

產生的 CLI 輸出包含如下所示的資料夾和檔案。這裡使用「DeploymentPackage」資料夾名稱做為範例。

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

在建立的專案中，找到 PkgAssets 資料夾中的 ImportConfig.xml 設定檔和 PackageImportExtension.cs 檔案。您將按照本文後面所述修改這些檔案。

您可以使用 Power Platform 解決方案範本建立 Visual Studio 專案，然後使用 Power Platform 套件部署專案範本新增套件專案，或直接使用 Power Platform 套件部署專案範本。

新增套件專案。

注意

不要選擇 Power Platform 套件範本。該範本適用於外掛程式套件。

產生的 Visual Studio 解決方案和專案會包含如下所示的資料夾和檔案。這裡使用「Deployment-package」名稱做為範例。為簡潔起見，此處未顯示 Content 資料夾的內容。

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

在建立的專案中，找到 PkgFolder 資料夾中的 ImportConfig.xml 設定檔和 PackageTemplate.cs 檔案。您將按照本文後面所述修改這些檔案。

關於使用 Power Platform Tools 擴充功能的詳細資訊：快速入門：建立 Power Platform Tools 專案

新增套件檔案

建立套件專案之後，您可以開始將解決方案及其他檔案新增至該專案。

Power Platform CLI
Power Platform Tools

使用 CLI 時，您可以使用其中一個新增子命令，將外部套件、解決方案和參考新增至套件專案。輸入 pac package help 以查看子命令清單。讓我們將解決方案新增至套件。

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

在方案總管窗格中，將 Dataverse 解決方案及其他檔案新增至 PkgFolder 資料夾之下。 HTML 檔案屬於內容資料夾。稍後將詳細說明此 HTML 內容。
對於每個您所新增的檔案，在屬性窗格中，將複製到輸出目錄值設定為永遠複製。設定此值可確保您的檔案會出現在產生的套件中。

接下來，更新 HTML 語言特定檔案。

在方案總管窗格中，展開 PkgFolder>內容>en-us。找到名稱為 WelcomeHTML 和 EndHTML 的兩個資料夾。這些資料夾包含 HTML 及相關聯檔案，可讓您在套件部署程序結束和開始時 (向使用者) 顯示資訊。編輯這些資料夾之 HTML 資料夾中的檔案，以新增要為套件顯示的資訊。
您也可以在套件中新增其他語言的 HTML 檔案，讓 HTML 的內容根據使用者電腦的地區設定，以適當的語言來顯示。若要執行此操作：
1. 在 PkgFolder>內容底下建立 en-us 資料夾的複本。
2. 將複製的資料夾重新命名為適當的語言。例如，若為西班牙文，則重新命名為 es-ES。
3. 修改 HTML 檔案內容以新增西班牙文內容。

設定套件

在專案的 ImportConfig.xml 檔案中新增套件的相關資訊，以定義套件設定。有關要使用的有效元素和屬性的範例和說明，請參閱 ImportConfig 參考。

新增自訂程式碼

您可以新增在將套件匯入至環境之前、之際以及之後執行的自訂程式碼。若要這樣，請遵循下列指示。

編輯專案根資料夾中的 PackageTemplate.cs (或 PackageImportExtension.cs) 檔案。

在 C# 檔案中，您可以：

輸入要在套件於 InitializeCustomExtension 的覆寫方法定義中進行初始化時執行的自訂程式碼。

此方法可讓使用者在執行套件時，使用執行階段參數。身為開發人員，只要您有程式碼可根據使用者輸入加以處理，就可以使用 RuntimeSettings 屬性將任何執行階段參數支援新增至套件。

例如，下列範例程式碼會啟用稱為 SkipChecks 的套件執行階段參數，其擁有兩個可能的值：true 或 false。範例程式碼會檢查使用者是否在執行 Package Deployer 時已指定任何執行階段參數 (使用命令列或 PowerShell)，然後相應地處理資訊。如果使用者執行套件時未指定任何執行階段參數，則 RuntimeSettings 屬性的值將是 null。
```
public override void InitializeCustomExtension()  
{  
// Do nothing.  

// Validate the state of the runtime settings object.  
if (RuntimeSettings != null)  
{  
PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
foreach (var setting in RuntimeSettings)  
{  
PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
}  

// Check to see if skip checks is present.  
if ( RuntimeSettings.ContainsKey("SkipChecks") )  
{  
bool bSkipChecks = false;  
if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
OverrideDataImportSafetyChecks = bSkipChecks;  
}  
}  
else  
PackageLog.Log("Runtime Settings not populated");  
}  
```
此程式碼可讓系統管理員使用命令列或 Import-CrmPackage Cmdlet 指定是否要在執行 Package Deployer 工具匯入套件時略過安全性檢查。其他資訊：使用 Package Deployer 和 Windows PowerShell 來部署套件
在 PreSolutionImport 的覆寫方法定義中輸入要在匯入解決方案之前執行的自訂程式碼，以指定要維護或覆寫自訂，在更新目標 Dataverse 執行個體中指定的解決方案時，以及是否要自動啟用外掛程式及工作流程。

使用 RunSolutionUpgradeMigrationStep 的覆寫方法定義，在解決方案的兩種版本之間執行資料轉換或升級，只有在您要匯入的解決方案已存在於目標 Dataverse 執行個體時，才會呼叫此方法。

這個函數必須有下列參數：

參數	描述
`solutionName`	方案的名稱
`oldVersion`	舊方案的版本號碼
`newVersion`	新方案的版本號碼
`oldSolutionId`	舊方案的 GUID。
`newSolutionId`	新方案的 GUID。

在 BeforeImportStage 方法的覆寫定義中，輸入要在解決方案匯入完成之前執行的自訂程式碼。在 ImportConfig.xml 檔案中指定的解決方案的範例資料以及某些一般資料，會在解決方案匯入完成之前匯入。
使用 OverrideConfigurationDataFileLanguage 的覆寫方法定義覆寫目前針對組態資料匯入選取的語言。如果所指定語言的指定地區設定識別碼 (LCID) 在套件的可用語言清單中找不到，則會匯入預設資料檔案。

您可以在 ImportConfig.xml 檔案的 <cmtdatafiles> 節點中指定組態資料的可用語言。預設的組態資料匯入檔案是在 ImportConfig.xml 檔案的 crmmigdataimportfile 屬性中指定。

在此處略過資料檢查 (OverrideDataImportSafetyChecks = true) 可能很有效，如果您確定目標 Dataverse 執行個體未包含任何資料。
在 AfterPrimaryImport> 方法的覆寫定義中，輸入要在匯入完成之後執行的自訂程式碼。在解決方案匯入開始之前，先前未匯入的其餘一般檔案，現在才會匯入。

將套件資料夾的預設名稱變更為您想要的套件名稱。若要這麼做，請重新命名方案總管窗格中的 PkgFolder (或 PkgAssets) 資料夾，然後編輯 GetImportPackageDataFolderName 屬性中的傳回值。

public override string GetImportPackageDataFolderName  
{  
get  
{  
// WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
// Changing this name requires that you also change the correlating name in the Solution Explorer  
return "PkgFolder";  
}  
}

編輯 GetNameOfImport 屬性下的傳回值，以變更套件名稱。
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
此傳回值會在 Dynamics 365 Package Deployer 精靈中出現於套件選取頁面的套件名稱。
編輯 GetImportPackageDescriptionText 屬性下的傳回值，以變更套件描述。
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
此傳回值會在 Package Deployer 精靈的套件選取頁面上出現於套件名稱旁邊的套件描述。
編輯 GetLongNameOfImport 屬性下的傳回值，以變更套件完整名稱。
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
套件完整名稱會在您選取要安裝的套件之後，出現於下一個頁面。

此外，套件還可以使用下列函數和變數：

名稱	類型	描述
CreateProgressItem(String)	函數	用來在使用者介面 (UI) 中建立新的進度項目。
RaiseUpdateEvent(String, ProgressPanelItemStatus)	函數	用來更新藉由呼叫 CreateProgressItem(String) 所建立的進度。 ProgressPanelItemStatus 是包含下列值的列舉：工作中 = 0 完成 = 1 失敗 = 2 警告 = 3 未知 = 4
RaiseFailEvent(String, Exception)	Function	用來使目前的狀態匯入失敗，並產生例外狀況訊息。
IsRoleAssoicatedWithTeam(Guid, Guid)	函數	用來判斷角色是否與特定團隊有關聯。
IsWorkflowActive(Guid)	函數	用來判斷指定的工作流程是否在使用中。
PackageLog	類別指標	套件初始化記錄介面的指標。套件會使用這個介面，將訊息和例外狀況記錄到套件記錄檔。
RootControlDispatcher	屬性	用於允許控制項在套件部署期間轉譯其本身 UI 的發送器介面。使用此介面來裝合任何 UI 元素或命令。由於可能不會將這個變數設定為某個值，請務必在使用該變數之前檢查其值是否為 null。
CrmSvc	屬性	CrmServiceClient 類別的指標，可讓套件從套件中定址 Dynamics 365。使用此指標來執行 SDK 方法以及覆寫方法中的其他動作。
DataImportBypass	屬性	指定 Dynamics 365 Package Deployer 是否略過所有資料匯入作業，例如匯入 Dataverse 範例資料、一般檔案資料，以及從 Configuration Migration Tool 匯出的資料。指定 true 或 false。預設值為 `false`。
OverrideDataImportSafetyChecks	屬性	指定 Dynamics 365 Package Deployer 是否略過部分安全檢查，這樣有助於改善匯入效能。指定 `true` 或 `false`。預設值為 `false`。只有在目標 Dataverse 執行個體未包含任何資料時，才應將此屬性設定為 `true`。

儲存您的專案。下一個步驟是建置套件。

建置和部署

以下小節說明如何建置和部署套件。

組建

下面根據您使用的工具描述了建立您的套件。

Power Platform CLI
Power Platform Tools

要建置使用 CLI 建立的套件，您可以將 .csproj 檔案載入到 Visual Studio 中，但我們將使用 dotnet 命令和 MSBuild。以下範例假設工作目錄包含 *.csproj 檔案。

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

您可以選擇查看已建置套件的詳細資料。

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

您的套件是由 <Project>\Bin\Debug 資料夾中的下列檔案構成。

<PackageName> 資料夾：資料夾名稱與您在本節新增自訂程式碼的步驟 2.g 中變更的套件資料夾名稱相同。此資料夾包含所有解決方案、設定資料、一般檔案及套件內容。

Note

您可能會看到包含 pdpublish 資料夾的 .NET 資料夾 (例如，net472)。您的 DLL 及其他專案檔案是在該 pdpublish 資料夾中。

<PackageName>.dll：此組件包含套件的自訂程式碼。組件的名稱預設會與專案名稱相同。

部署

建立套件之後，您可以使用 Package Deployer 工具、Windows PowerShell 或 CLI 命令，將該套件部署在 Dataverse 執行個體上。

若要使用 Package Deployer 工具來部署，請先依照 Dataverse 開發工具中所述的方式來下載工具。接下來，請按照文章使用 Package Deployer 或 Windows PowerShell 部署套件中有關套件部署的詳細資訊進行操作。
若要使用 CLI 進行部署，請使用 pac package deploy 命令。
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
Note

若要使用 CLI 將套件部署至目標環境，您必須先設定驗證設定檔，並選取組織。其他資訊：pac auth create、pac org select

最佳做法

以下所列是一些要在使用 Package Deployer 套件時遵循的最佳做法提示。

建立套件

建立套件時，開發人員必須：

確保套件組件已簽署。

部署套件

部署套件時，Dataverse 系統管理員必須：

堅持要求已簽署套件組件，讓您可以將組件追蹤至其來源。
先在生產前執行個體 (最好是生產執行個體的鏡像映像) 測試套件，然後在生產執行個體上執行套件。
備份生產執行個體，然後再部署套件。

請參閱

解決方案封裝工具

共用方式為