意見反映

建立 Package Deployer 工具的套件

  • 文章

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

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

Visual Studio 2015 或更新版本的範本 (可供下載) 可用於建立套件。 建立套件之後，使用 Package Deployer 工具，將您的套件部署至 Dataverse 執行個體。

先決條件

建立套件

執行下列五個步驟以建立套件：

步驟 1：使用範本建立專案

  1. 啟動 Visual Studio 並建立新的專案。

  2. 在 新增專案 對話方塊：

    1. 在已安裝範本的清單中，展開 Visual C# 並選擇 Dynamics 365 SDK 範本。
    2. 確定已選取 .NET Framework 4.6.2。
    3. 選取 Dynamics 365 套件。
    4. 指定專案的名稱和位置，並按一下 確定。

    建立自訂套件的新專案。

步驟 2：將檔案新增至專案

  1. 在 方案總管 窗格中，將您的方案與檔案新增至 PkgFolder 資料夾下。
  2. 針對新增至 PkgFolder 資料夾下的每個檔案，在 屬性 窗格中，將 複製到輸出目錄 值設定為 永遠複製。 這可確保您的檔案會出現在產生的套件中。

步驟 3：更新 HTML 檔案：英文和其他語言

  1. 在 [方案總管] 窗格中，展開 PkgFolder > 內容 > en-us。 您會找到兩個資料夾，名稱為 WelcomeHTML 和 EndHTML。 這些資料夾包含 HTML 與關聯檔案，可讓您在套件部署程序結束和開始時顯示資訊。 編輯這些資料夾之 HTML 資料夾中的檔案，以將套件的資訊加入。

  2. 您也可以在套件中新增其他語言的 HTML 檔案，讓 HTML 的內容根據使用者電腦的地區設定，以適當的語言來顯示。 若要執行此操作：

    1. 在 PkgFolder > 內容 底下建立 en-us 資料夾的複本。
    2. 將複製的資料夾重新命名為適當的語言。 例如，若為西班牙文，則重新命名為 es-ES。
    3. 修改 HTML 檔案內容以新增西班牙文內容。

步驟 4：指定套件的設定值

  1. 在位於 PkgFolder 的 ImportConfig.xml 檔案中新增套件的相關資訊，以定義套件設定。 按兩下檔案，將它開啟以進行編輯。 下列瀏覽器提供設定檔中有關每個參數及節點的資訊。

    installsampledata
    True 或 false。 如果為 true，則將範例資料安裝到 Dataverse 執行個體。 這與您可從 Dataverse 的 設定 > 資料管理 區域安裝的範例資料相同。

    waitforsampledatatoinstall
    true 或 false。 如果為 true，而且 installsampledata 也設定為 true，請先等待範例資料完成安裝，再部署套件。

    備註

    如果您要將 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
    使用設定移轉工具所匯出之預設組態資料檔 (.zip) 的檔案名稱。

    • 您也可以在執行 Package Deployer 的同時，使用新的執行階段設定匯入組態資料檔的翻譯版本，依據指定的地區設定 ID (LCID)。 使用 <cmtdatafile> 節點 (稍後說明) 指定套件中組態資料檔的翻譯版本，然後使用 OverrideConfigurationDataFileLanguage 方法 (稍後說明) 依據指定的地區設定 ID 指定，使用執行階段設定匯入組態資料檔的邏輯。 您無法使用套件一次匯入多個組態資料檔。

    • 對於 Dataverse (內部部署)，如果您的組態資料檔包含使用者資訊，而且來源和目標 Dataverse 執行個體位於相同的 Active Directory 網域，則使用者資訊會匯入目標 Dataverse 執行個體。 若要將使用者資訊匯入不同網域的 Dataverse (內部部署) 執行個體，則必須在專案中加入使用設定移轉工具所產生的使用者對應檔 (.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 用於匯入檔案的資料分隔符號名稱。 有效值為 singlequote 或 doublequotes。
    fielddelimiter 用於匯入檔案的欄位分隔符號名稱。 有效值為逗號或冒號或 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> 節點下使用這個節點，提供要在 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 中指定)。

  2. 按一下 全部儲存。

    下列範例顯示範例 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>

步驟 5：定義套件的自訂程式碼

  1. 在 [方案總管] 窗格中，按兩下位於根目錄的 PackageTemplate.cs 檔案以進行編輯。

  2. 在 PackageTemplate.cs 檔案中，您可以：

    1. 輸入要在套件於 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 來部署套件

    2. 在 PreSolutionImport 的覆寫方法定義中輸入要在匯入解決方案之前執行的自訂程式碼，以指定要維護或覆寫自訂，在更新目標 Dataverse 執行個體中指定的解決方案時，以及是否要自動啟用外掛程式及工作流程。

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

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

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

    4. 在 BeforeImportStage 方法的覆寫定義中，輸入要在解決方案匯入完成之前執行的自訂程式碼。 在 ImportConfig.xml 檔案中指定的解決方案的範例資料以及某些一般資料，會在解決方案匯入完成之前匯入。

    5. 使用 OverrideConfigurationDataFileLanguage 的覆寫方法定義覆寫目前針對組態資料匯入選取的語言。 如果所指定語言的指定地區設定識別碼 (LCID) 在套件的可用語言清單中找不到，則會匯入預設資料檔案。

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

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

    6. 在 AfterPrimaryImport 方法的覆寫定義中，輸入要在匯入完成之後執行的自訂程式碼。 在解決方案匯入開始之前，先前未匯入的其餘一般檔案，現在才會匯入。

    7. 將套件資料夾的預設名稱從 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";  
}  
}

    8. 編輯 GetNameOfImport 屬性下的傳回值，以變更套件名稱。

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

      這是會在 Dynamics 365 Package Deployer 精靈中出現於套件選取頁面的套件名稱。

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

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

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

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

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

      套件完整名稱會在您選取要安裝的套件之後，出現於下一個頁面。

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

    名稱 類型 描述
    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 範例資料、一般檔案資料，以及從設定移轉工具匯出的資料。 指定 true 或 false。 預設值為 false。
    OverrideDataImportSafetyChecks 屬性 使用此屬性來指定 Dynamics 365 Package Deployer 是否略過部分安全檢查，這樣有助於改善匯入效能。 指定 true 或 false。 預設值為 false。

    只有在目標 Dataverse 執行個體未包含任何資料時，才應將此設定為 true。

  4. 儲存您的專案，然後建置它 (建置 > 建置方案) 來建立套件。 您的套件是位於 <Project> \Bin\Debug 資料夾中的下列檔案

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

    • <PackageName>.dll：此組件包含套件的自訂程式碼。 根據預設，這個組件的名稱與您的 Visual Studio 專案名稱相同。

      下一步是部署套件。

部署套件

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

Package Deployer 工具是做為 Microsoft.CrmSdk.XrmTooling.PackageDeployment NuGet 套件的一部分進行散發。 若要下載 Package Deployer 工具，請參閱從 NuGet 下載工具。

如需詳細資訊，請參閱使用 Package Deployer 或 Windows PowerShell 來部署套件。

建立和部署套件的最佳作法

建立套件時，開發人員必須確保套件組件已簽署。

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

  • 堅持簽署的套件組件，以便追蹤到組件的來源。
  • 先在生產前執行個體 (最好是生產執行個體的鏡像映像) 測試套件，然後在生產執行個體上執行套件。
  • 先備份生產執行個體，再部署套件。

請參閱

解決方案封裝工具

備註

是否能請您告知您偏好的慣用文件語言？ 請填寫問卷。 (請注意，本問卷為英文版)

完成問卷大約需要七分鐘。 本問卷將不會收集個人資料 (隱私權聲明)。