为 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 package init 命令创建初始包。 有关详细信息,请参阅 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 文件夹和 PackageImportExtension.cs 文件中找到 ImportConfig.xml 配置文件。 您将按照本文后面的描述修改这些文件。

添加包文件

创建包项目后,可以开始向该项目添加解决方案和其他文件。

使用 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 参考。

添加自定义代码

您可以添加在包导入环境之前、期间和之后运行的自定义代码。 若要添加自定义代码,请按照以下说明操作:

  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 指定在运行包部署程序工具导入包时是否跳过安全检查。 有关详细信息,请参阅使用包部署器和 Windows PowerShell 部署包。

    2. 输入要在 PreSolutionImport 的替代方法定义中导入解决方案之前运行的自定义代码。 使用此方法指定在更新目标 Dataverse 实例中的指定解决方案时是保留还是覆盖自定义项,以及是否自动激活插件和工作流。

    3. 使用 RunSolutionUpgradeMigrationStep 的替代方法定义,以在解决方案的两个版本之间执行数据转换或升级。 仅当要导入的解决方案已存在于目标 Dataverse 实例中时,此方法才会运行。

      该功能需要以下参数:

      参数 Description
      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 属性中指定默认配置数据导入文件。

      跳过数据检查 (OverrideDataImportSafetyChecks = true) 此时可能有效,前提是您确保目标 Dataverse 实例不包含任何数据。

    7. 输入在 AfterPrimaryImport 方法的重写定义中于导入完成后运行的自定义代码。 该工具会在解决方案导入开始之前,导入之前尚未导入的其余平面文件。

    8. 将包文件夹的默认名称更改为您想要的包名称。 为此,请在 解决方案资源管理器 窗格中重命名 PkgFolder 或 PkgAssets 文件夹,然后在 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 类型 Description
    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 元素或命令。 在使用该变量之前检查此变量是否为 null 值,因为它可能尚未被赋值。
    CrmSvc 财产 一个指向允许包在包内使用 Dynamics 365 的 CrmServiceClient 类的指针。 将此指针用于执行 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 中为包文件夹选择的名称匹配。 此文件夹包含所有解决方案、配置数据、平面文件和您的数据包的内容。

注释

您可能会看到包含 pdpublish 文件夹的 .NET 文件夹(例如 net472)。 DLL 和其他项目文件位于该 pdpublish 文件夹中。

  • <PackageName>.dll:程序集包含包的自定义代码。 默认情况下,程序集的名称与项目名称匹配。

部署

创建包后,请使用包部署器工具、Windows PowerShell 或 CLI 命令在 Dataverse 实例上部署它。

  • 若要使用包部署器工具进行部署,请先按 Dataverse 开发工具 中所述下载该工具。 接下来,请参阅文章使用包部署器或 Windows PowerShell 部署包中的详细信息,了解包部署的具体步骤。

  • 若要使用 CLI 进行部署,请使用 pac package deploy 命令。

    > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
    

    注释

    若要使用 CLI 将包部署到目标环境,必须先设置身份验证配置文件并选择组织。 有关详细信息,请参阅 pac auth create 和 pac org select。

最佳做法

下面列出了使用 Package Deployer 包时需要遵循的一些最佳做法提示。

创建包

创建包时,开发人员必须:

  • 确保已签署包程序集。

部署包

在部署包时,Dataverse 管理员必须:

  • 坚持使用已签名包的程序集,以便跟踪程序集回到其源。
  • 在生产实例上运行包之前,在预生产实例(最好是生产实例的镜像)上对其进行测试。
  • 在部署包之前对生产实例进行备份。

另请参阅

解决方案包生成工具