建立 Package Deployer 工具的套件

Package Deployer 讓管理員能在 Microsoft Dataverse 實例上部署套件。 Package Deployer 套件可以包含下列任何或所有項目:

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

備註

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

先決條件

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

流程概觀

要建立套件部署器套件,請完成以下步驟:

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

本文詳細說明這些步驟。

建立套件專案

首先,為該套件建立一個 Visual Studio 或 MSBuild 專案。 要建立專案,請在您的開發電腦上安裝兩個可用的工具擴充套件之一。 如果你使用 Visual Studio Code,請安裝 Microsoft Power Platform CLI。 如果您使用 Visual Studio 2019 或後續版本,請安裝 適用於 Visual Studio 的 Power Platform 工具。

要了解如何使用你想要的工具擴充功能建立專案,請在下一節選擇相應的分頁。 這兩個工具都會以相似格式來輸出專案。

執行 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 檔案。 您將按照本文後面所述修改這些檔案。

新增套件檔案

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

使用 CLI 時,你可以透過 add 子指令為你的套件專案新增外部套件、解決方案和參考。 輸入 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.

設定套件

在專案的 ImportConfig.xml 檔案中新增套件的相關資訊,以定義套件設定。 關於範例及有效元素與屬性的說明,請參見 ImportConfig Reference。

新增自訂程式碼

你可以新增自訂程式碼,分別在套件匯入至環境前、中、後執行。 要新增自訂程式碼,請依照以下指示操作:

  1. 編輯專案根目錄中的 PackageTemplate.cs 或 PackageImportExtension.cs 檔案。

  2. 在 C# 檔案中,您可以:

    1. 在 InitializeCustomExtension 的覆寫方法定義中,輸入當套件初始化時執行的自訂程式碼。

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

      例如,下列範例程式碼會啟用稱為 SkipChecks 的套件執行階段參數,其擁有兩個可能的值:true 或 false。 範例程式碼會檢查使用者在執行套件部署器時(無論是使用命令列或 PowerShell)時是否指定任何執行時參數,然後依此處理資訊。 如果使用者在執行套件時未指定執行時參數,RuntimeSettings 屬性的值為 null。

      public override void InitializeCustomExtension()  
      {
        // 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 與 Windows PowerShell 部署套件。

    2. 在 PreSolutionImport 的覆寫方法定義中輸入自訂程式碼,以便在解決方案匯入前執行。 使用此方法可指定在更新目標 Dataverse 實例中指定解決方案時,是否維護或覆寫自訂內容,以及是否自動啟用外掛與工作流程。

    3. 使用 RunSolutionUpgradeMigrationStep 的覆寫方法定義來執行兩個版本解決方案之間的資料轉換或升級。 這個方法只有在你匯入的解決方案已經存在於目標 Dataverse 實例時才會執行。

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

      參數 說明
      solutionName 方案的名稱
      oldVersion 舊方案的版本號碼
      newVersion 新方案的版本號碼
      oldSolutionId 舊方案的 GUID。
      newSolutionId 新方案的 GUID。
    4. 覆寫該方法 OverrideSolutionImportDecision,回傳一個 UserRequestedImportAction 枚舉,該枚舉控制解決方案的匯入是跳過、更新或升級(預設為升級)。

      public override UserRequestedImportAction OverrideSolutionImportDecision(
        string solutionUniqueName, Version organizationVersion,
        Version packageSolutionVersion, Version inboundSolutionVersion,
        Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
      {
        return systemSelectedImportAction == 
            ImportAction.Import ? UserRequestedImportAction.ForceUpdate
            : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
            packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
            systemSelectedImportAction);
      }
      
    5. 在 BeforeImportStage 方法的覆寫定義中,輸入要在解決方案匯入完成之前執行的自訂程式碼。 工具會在解決方案匯入完成之前匯入 ImportConfig.xml 檔案中所指定解決方案的範例資料及部分一般檔案。

    6. 使用 OverrideConfigurationDataFileLanguage 的覆寫方法定義來覆寫目前針對組態資料匯入選取的語言。 如果該語言的指定區域 ID(LCID)在套件的可用語言清單中找不到,則會匯入預設資料檔。

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

      如果您確定目標 Dataverse 執行個體未包含任何資料,則在此處略過資料檢查 (OverrideDataImportSafetyChecks = true) 可能會很有效。

    7. 在 AfterPrimaryImport 方法的覆寫定義中輸入自訂程式碼,讓其在匯入完成後執行。 工具會匯入之前未匯入的剩餘平面檔案,這些檔案在解決方案匯入開始前尚未匯入。

    8. 將套件資料夾的預設名稱變更為您想要的套件名稱。 要做到這點,請在 方案總管 窗格中重新命名 或 PkgFolder 資料夾,然後在該 GetImportPackageDataFolderName 屬性下編輯回傳值。

      public override string GetImportPackageDataFolderName  
      {  
          get  
          {  
              // WARNING this value directly correlates to the folder name in Solution 
              // Explorer where the ImportConfig.xml and sub content is located.  
              // Changing this name requires that you also change the correlating name
              // in Solution Explorer.
              return "PkgFolder";  
          }  
      }  
      
    9. 編輯 GetNameOfImport 屬性下的傳回值,以變更套件名稱。

      public override string GetNameOfImport(bool plural)  
      {  
          return "Package Short Name";  
      }  
      

      這個回傳的值是你在 Dynamics 365 套件部署器精靈中,顯示在套件選擇頁面上的套件名稱。

    10. 編輯 GetImportPackageDescriptionText 屬性下的傳回值,以變更套件描述。

      public override string GetImportPackageDescriptionText  
      {  
          get { return "Package Description"; }  
      }  
      

      此傳回值是在 Package Deployer 精靈的套件選取頁面上出現於套件名稱旁邊的套件描述。

    11. 編輯 GetLongNameOfImport 屬性下的傳回值,以變更套件完整名稱。

      public override string GetLongNameOfImport  
      {  
          get { return "Package Long Name"; }  
      }  
      

      選擇要安裝的套件後,套件長名稱會出現在下一頁。

  3. 該套件還能存取以下函式與變數:

    Name 類型 說明
    CreateProgressItem(String) 函數 在使用者介面(UI)中建立新的進度項目。
    RaiseUpdateEvent(String, ProgressPanelItemStatus) 函數 更新由對 CreateProgressItem(String) 的呼叫所產生的進度。

    ProgressPanelItemStatus 是包含下列值的列舉:

    工作中 = 0
    完成 = 1
    失敗 = 2
    警告 = 3
    未知 = 4
    RaiseFailEvent(String, Exception) 函數 使目前的狀態匯入失敗,並顯示例外狀況訊息。
    IsRoleAssociatedWithTeam(Guid, Guid) 函數 判斷該角色是否與特定團隊相關聯。
    IsWorkflowActive(Guid) 函數 判斷指定的工作流程是否處於啟用狀態。
    PackageLog 類別指標 套件初始化記錄介面的指標。 該套件利用此介面記錄訊息與例外至套件日誌檔案。
    RootControlDispatcher 房產 您的控制項在套件部署期間用來轉譯其本身 UI 的發送器介面。 使用此介面來裝合任何 UI 元素或命令。 使用前請檢查此變數是否為 null,因為它可能尚未設定任何值。
    CrmSvc 房產 CrmServiceClient 類別的指標,可讓套件從套件中定址 Dynamics 365。 使用此指標來執行 SDK 方法以及覆寫方法中的其他動作。
    DataImportBypass 房產 請指定 Dynamics 365 套件部署器是否跳過所有資料匯入操作,例如匯入 Dataverse 樣本資料、平面檔案資料,以及從組態遷移工具匯出的資料。 指定 true 或 false。 預設值為 false。
    OverrideDataImportSafetyChecks 房產 請說明 Dynamics 365 套件部署器是否繞過部分安全檢查,以提升匯入效能。 指定 true 或 false。 預設值為 false。

    僅在目標 Dataverse 實例不包含任何資料時,將此屬性設為 true。
  4. 儲存您的專案。 下一個步驟是建置套件。

建置和部署

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

建置

以下章節將根據你所使用的工具,說明如何建立你的套件。

要建立用 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 步驟中選擇的套件資料夾名稱相符。 此資料夾包含所有解決方案、設定資料、一般檔案及套件內容。

備註

你可能會看到一個 .NET 資料夾(例如 net472),裡面包含一個pdpublish資料夾。 你的 DLL 和其他專案檔案都在那個 pdpublish 資料夾裡。

  • <PackageName>.dll:該組件包含你套件的自訂程式碼。 預設情況下,組件的名稱會與你的專案名稱相符。

Deploy

建立套件後,使用套件部署工具、Windows PowerShell 或 CLI 指令部署到 Dataverse 實例。

最佳做法

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

建立套件

建立套件時,開發人員必須:

  • 確保套件組件已簽署。

部署套件

部署套件時,Dataverse 管理員必須:

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

也請參閱

解決方案封裝工具