建立 Package Deployer 工具的套件
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 Tools 擴充功能目前僅適用於 Visual Studio 2019。 不過，建立的專案可以是使用 Visual Studio 2019 或更新版本所建置。
選取下方相應的索引標籤，了解如何使用所需的工具擴充功能來建立專案。 這兩個工具都會以相似格式來輸出專案。
執行 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 時，您可以使用其中一個新增子命令，將外部套件、解決方案和參考新增至套件專案。 輸入 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 檔案中新增套件的相關資訊，以定義套件設定。 開啟檔案以進行編輯。 下列瀏覽器提供設定檔中有關每個參數及節點的資訊。
installsampledata
True或false。 如果為true，則將範例資料安裝到 Dataverse 執行個體。 此資料與您可從 Dataverse 的 設定>資料管理區域安裝的範例資料相同。waitforsampledatatoinstall
true 或 false。 如果為 true，而且 installsampledata 也設定為 true，請先等待範例資料完成安裝，再部署套件。Note
如果您要將
waitforsampledatatoinstall設定為 true，則務必將 installsampledata 設定為 true。agentdesktopzipfile
要解壓縮的 ZIP 檔案的名稱。 如果您在此處指定 .zip 檔案名稱，則會在套件部署程序中新增畫面，提示您選取要解壓縮檔案內容的位置。此屬性通常用於建立 Dynamics 365 的 Unified Service Desk 套件。 如需 Unified Service Desk 的詳細資訊，請參閱 Unified Service Desk 3.0 管理指南。
agentdesktopexename
要在部署程序結束時叫用的 ZIP 檔案中 .exe 或 .msi 檔案的名稱或 URL。此屬性通常用於建立 Unified Service Desk 的套件。
crmmigdataimportfile
使用 Configuration Migration Tool 所匯出之預設組態資料檔 (.zip) 的檔案名稱。您也可以在執行 Package Deployer 的同時，使用新的執行階段設定匯入組態資料檔的翻譯版本，依據指定的地區設定 ID (LCID)。 使用
<cmtdatafile>節點 (稍後說明) 指定套件中組態資料檔的翻譯版本，然後使用OverrideConfigurationDataFileLanguage方法 (稍後說明) 依據指定的地區設定識別碼指定，使用執行階段設定匯入組態資料檔的邏輯。 您無法使用套件一次匯入多個組態資料檔。對於 Dataverse (內部部署)，如果您的組態資料檔包含使用者資訊，而且來源和目標 Dataverse 執行個體位於相同的 Active Directory 網域，則使用者資訊會匯入目標 Dataverse 執行個體。 若要將使用者資訊匯入不同網域的 Dataverse (內部部署) 執行個體，則必須在專案中加入使用 Configuration Migration Tool 所產生的使用者對應檔 (.xml)，並使用稍後說明之
<cmtdatafile>節點中的usermapfilename屬性來指定它以及組態資料檔。 使用者資訊無法匯入 Dataverse 執行個體中。
<solutions>節點
包含描述要匯入之方案的<configsolutionfile>節點陣列。 這個節點下的方案的順序代表在目標 Dataverse 執行個體上匯入方案所依照的順序。<configsolutionfile>節點
使用<solutions>節點底下的此節點指定個別解決方案，以及要匯入的每一個解決方案的下列資訊：solutionpackagefilename：指定解決方案的 .zip 檔案名稱。 必要。overwriteunmanagedcustomizations：指定是否要覆寫所有未受管理的自訂，當您匯入已存在目標 Dynamics 365 執行個體的解決方案時。 此屬性是選擇性的，如果您未指定此屬性，根據預設，現有解決方案中的未受管理自訂會保留在目標 Dynamics 365 執行個體中。publishworkflowsandactivateplugins：指定是否在匯入解決方案之後發行工作流程，並在目標 Dynamics 365 執行個體中啟用外掛程式。 此屬性是選擇性的，如果您未指定此屬性，根據預設，在目標 Dynamics 365 執行個體上匯入解決方案之後，工作流程會發行且外掛程式會啟用。您可以新增多個
<configsolutionfile>節點，在套件中新增同樣多的方案檔名稱。 例如，如果您要匯入三個解決方案檔案，請依照下列方式新增這些檔案：
<solutions> <configsolutionfile solutionpackagefilename="SampleSolutionOne_1_0_managed.zip" overwriteunmanagedcustomizations="false" publishworkflowsandactivateplugins="true"/> <configsolutionfile solutionpackagefilename="SampleSolutionTwo_1_0_managed.zip" overwriteunmanagedcustomizations="false" publishworkflowsandactivateplugins="true"/> <configsolutionfile solutionpackagefilename="SampleSolutionThree_1_0_managed.zip" /> </solutions><filestoimport>節點
包含<configimportfile>與<zipimportdetails>節點的陣列，這些節點分別用來描述要匯入的個別檔案和 ZIP 檔案。<configimportfile>節點
在<configimportfile>節點下使用這個節點，描述要匯入至 Dataverse 的檔案。 您可以新增多個<configimportfile>節點，在套件中新增同樣多的檔案。<filestoimport> <configimportfile filename="File.csv" filetype="CSV" associatedmap="FileMap" importtoentity="FileEntity" datadelimiter="" fielddelimiter="comma" enableduplicatedetection="true" isfirstrowheader="true" isrecordownerateam="false" owneruser="" waitforimporttocomplete="true" /> <configimportfile filename="File.zip" filetype="ZIP" associatedmap="FileMapName" importtoentity="FileEntity" datadelimiter="" fielddelimiter="comma" enableduplicatedetection="true" isfirstrowheader="true" isrecordownerateam="false" owneruser="" waitforimporttocomplete="true"/> </filestoimport>以下是支援的屬性清單：
屬性 描述 filename包含匯入資料之檔案的名稱。 如果檔案是 .zip 檔，則 <zipimportdetails>節點必須存在，而且 .zip 檔中的每個檔案都有<zipimportdetail>節點。filetype此值可以是 csv、xml 或 zip。 associatedmap要用於這個檔案的 Dataverse 匯入資料對應的名稱。 如果空白，請嘗試為這個檔案使用系統決定的匯入資料對應名稱。 importtoentity可以是 ZIP 檔案中 exe 的名稱、URL 或 .msi，以便提供要在程序結束時叫用的連結。 datadelimiter用於匯入檔案的資料分隔符號名稱。 有效值為單引號或雙引號。 fielddelimiter用於匯入檔案的欄位分隔符號名稱。 有效值為逗號、冒號或單引號。 enableduplicatedetection表示是否對資料匯入啟用重複資料偵測規則。 有效值為 true 或 false。 isfirstrowheader用來表示匯入檔案的第一列包含欄位名稱。 有效值為 true或false。isrecordownerateam表示匯入時的記錄負責人是否必須為團隊。 有效值為 true或false。owneruser表示應該擁有記錄的使用者識別碼。 預設值為目前登入的使用者。 waitforimporttocomplete如果為 true，系統會等待匯入完成後，再繼續執行。 如果為false，則將工作排入佇列並繼續進行。<zipimportdetails>節點
這個節點包含<zipimportdetail>節點的陣列，這些節點描述 ZIP 檔案中所包含用來匯入至 Dynamics 365 的檔案。<zipimportdetail>節點
在<zipimportdetails>下使用這個節點，提供<configimportfile>節點指定之 .zip 檔中個別檔案的相關資訊。<filestoimport> ... ... <zipimportdetails> <zipimportdetail filename="subfile1.csv" filetype="csv" importtoentity="account" /> <zipimportdetail filename="subfile2.csv" filetype="csv" importtoentity="contact" /> </zipimportdetails> </filestoimport>以下套件支援的屬性：
屬性 描述 filename包含匯入資料之檔案的名稱。 filetype此值可以是 csv 或 xml。 importtoentity可以是 ZIP 檔案中 exe 的名稱、URL 或 .msi，以便提供要在程序結束時叫用的連結。 <filesmapstoimport>節點
這個節點包含要匯入之<configmapimportfile>節點的陣列。 節點中的對應檔順序表示匯入這些對應檔所依照的順序。 如需資料對應的詳細資訊，請參閱 建立用於匯入的資料對應。<configimportmapfile>節點
在<filesmapstoimport>節點下使用這個節點，提供要在 Dataverse 中匯入之個別對應檔的相關資訊。<filesmapstoimport> <configimportmapfile filename="FileMap.xml" /> </filesmapstoimport><cmtdatafiles>節點
此節點包含<cmtdatafile>節點陣列，其中包含要匯入的組態資料檔的當地語系化版本。<cmtdatafile>節點
在<cmtdatafiles>節點底下使用此節點指定翻譯的組態資料檔與地區設定 ID (必要) 和使用者資訊對應檔 (選用)。 例如：<cmtdatafiles> <cmtdatafile filename="data_1033.zip" lcid="1033" usermapfilename="UserMap.xml" /> <cmtdatafile filename="data_1041.zip" lcid="1041" usermapfilename="" /> </cmtdatafiles>您可以在
OverrideConfigurationDataFileLanguage方法 (稍後說明) 中定義自訂邏輯，根據指定的地區設定 ID (LCID) 值，使用執行階段設定 (稍後說明) 匯入當地語系化組態資料檔，而不匯入預設檔案 (在 crmmigdataimportfile 中指定)。選取全部儲存。
下列 xml 表示範例
ImportConfig.xml檔案的內容。<?xml version="1.0" encoding="utf-16"?> <configdatastorage xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema" installsampledata="true" waitforsampledatatoinstall="true" agentdesktopzipfile="" agentdesktopexename="" crmmigdataimportfile="data_1033.zip"> <solutions> <configsolutionfile solutionpackagefilename="SampleSolutionOne_1_0_managed.zip" overwriteunmanagedcustomizations="false" publishworkflowsandactivateplugins="true"/> <configsolutionfile solutionpackagefilename="SampleSolutionTwo_1_0_managed.zip" overwriteunmanagedcustomizations="false" publishworkflowsandactivateplugins="true"/> <configsolutionfile solutionpackagefilename="SampleSolutionThree_1_0_managed.zip" /> </solutions> <filestoimport> <configimportfile filename="SampleOption.csv" filetype="CSV" associatedmap="SampleOption" importtoentity="sample_option" datadelimiter="" fielddelimiter="comma" enableduplicatedetection="true" isfirstrowheader="true" isrecordownerateam="false" owneruser="" waitforimporttocomplete="false"/> <configimportfile filename="File.zip" filetype="ZIP" associatedmap="FileMapName" importtoentity="FileEntity" datadelimiter="" fielddelimiter="comma" enableduplicatedetection="true" isfirstrowheader="true" isrecordownerateam="false" owneruser="" waitforimporttocomplete="true"/> <zipimportdetails> <zipimportdetail filename="subfile1.csv" filetype="csv" importtoentity="account" /> <zipimportdetail filename="subfile2.csv" filetype="csv" importtoentity="contact" /> </zipimportdetails> </filestoimport> <filesmapstoimport> <configimportmapfile filename="SampleOption.xml" /> </filesmapstoimport> <cmtdatafiles> <cmtdatafile filename="data_1033.zip" lcid="1033" usermapfilename="UserMap.xml" /> <cmtdatafile filename="data_1041.zip" lcid="1041" usermapfilename="" /> </cmtdatafiles> </configdatastorage>
新增自訂程式碼
您可以新增在將套件匯入至環境之前、之際以及之後執行的自訂程式碼。 若要這樣，請遵循下列指示。
編輯專案根資料夾中的 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
未知 = 4RaiseFailEvent(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。儲存您的專案。 下一個步驟是建置套件。
建置和部署
以下小節說明如何建置和部署套件。
組建
下面根據您使用的工具描述了建立您的套件。
要建置使用 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.zipNote
若要使用 CLI 將套件部署至目標環境，您必須先設定驗證設定檔，並選取組織。 其他資訊：pac auth create、pac org select
最佳做法
以下所列是一些要在使用 Package Deployer 套件時遵循的最佳做法提示。
建立套件
建立套件時，開發人員必須：
- 確保套件組件已簽署。
部署套件
部署套件時，Dataverse 系統管理員必須：
- 堅持要求已簽署套件組件，讓您可以將組件追蹤至其來源。
- 先在生產前執行個體 (最好是生產執行個體的鏡像映像) 測試套件，然後在生產執行個體上執行套件。
- 備份生產執行個體，然後再部署套件。