为 Dynamics 365 Package Deployer 创建数据包

项目
03/03/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

Microsoft Dynamics CRM Package Deployer 使管理员能够在 Microsoft Dynamics 365 (online) 和 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 的 CRM 包部署程序集合更新到版本 8.1 或更高版本，更新现有包项目以利用新的功能集。

本主题内容

必备条件

创建数据包

部署数据包

创建和部署数据包的最佳实践

必备条件

确保您拥有要包括在数据包中的所有解决方案和文件。
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 Package Manager
包含数据包模板的 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 并创建一个新项目。
在“新项目”对话框中：
1. 从安装模板列表中，展开“Visual C#”，然后选择“Dynamics 365 SDK 模板”。
2. 确保 .NET Framework 4.5.2 已选中。
3. 选择 “Dynamics 365 数据包”。
4. 指定项目的名称和位置，然后单击“确定”。

步骤 2：将文件添加到项目

在“Solutions Explorer”窗格中，在“PkgFolder”文件夹下添加您的解决方案和文件。
对于要添加到“PkgFolder”文件夹下的每个文件，在“属性”窗格中，将“复制到输入目录”值设置为“始终复制”。这可确保您的文件可在生成的程序包中可用。

步骤 3：更新 HTML 文件：英语和其他语言

在“Solution Explorer”窗格中，展开 PkgFolder > Content > en-us。您可以找到两个名为 EndHTML 和 WelcomeHTML 的文件夹。这些文件夹包含 HTML 和关联文件，可使您能够在程序包部署流程开始和结束时显示信息。编辑这些文件夹的 HTML 文件夹中的文件，为您的程序包添加信息。
您还可以添加在您的数据包中添加其他语言的 HTML 文件，这样 HTML 中的内容会在用户的计算机的区域设置上以那种语言显示。为此：
1. 创建 PkgFolder > Content 下的 en-us 文件夹的副本。
2. 将复制的文件夹重命名为相应的语言。例如，若为西班牙语，则将其重命名为“es-ES”。
3. 修改 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 文件名，在提示您选择一个要在其解压缩文件内容的位置的数据包部署过程期间，添加一个屏幕。

这常用于为 Unified Service Desk for Microsoft Dynamics 365 创建数据包。有关 Unified Service Desk 的信息，请参阅 TechNet：Unified Service Desk 管理指南。

agentdesktopexename

在部署过程快结束时调用位于压缩文件或 URL 中的 .exe 或 .msi 文件的名称。

这常用于为 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> 节点。

<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	可以是压缩文件中的 exe 名称、URL 或 .msi 文件，在过程末尾调用链接。
datadelimiter	导入文件中所使用的数据分隔符的名称。有效值是 singlequote 或 doublequotes。
fielddelimiter	导入文件中所使用的字段分隔符的名称。有效值是 comma、colon 或 singlequote。
enableduplicatedetection	指示是否对数据导入启用重复检测功能。有效值为“true”或“false”。
isfirstrowheader	用于指示导入文件的第一行包含字段名称。有效值是 true 或 false。
isrecordownerateam	指示导入记录的所有者是否应为团队。有效值是 true 或 false。
owneruser	指示应拥有记录的用户 ID。默认值是当前登录用户。
waitforimporttocomplete	如果 true，则系统在继续之前等待导入完成。如果 false，则对作业进行排队然后继续。

<zipimportdetails> 节点

该节点包含一个描述包含在用于导入到 Dynamics 365 中的压缩文件中的 <zipimportdetail> 节点阵列。

<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	可以是压缩文件中的 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 方法（下文进行解释）定义您的自定义逻辑，以基于使用运行时设置（下文进行解释）指定的区域 ID (LCID) 值导入本地化配置数据文件而不是默认文件（在 crmmigdataimportfile 中指定）。

单击“保存全部”。

以下表示示例 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：为您的数据包定义自定义代码

在“Solution Explorer”窗格中，双击位于根的 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	旧解决方案指南。
newSolutionId	新解决方案指南。

在解决方案在 BeforeImportStage 方法的替代定义中完成导入前，输入要执行的自定义代码。示例数据和在 ImportConfig.xml 文件中指定的解决方案的某些平面文件在解决方案导入完成之前导入。
使用 OverrideConfigurationDataFileLanguage 的替代方法定义替代配置数据导入当前选择的语言。如果指定语言的指定区域设置 ID (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"; }
}
```
在您选择了要安装的程序包之后，会在下一页上显示数据包长名称。

此外，数据包可以使用以下函数和变量：

客户	类型	说明
CreateProgressItem	函数	用于在用户界面中 (UI) 创建新的流程项目。
RaiseUpdateEvent	函数	曾用于更新通过调用到 CreateProgressItem 而创建的进度。 ProgressPanelItemStatus 是一个枚举： `public enum ProgressPanelItemStatus { Working = 0, Complete = 1, Failed = 2, Warning = 3, Unknown = 4 }`
RaiseFailEvent	函数	用于因异常消息而导致当前状态导入失败的情况。
IsRoleAssoicatedWithTeam	函数	用于确定角色是否与指定的团队相关联。
IsWorkflowActive	函数	用于确定指定的工作流是否可用。
PackageLog	类指针	这是指向数据包的初始化登录界面的指针。数据包利用此界面将消息和异常情况记录到包日志文件。
RootControlDispatcher	属性	此为调度程序界面，用于在包部署期间允许控件呈现自己的 UI。使用此界面可以包含所有 UI 元素或命令。在使用此变量之前，很有必要为空值检查变量，因为可（或不可）将她设置为值。
CrmSvc	属性	这是一个指向允许数据包在数据包内使用 Dynamics 365 的 CrmServiceClient 类的指针。使用此方法执行 Dynamics 365 SDK 以及替代方法中的其他操作。
DataImportBypass	属性	使用此方法指定 CRM 包部署程序是否跳过所有数据导入操作，如导入 Dynamics 365 示例数据、平面文件数据，以及从配置迁移工具导出的数据。指定 true 或 false。默认值为 false。
OverrideDataImportSafetyChecks	属性	使用此功能指定 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

通过

为 Dynamics 365 Package Deployer 创建数据包

本主题内容

必备条件

创建数据包

步骤 1：使用模板创建项目

步骤 2：将文件添加到项目

步骤 3：更新 HTML 文件：英语和其他语言

步骤 4：为数据包指定配置值。

步骤 5：为您的数据包定义自定义代码

部署数据包

创建和部署数据包的最佳实践

另请参阅

其他资源