调试代码组件

本文介绍如何在开发期间以及部署到 Microsoft Dataverse 之后调试代码组件。 使用单元测试独立于Power Apps组件框架运行时来验证组件逻辑。

本文介绍了如何使用测试框架调试代码组件，以及部署到 Microsoft Dataverse 后的调试方法：

使用浏览器测试工具调试代码组件

在实现代码组件逻辑时，使用 npm start 或 npm start watch 生成代码组件并在新的浏览器窗口中打开本地测试工具。 此测试工具是Microsoft Power Platform CLI 的一部分，因此，无论是否打算在模型驱动应用、画布应用或门户中使用代码组件，都是相同的。 详细信息： 创建第一个组件。

Note

在使用 npm start 之前，需要检查计算机中是否安装了 npm。

下图展示了使用 npm start watch 进行 DataSetGrid 示例时 Visual Studio Code 的界面：

在监视模式下运行 DataSetGrid 组件的Visual Studio Code屏幕截图。

以 watch 模式启动测试工具架后，您可以快速直观看到更改的实际效果。 对以下任何组件资产所做的更改会自动反映在测试工具中，而无需重启它：

  1. index.ts 文件。
  2. index.ts 中导入的模块（不包括 node_modules）。
  3. 文件中列出的 ControlManifest.Input.xml 所有资源，例如， css/DataSetGrid.css 或 strings/DataSetGrid.1033.resx

如果对其中任何文件进行更改，你将看到一 Change detected 条消息，浏览器会使用更新的代码重新加载。

检测到代码组件变更后重新加载的测试框架屏幕截图。

下图显示了测试框架在新的浏览器窗口中打开后的样子：

浏览器测试工具的屏幕截图，其中包含代码组件和输入面板。

如上图所示，浏览器窗口随即打开以显示四个区域。 代码组件在左窗格中呈现，而右窗格有三个部分，具体取决于正在调试的组件类型：

  • 所有代码组件类型都显示上下文输入：

    • 外形规格：提供一种方法来指定外形规格，并使用每个外形规格（Web、平板电脑、手机）测试代码组件。 当代码组件根据加载组件的位置更改其布局时，外形规格非常有用。 可以使用 在代码中检测外形规格。
    • 组件容器宽度和高度：最初，宽度和高度为空。 这会将代码组件置于没有宽度或高度 CSS 样式集的容器 div 中。 如果提供宽度或高度，则容器 div 的维度受限制，以便查看代码组件如何适应可用空间。 你需要在部署完成后于 Power Apps 中仔细测试代码组件的行为，因为其实际行为与测试工具中的行为并不完全相同。 此外，如果你的组件想要在 context.mode.trackContainerResize(true) 方法中接收 context.mode.allocatedHeightcontext.mode.allocatedWidth，则需要调用 updateView；不过，无论是否进行此调用，测试框架始终都会提供高度和宽度。 详细信息： trackContainerResize。

    Note

    使用测试工具时，allocatedWidth 和 allocatedHeight 将以文本形式而非数值形式提供。

  • 数据输入是一个交互式 UI，用于显示清单文件中定义的所有属性及其类型或类型组。 此区域的内容取决于其中 ControlManifest.Input.xml 定义的属性和数据集，并允许提供模拟数据进行测试。

  • Outputs 会在调用组件的 getOutputs 方法时渲染输出。

Note

如果要修改 ControlManifest.Input.xml 文件，则需要在输入部分显示任何其他属性或数据集之前重启调试过程。 可以通过在命令行中对正在运行的进程使用 Ctrl + c，然后再次运行 npm start watch 来执行此操作。

Important

使用 npm start 并 npm start watch 生成针对开发和调试优化的代码组件。 此代码通常不会部署到Microsoft Dataverse。 详细信息： 代码组件应用程序生命周期管理。

使用模拟数据测试代码组件

  • 对于包含 property 元素的 ControlManifest.Input.xml组件， “数据输入 ”部分显示每个值的输入框。

    测试框架中代码组件属性的“数据输入”字段截图。

  • 对于 数据集 类型组件，可以使用每个 数据集 元素的测试数据加载 CSV 文件。 直接从环境中手动创建或导出 .csv 格式。 加载 CSV 文件后，可以将在 ControlManifest.Input.xml CSV 文件中定义的每个属性集绑定到 CSV 文件中的列。 以下屏幕截图显示了如何通过为每个属性选择列来完成此绑定：

    测试框架中 CSV 列与数据集属性映射的截图。

  • 如果您未在 ControlManifest.Input.xml 文件中定义任何属性，则所有列都会自动加载到测试框架中。 以下屏幕截图显示了如何将数据类型分配给源 CSV 中每个列的代码组件：

    测试框架中 CSV 列所分配的数据类型的截图。

Note

加载 CSV 示例数据集时，必须在加载数据之前选择 “应用 ”。 如果数据集定义了属性集元素，则必须将每个元素映射到 CSV 中的列，然后才能选择 “应用”。 这些设置不会被保存，因此每次代码更改后，在测试框架重新加载之后，都必须重新设置。

使用测试框架时的常见限制

虽然测试工具适用于测试简单的代码组件，但以下方案可能意味着测试工具不能用于测试更复杂的代码组件：

  1. 在测试框架数据输入部分中更改属性时，updatedProperties数组不会被填充。
  2. 使用 ControlManifest.Input.xml 中 feature-usage 部分列出的功能。 例如，在测试工具内部调用 context.WebApi.* 方法时会抛出异常。
  3. 对数据集使用 分页、 排序和 筛选 API 会在测试工具中引发异常。
  4. 使用提供更多元数据的复杂数据类型绑定，例如选择和查找。 对于选择列，测试工具提供三个简单选项，其中包含最少的元数据。
  5. 模型驱动应用的具体信息，例如字段级别安全性、只读行为、数据集选择 API 以及与模型驱动应用命令栏的集成。
  6. 其他上下文 API，例如 导航 和 实用工具 方法。

若要测试这些场景，您需要先部署代码组件，然后使用部署到 Microsoft Dataverse 后调试代码组件中所述的技术进行测试

使用浏览器开发人员工具调试代码组件

新式浏览器具有一组内置的开发人员工具，可用于检查在当前页上加载的 HTML、CSS 和 JavaScript。 可以使用键盘快捷方式Ctrl++ShiftI访问这些开发人员工具。 F12使用键也是打开开发人员工具的常用键盘快捷方式，但由于此快捷方式已用于下载应用键盘快捷方式，因此此快捷方式在 Power Apps Studio 中不起作用。

将代码组件与 Webpack 捆绑在一起

使用 TypeScript 编写代码组件时，代码可能与发送到捆绑代码组件输出的 JavaScript 不同。 当您运行 npm start 或 npm start watch 时，pcf-scripts 模块（通过运行 pac pcf init 添加到 packages.json 中）会使用 Webpack 将多个 TypeScript 文件构建为 out 文件夹内的单个 bundle.js 文件。 此文件夹还包含由你的ControlManifest.xml引用的任何其他资源（例如 html/css），包括清单本身，只是其名称为ControlManifest.Input.xml。

当你使用现代 TypeScript 语言功能（例如 import/export 或 async/await），而 JavaScript 的目标标准（例如 ES5）又不支持这些功能时，构建过程会将 TypeScript 转译为不使用这些语言功能的 JavaScript。 作为开发版本的一部分输出的源映射，向开发人员工具提供信息，以便 TypeScript 中的断点位置可以映射到相应的 JavaScript 行。 同样，当发生异常或您逐步调试代码时，您将看到原始的 TypeScript 代码行，而不是底层的转译后的 JavaScript 代码。

打包的另一个特性是，当你使用 npm install 引入外部模块时，构建过程会利用关联的 bundle.js 目录中的内容，将所需模块添加到代码组件的 node_modules 中。 因此，使用的任何外部模块都必须以捆绑的方式打包。 详细信息： 最佳做法：模块导入。

Note

只有在以开发模式运行构建时，才会输出源映射，而且生成的文件会比生产构建产物大得多。 因此，不建议将代码组件构建为开发用途后再进行部署。 详细信息：应用程序生命周期管理（ALM）。

使用开发人员工具调试代码组件

本部分介绍如何在Microsoft Edge开发人员工具中调试代码组件：

  1. 使用以下任一方法将代码组件加载到浏览器会话中：

    1. 使用 npm start watch 的测试框架。
    2. 将代码组件的本地开发构建加载到模型驱动应用、画布应用或门户浏览器会话中。 无需将代码组件的开发版本部署到 Dataverse 服务器。 或者，您可以按照部署到 Microsoft Dataverse 后调试代码组件中所述，使用 Fiddler 自动响应器。

  2. 选择Ctrl + + ShiftI以打开开发人员工具。

  3. 在开发人员工具面板中选择“ 源 ”选项卡。

  4. 使用 Ctrl + P 显示 “打开文件”命令面板。 您还可以从省略号菜单中选择打开文件。

  5. 输入控件的名称（这是 在 pac pcf init 中使用的控件的名称）。

  6. 在列出的匹配项中，选择与 webpack://pcf_tools_652ac3f36e1e4bca82eb3c1dc44e6fad/./DataSetGrid/index.ts 类似的文件。

    Microsoft Edge DevTools 的屏幕截图，其中显示了代码组件 TypeScript 源文件。

  7. 找到函数 updateView 并在第一行上放置断点。

  8. 对绑定到代码组件的属性进行更改。 在测试工具中，可以使用属性面板更改属性；或者在 Power Apps 中更改绑定的属性或数据集。 更改属性会触发对 updateView. 的调用。

  9. 此时您将看到断点被触发，并可检查代码。

    Microsoft Edge DevTools 在 updateView 断点处暂停时的屏幕截图。

  10. 您还可以通过元素选项卡检查组件生成的 HTML 元素和 CSS。如果您对特定交互（如根容器元素）感兴趣，可以在选中根元素时，通过上下文菜单在 HTML DOM 元素上设置断点>在>子树修改时暂停

    Microsoft Edge DevTools 中“在子树修改时暂停”菜单的截图。

ES5 与 ES6

目前，默认情况下，代码组件配置为转译到 ES5 JavaScript，以便支持较旧的浏览器。 如果不需要支持较旧的浏览器，可以通过在项目的 target 中将 tsconfig.json 设置为 ES6 来把目标更改为 ES6：

{
  "extends": "./node_modules/pcf-scripts/tsconfig_base.json",
  "compilerOptions": {
    "target": "ES6",
    "typeRoots": ["node_modules/@types"]
  }
}

Note

目前，源映射是根据每个 TypeScript 文件转译后的输出生成的，而不是根据源文件生成的。 如果 ES5 是目标，则由于删除了 ES6 语言功能（如类），源映射将更难阅读。 在支持 ES6 之前，即使需要输出 ES5，你也可以在开发时将 tsconfig.json 的目标设置为 ES6，这样源映射会更接近原始 TypeScript。 如果需要输出 ES5，请记住在生成代码组件以供生产部署之前将其设置回来。

在部署到Microsoft Dataverse后调试代码组件

若要在模型驱动应用、画布应用或门户的上下文中完整测试逻辑，可以先将代码组件部署并配置到 Microsoft Dataverse 中，然后使用 Fiddler 的 Auto Responder 功能，或使用 requestly。 在这两种情况下，你将在浏览器中加载代码组件（本地生成的）开发版本，而无需在调试代码时持续部署更改。 通过这种方式进行调试，您就可以针对下游的非开发环境进行调试，而无需先部署开发版本。

首先，请确保在Microsoft Dataverse中部署和配置组件。 理想情况下，应仅将代码组件的生产版本发布到Microsoft Dataverse中。 对于较大的代码组件，发布开发生成可能会导致 Web 资源大小过大错误。 由于我们将把代码组件的 bundle.js 重定向到本地构建的版本，因此，你可以更新你的 文件，通过将属性 .pcfproj 设置为 production，使其在使用 PcfBuildMode 时始终以生产模式构建。

<PropertyGroup>
  <Name>ReactStandardControl</Name>
  <ProjectGuid>0df84c56-2f55-4a80-ac9f-85b7a14bf378</ProjectGuid>
  <OutputPath>$(MSBuildThisFileDirectory)out\controls</OutputPath>
  <PcfBuildMode>production</PcfBuildMode>
</PropertyGroup>

使用 Fiddler 调试代码组件

使用 Fiddler 调试代码组件：

  1. 下载并安装 Fiddler 经典版

  2. 打开 Fiddler，然后从菜单栏中转到 “工具”，然后选择“ 选项”。

  3. 选中对话框中的 HTTPS 选项卡，选中“ 捕获 HTTPS CONNECTS 并 解密 HTTPS 流量 ”复选框，以便捕获并解密 HTTPS 流量。

    用于捕获和解密 HTTPS 流量的 Fiddler HTTPS 选项的屏幕截图。

  4. 选择“确定”关闭对话框。

    Note

    • 如果是首次启用此设置，Fiddler 将提示你安装证书。 安装证书并重启 Fiddler，使新设置生效。
    • 如果过去已运行 Fiddler 并收到 NET::ERR_CERT_AUTHORITY_INVALID 错误，请在 “HTTPS ”选项卡中选择“ 操作 ”按钮，然后选择 “重置所有证书”。 这还会显示要安装的新证书的多个提示。

  5. 在右侧面板中，选择 “AutoResponder ”选项卡。

  6. 确保已勾选启用规则和未匹配请求直通。

  7. 选择 “添加规则 ”，然后首先输入：

    REGEX:(.*?)((?'folder'css|html)(%252f|\/))?YOUR_NAMESPACE\.YOUR_CONTROL_NAME[\.\/](?'fname'[^?]*\.*)(.*?)$

    地点：

    • YOUR_NAMESPACE - 你提供给 pac pcf init 的命名空间，包含在 ControlManifest.Input.xml 的 control.namespace 属性中
    • YOUR_CONTROL_NAME - 你提供给 pac pcf init 的组件名称，并在 ControlManifest.Input.xml 的 control.constructor 属性中设置

    此规则旨在匹配代码组件bundle.js和相关资源（css/html）的请求，使其适用于Power Apps Studio 和 Player 中的模型驱动应用和画布应用。

    此规则的示例如下所示：

    Fiddler AutoResponder 中用于本地代码组件资源的规则的屏幕截图。

    如果需要更简单的 AutoResponder 规则方法，请参阅 使用 Fiddler 自动响应程序编写 Web 资源开发的脚本。

  8. 为用于响应的路径输入如下格式的字符串：

    C:\COMPONENT_ROOT_FOLDER\out\controls\YOUR_CONTROL_NAME\${folder}\${fname}

    例如，如果代码组件根文件夹为 C:\src\PowerApps-Samples\component-framework\DataSetGrid 组件名称 DataSetGrid，则路径为：

    C:\src\PowerApps-Samples\component-framework\DataSetGrid\out\controls\DataSetGrid\${folder}\${fname}

  9. 选择“保存”。

  10. 打开“ 筛选器 ”选项卡，并选中 “使用筛选器”。 在 “响应标头 ”部分中，选中 “设置响应标头 ”并提供以下内容：

    标头：Access-Control-Allow-Origin

    值：*

    Fiddler 中用于跨源访问的响应头过滤器的截图。

    Important

    只有在将代码组件部署到画布应用后调试代码组件时，才需要执行此步骤，因为资源存储在 Blob 存储中，而不是存储在域下 powerapp.com 。 因此，在浏览器加载时，对这些资源的任何请求都需要跨域访问。 仅在调试时启用此 Access-Control-Allow-Origin 筛选器规则，因为它将修改您访问的其他网站的标头。

  11. 运行 AutoResponder 规则后，首先需要在浏览器中清除缓存并重新加载包含代码组件的页。 这可以通过打开开发人员工具（Ctrl + Shift + I）、右键单击 “刷新>空缓存”和“硬刷新”轻松完成。

    Microsoft Edge空缓存和硬刷新命令的屏幕截图。

  12. 从本地计算机加载代码组件后，可以在 npm start watch 运行时更改代码，并刷新浏览器以加载新构建的版本。 Fiddler 的自动响应器会自动添加 Cache-Control 标头，使浏览器不缓存这些资源，因此只需简单刷新即可重新加载资源，而无需每次都清除缓存。

使用 Requestly 调试代码组件

若要使用 Requestly 调试代码组件，请执行以下操作：

  1. 在计算机上启用Internet Information Services（IIS）。

    1. 打开控制面板并选择“程序和功能>”打开或关闭Windows功能。
    2. 启用Internet Information Services。
    3. 展开“Internet Information Services”，并确认下一节中列出的 Web 服务器组件已启用。
    4. 选择“确定”。

  2. 设置 ISS

    1. 在计算机上打开 IIS。
    2. 在右侧面板 “连接”中，展开树，然后右键单击“ 站点”。
    3. 添加网站。
    4. 设置 站点 名称。
    5. 设置自定义组件文件夹 的物理路径 ，例如 C:\COMPONENT_ROOT_FOLDER\out\controls\YOUR_CONTROL_NAME\
    6. 设置 端口 （任意数字，例如 7777）。
    7. 选择“确定”。 所选文件夹现在托管在 http://localhost:<SELECTED_PORT>

    用于在本地网站上托管代码组件文件的 IIS 设置的屏幕截图。

  3. 下载并 安装 Requestly

  4. 按照该工具的引导流程操作。

  5. 打开规则（导航到 https://app.requestly.io/rules）。

  6. 添加“替换主机”规则：

    1. 设置规则的名称。
    2. 将“替换”字段设置为 https://[ORG_URL]/[APPLICATION_ID]/webresources/[YOUR_NAMESPACE].[YOUR_CONTROL_NAME]/
    3. 使用 http://localhost:<SELECTED_PORT> 设置“With”
    4. 将“If request”设置为“URL” “Contains” [YOUR_NAMESPACE].[YOUR_CONTROL_NAME]
    5. 保存规则并启用它。

    本地代码组件文件的“请求替换主机”规则的屏幕截图。

  7. 现在，需要在浏览器中清除缓存并重新加载包含代码组件的页。 可以通过打开开发人员工具（Ctrl + Shift + I）、右键单击 “刷新>空缓存”和“硬刷新”来清除浏览器中的缓存并重新加载页面。

    空缓存和硬刷新

  8. 从本地计算机加载代码组件后，您可以在 npm start watch 运行期间修改代码，并刷新浏览器以加载新构建的版本。 Requestly 会自动添加 Cache-Control 标头，以防止浏览器缓存这些资源，因此只需简单刷新页面即可重新加载资源，而无需每次都清除缓存。

Power Apps组件框架 API 参考
Power Apps组件框架概述
应用程序生命周期管理 （ALM）
创建您的第一个组件

  • Last updated on