建立 Dynamics 365 Package Deployer 的套件
發佈日期： 2017年1月
適用對象： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online
Microsoft Dynamics CRM Package Deployer 可讓系統管理員在 Microsoft Dynamics 365 (線上) 和 Dynamics 365 (內部部署) 執行個體上部署套件。 「套件」可以包含下列任何或所有項目：
一個或多個 Dynamics 365 解決方案檔案。
一般檔案或從設定移轉工具匯出的組態資料檔案。 如需此工具的詳細資訊，請參閱TechNet：管理您的設定資料。
可以在套件部署到 Dynamics 365 執行個體之前、期間或之後執行的自訂程式碼。
套件所特有、可在部署程序開始和結束時顯示的 HTML 內容。 這可提供套件中部署的解決方案和檔案的描述。
Microsoft Dynamics 365 會提供您建立這些套件的 Visual Studio 範本，這個範本可以搭配 套件部署器工具 用來將套件部署至 Dynamics 365 執行個體。
備註
在 CRM Online 2016 更新 1 和 CRM 2016 Service Pack 1 (內部部署) 版本中，建立 Dynamics 365 套件的 Visual Studio 範本經過強化可支援新功能，像是執行階段參數支援、使用單一套件匯入多種語言設定檔、能夠控制更新解決方案時要覆寫或是維護自訂，以及其他功能。 可更新現有的套件專案，以利用使用 NuGet 8.1 版或更新版本更新的 CRM 套件部署器 組件設定的新功能。
本主題內容
先決條件
建立套件
部署套件
建立和部署套件的最佳作法
先決條件
確定您已準備好所有要包含在套件中的方案與檔案。
Microsoft .NET Framework 4.5.2
Microsoft Visual Studio 2012、Visual Studio 2013 或 Visual Studio 2015
Visual Studio 2012、Visual Studio 2013 或 Visual Studio 2015 的 NuGet 套件管理員
包含套件範本之 Visual Studio 的Microsoft Dynamics 365 SDK 範本。 您可以用下列其中一個方式取得它：
下載 CRM SDK 範本，並按兩下 CRMSDKTemplates.vsix 檔案，將範本安裝在 Visual Studio 中。
下載並解壓縮 CRM SDK 套件。 範本檔案 CRMSDKTemplates.vsix 位於 SDK\Templates 資料夾中。 按兩下 CRMSDKTemplates.vsix 檔案，將範本安裝在 Visual Studio 中。
建立套件
執行下列五個步驟以建立套件：
步驟 1：使用範本建立專案
步驟 2：將檔案新增至專案
步驟 3：更新 HTML 檔案：英文和其他語言
步驟 4：指定套件的設定值
步驟 5：定義套件的自訂程式碼
步驟 1：使用範本建立專案
啟動 Microsoft Visual Studio 並建立新的專案。
在 [新增專案] 對話方塊：
在已安裝範本的清單中，展開 [Visual C#] 並選擇 [Dynamics 365 SDK 範本]。
確定已選取 .NET Framework 4.5.2。
選取 [Dynamics 365 套件]。
指定專案的名稱和位置，並按一下 [確定]。
.jpeg "建立自訂套件的新專案")
步驟 2：將檔案新增至專案
在 [方案總管] 窗格中，將您的方案與檔案新增至 PkgFolder 資料夾下。
針對新增至 PkgFolder 資料夾下的每個檔案，在 [屬性] 窗格中，將 [複製到輸出目錄] 值設定為 [永遠複製]。 這可確保您的檔案會出現在產生的套件中。
步驟 3：更新 HTML 檔案：英文和其他語言
在 [方案總管] 窗格中，展開 [PkgFolder] > [Content] > [en-us]。 您會找到兩個資料夾，名稱為 WelcomeHTML 和 EndHTML。 這些資料夾包含 HTML 與關聯檔案，可讓您在套件部署程序結束及開始時顯示資訊。 編輯以這些資料夾之 HTML 資料夾中的檔案，以加入套件的資訊。
您也可以在套件中新增其他語言的 HTML 檔案，讓 HTML 的內容根據使用者電腦的地區設定，以適當的語言來顯示。 若要執行此操作：
在 [PkgFolder] > [Content] 底下，建立 en-us 資料夾的複本。
將複製的資料夾重新命名為適當的語言。 例如，若為西班牙文，則重新命名為 es-ES。
修改 HTML 檔案內容以新增西班牙文內容。
步驟 4：指定套件的設定值
在位於 PkgFolder 的 ImportConfig.xml 檔案中新增套件的相關資訊，以定義套件設定。 按兩下檔案，將它開啟以進行編輯。 下表列出設定檔中有關每個參數及節點的相關資訊。
參數/節點
描述
installsampledata
True 或 false。 如果為 true，則將範例資料安裝到 Dynamics 365 執行個體。 這與您可以從 Dynamics 365 的 [設定] > [資料管理] 區域安裝的範例資料相同。
waitforsampledatatoinstall
true 或 false。 如果為 true，而且 [installsampledata] 也設定為 true，請先等待範例資料完成安裝，再部署套件。
備註
如果您要將 waitforsampledatatoinstall 設定為 true，則務必將 [installsampledata] 設定為 true。
agentdesktopzipfile
要解壓縮的 ZIP 檔案的名稱。 如果您在此處指定 .zip 檔案名稱，則會在套件部署程序中新增畫面，提示您選取要解壓縮檔案內容的位置。
這通常用於建立 Unified Service Desk for Microsoft Dynamics 365 的套件。 如需Unified Service Desk的詳細資訊，請參閱 TechNet：Unified Service Desk 管理指南 (英文)。
agentdesktopexename
要在部署程序結束時叫用的 ZIP 檔案中 .exe 或 .msi 檔案的名稱或一個 URL。
這通常用於建立 Unified Service Desk 的套件。
crmmigdataimportfile
使用 設定移轉工具 匯出的預設組態資料檔 (.zip) 的檔案名稱。
您也可以在執行 Package Deployer 的同時，使用新的執行階段設定匯入組態資料檔的翻譯版本，依據指定的地區設定 ID (LCID)。 使用 <cmtdatafile> 節點 (稍後說明) 指定套件中組態資料檔的翻譯版本，然後使用 OverrideConfigurationDataFileLanguage 方法 (稍後說明) 依據指定的地區設定 ID 指定，使用執行階段設定匯入組態資料檔的邏輯。 您無法使用套件一次匯入多個組態資料檔。
對於 Dynamics 365 (內部部署)，如果您的組態資料檔包含使用者資訊，而且來源和目標 Dynamics 365 執行個體位於相同的 Active Directory 網域，則使用者資訊會匯入目標 Dynamics 365 執行個體。 若要將使用者資訊匯入不同網域的 Dynamics 365 (內部部署) 執行個體，則必須在專案中包括使用 設定移轉工具 產生的使用者對應檔 (.xml)，並使用稍後說明的 <cmtdatafile> 節點中的 usermapfilename 屬性指定它以及組態資料檔。 使用者資訊無法匯入 Dynamics 365 (線上) 執行個體中。
<solutions> 節點
包含描述要匯入之方案的 <configsolutionfile> 節點陣列。 這個節點下的方案的順序代表在目標 Dynamics 365 執行個體上匯入方案所依照的順序。
<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>filestoimportnode> 節點
包含 <configimportfile> 與 <zipimportdetails> 節點的陣列，這些節點分別用來描述要匯入的個別檔案和 ZIP 檔案。
<configimportfile> 節點
在 <configimportfile> 節點下使用這個節點，描述要匯入至 Dynamics 365 的檔案。 您可以新增多個 <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
要用於這個檔案的 Dynamics 365 匯入資料對應的名稱。 如果空白，請嘗試為這個檔案使用系統決定的匯入資料對應名稱。
importtoentity
可以是 ZIP 檔案中 exe 的名稱、URL 或 .msi，以便提供要在程序結束時叫用的連結。
datadelimiter
用於匯入檔案的資料分隔符號名稱。 有效值為 singlequote 或 doublequotes。
fielddelimiter
用於匯入檔案的欄位分隔符號名稱。 有效值為 comma 或 colon 或 singlequote。
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> 節點下使用這個節點，提供要在 Dynamics 365 中匯入之個別對應檔的相關資訊。
<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 方法 (稍後說明) 中定義自訂邏輯來匯入翻譯的組態資料檔，而非預設檔案 (在 crmmigdataimportfile 中指定)，依據指定的地區設定 ID (LCID) 值。使用執行階段設定 (稍後說明)。
按一下 [全部儲存]。
下列範例顯示範例 ImportConfig.xml 檔案的內容。
<?xml version="1.0" encoding="utf-16"?> <configdatastorage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://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>
步驟 5：定義套件的自訂程式碼
在 [方案總管] 窗格中，按兩下位於根目錄的 PackageTemplate.cs 檔案以進行編輯。
在 PackageTemplate.cs 檔案中，您可以：
輸入要在套件於 InitializeCustomExtension 的覆寫方法定義中進行初始化時執行的自訂程式碼。
此方法可讓使用者在執行套件時，使用執行階段參數。 身為開發人員，您可以使用 RuntimeSettings 屬性將任何執行階段參數支援新增至套件，只要您有程式碼可根據使用者輸入處理它。
例如，下列範例程式碼會啟用稱為 SkipChecks 的套件執行階段參數，其擁有兩個可能的值：true 或 false。 範例程式碼會檢查使用者是否在執行 CRM 套件部署器 時已指定任何執行階段參數 (使用命令列或 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 指定是否要略過安全性檢查，在執行 套件部署器工具 匯入套件時。 其他資訊：TechNet：使用 CRM Package Deployer 和 Windows PowerShell 部署套件
在 PreSolutionImport 的覆寫方法定義中輸入要在匯入解決方案之前執行的自訂程式碼，以指定要維護或覆寫自訂，在更新目標 Dynamics 365 執行個體中指定的解決方案時，以及是否要自動啟用外掛程式及工作流程。
使用 RunSolutionUpgradeMigrationStep 的覆寫方法定義，在解決方案有兩種版本之間執行資料轉換或升級。 此方法只有在您要匯入的解決方案已存在目標 Dynamics 365 執行個體中時才會呼叫。
這個函數必須有下列參數：
參數
描述
solutionName
方案的名稱
oldVersion
舊方案的版本號碼
newVersion
新方案的版本號碼
oldSolutionId
舊方案的 GUID。
newSolutionId
新方案的 GUID。
在 BeforeImportStage 方法的覆寫定義中，輸入要在解決方案匯入完成之前執行的自訂程式碼。 在 ImportConfig.xml 檔案中指定的解決方案的範例資料以及某些一般資料，會在解決方案匯入完成之前匯入。
使用 OverrideConfigurationDataFileLanguage 的覆寫方法定義覆寫目前針對組態資料匯入選取的語言。 如果所指定語言的指定地區設定識別碼 (LCID) 在套件的可用語言清單中找不到，則會匯入預設資料檔案。
您可以在 ImportConfig.xml 檔案的 <cmtdatafiles> 節點中，指定組態資料的可用語言。 預設的組態資料匯入檔案是在 ImportConfig.xml 檔案的 crmmigdataimportfile 屬性中指定。
在此處略過資料檢查 (OverrideDataImportSafetyChecks = true) 可能很有效，如果您確定目標 Dynamics 365 執行個體未包含任何資料。
在 AfterPrimaryImport 方法的覆寫定義中，輸入要在匯入完成之後執行的自訂程式碼。 在解決方案匯入開始之前，先前未匯入的其餘一般檔案，現在才會匯入。
將套件資料夾的預設名稱從 PkgFolder 變更為您想要的套件名稱。 若要這麼做，請重新命名 [方案總管] 窗格中的 [PkgFolder] 資料夾，然後編輯 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"; }這是會在 CRM 套件部署器 精靈中出現於套件選取頁面上的套件名稱。
編輯 GetImportPackageDescriptionText 屬性下的傳回值，以變更套件描述。
public override string GetImportPackageDescriptionText { get { return "Package Description"; } }這是會在 Package Deployer 精靈的套件選取頁面上出現於套件名稱旁邊的套件描述。
編輯 GetLongNameOfImport 屬性下的傳回值，以變更套件完整名稱。
public override string GetLongNameOfImport { get { return "Package Long Name"; } }套件完整名稱會在您選取要安裝的套件之後，出現於下一個頁面。
此外，套件還可以使用下列函數和變數：
名稱
類型
描述
函數
用來在使用者介面 (UI) 中建立新的進度項目。
函數
用來更新藉由呼叫 CreateProgressItem 所建立的進度。
public enum ProgressPanelItemStatus { Working = 0, Complete = 1, Failed = 2, Warning = 3, Unknown = 4 }函數
用來使目前的狀態匯入失敗，並產生例外狀況訊息。
函數
用來判斷角色是否與特定團隊有關聯。
函數
用來判斷指定的工作流程是否在使用中。
類別指標
這是套件之初始化記錄介面的指標。 套件會使用這個介面，將訊息和例外狀況記錄到套件記錄檔。
屬性
這是用來讓控制項在套件部署期間轉譯其本身 UI 的發送器介面。 使用此介面來包裝任何 UI 元素或命令。 由於不一定會將這個變數設定為某個值，請務必在使用該變數之前檢查其值是否為 null。
屬性
這是 CrmServiceClient 類別的指標，讓套件可以從套件中定址 Dynamics 365。 這可用來執行 Dynamics 365 SDK 和覆寫方法中的其他動作。
屬性
這可用來指定 CRM 套件部署器 是否略過所有資料匯入作業，例如匯入 Dynamics 365 範例資料、一般檔案資料，以及從 設定移轉工具 匯出的資料。 指定 true 或 false。 預設值為 false。
屬性
這可用來指定 CRM 套件部署器 是否將略過部分安全檢查，這樣有助於改善匯入效能。 指定 true 或 false。 預設值為 false。
只有在目標 Dynamics 365 執行個體未包含任何資料時，才應將此設定為 true。
儲存您的專案，然後建置它 ([建置] > [建置方案]) 來建立套件。 您的套件是位於 <Project>\Bin\Debug 資料夾下的下列檔案。
<PackageName> 資料夾：資料夾名稱與您在本節的步驟 2.g 中變更的套件資料夾名稱相同 (步驟 5：定義套件的自訂程式碼)。 此資料夾包含所有解決方案、組態資料、一般檔案及套件內容。
<PackageName>.dll：此組件包含套件的自訂程式碼。 根據預設，這個組件的名稱與您的 Visual Studio 專案名稱相同。
下一步是部署套件。
部署套件
建立套件之後，您可以使用 套件部署器工具 或 Windows PowerShell，將該套件部署在 Dynamics 365 執行個體上。 如需詳細資訊，請參閱 TechNet：使用 CRM Package Deployer 或 Windows PowerShell 部署套件 (英文)。
建立和部署套件的最佳作法
建立套件時，開發人員必須確保套件組件已簽署。
部署套件時，Dynamics 365 系統管理員必須：
堅持簽署的套件組件，以便追蹤到組件的來源。
先在生產前執行個體 (最好是生產執行個體的鏡像映像) 測試套件，然後在生產執行個體上執行套件。
先備份生產執行個體，再部署套件。
另請參閱
開發人員適用的新功能：Microsoft Dynamics 365
Microsoft Dynamics 365
© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權