在 Power Pages 中创建和部署单页应用程序

Power Pages支持集成使用下一代 AI 辅助工具(如GitHub Copilot)创建的单页应用程序(SPA)代码。 此功能使开发人员可以使用自然语言作为编码界面将基于组件的新式前端体验引入Power Pages。

通过引导、测试和优化 AI 生成的代码,制作者可以将注意力从重复的实现任务转移到更高层次的协调工作。 此方法可提高直观、创造性的开发,同时保持企业级质量和标准。

本文将向您介绍如何操作:

注释

  • SPA 站点是一个Power Pages站点,它完全在用户的浏览器(客户端呈现)中运行。 与传统Power Pages站点不同,你只能通过源代码和命令行接口 (CLI) 工具管理 SPA 站点。
  • Power Platform Git 集成不支持 Power Pages 中的单页应用程序(SPA)网站。

Prerequisites

在开始之前,请确保具备:

允许上传 JavaScript 文件

默认情况下,某些 Dataverse 环境会阻止上传 JavaScript (.js) 文件。 如果遇到 错误“导入失败:附件不是有效类型或太大。无法上传或下载它。“请更新环境设置以允许此文件类型。

要调整环境 Power Platform 管理中心的设置,请按照以下步骤操作:

  1. 登录到 Power Platform 管理中心。
  2. 在导航窗格中,选择“ 管理”。
  3. 在管理窗格中,选择环境。
  4. 选择环境。
  5. 在命令栏中,选择 设置。
  6. 展开产品,然后选择隐私和安全性。
  7. 在 “阻止的附件 ”部分中,从文件扩展名列表中删除 js 。
  8. 选择“保存”。

创建和部署 SPA 站点

Power Pages SPA 站点使用 PAC CLI 命令upload-code-site和 download-code-site进行管理。 上传网站后,它将显示在 Power Pages非活动网站列表中。 激活站点以使其可供用户使用。

上传 SPA 站点

使用 pac pages upload-code-site 命令将本地源和已编译的资产上传到Power Pages环境。

Syntax

pac pages upload-code-site `
  --rootPath <local-source-folder> `
  [--compiledPath <build-output-folder>] `
  [--siteName <site-display-name>]

Parameters

参数 别名 必需 Description
--rootPath -rp 是的 具有站点源文件的本地文件夹
--compiledPath -cp 否 编译后资源的路径,如 React build
--siteName -sn 否 Power Pages 网站的显示名称

示例

pac pages upload-code-site `
  --rootPath "../your-project" `
  --compiledPath "./build" `
  --siteName "Contoso Code Site"

如果没有现有项目,请尝试 使用 React、Angular 和 Vue 的 SPA 站点的示例实现。

使用powerpages.config.json定义上传参数

通过在网站根文件夹中添加一个upload-code-site文件,自定义powerpages.config.json命令的行为。 当此文件存在时,仅使用 upload-code-site 参数运行 --rootPath。 该命令从配置文件中读取剩余值。 如果同时提供命令行参数和配置值,则命令行参数优先。

配置字段
领域 类型 必需 Description
siteName 字符串 是的 Power Pages 站点的显示名称。
compiledPath 字符串 是的 编译输出目录的路径(例如 Vite dist 或 React build 文件夹),相对于 powerpages.config.json。
defaultLandingPage 字符串 是的 打开站点根目录时提供的 HTML 页面,相对于 compiledPath(通常为 index.html)。
bundleFilePatterns string[] 否 一组通配符模式,用于标识 CLI 在上传新构建前将从站点 web-files 中删除的文件。 使用此字段清理过时的、带内容哈希的捆绑包,以免旧资源在站点中堆积。 请参阅 代码拆分和捆绑包清理。
includeSource 布尔 否 当 true 时,该命令除上传编译后的资源文件外,还会上传源代码。 默认值为 false.
sourceExcludePatterns string[] 否 用于排除上传的源文件的通配符模式。 仅当includeSource为true时适用(例如,跳过node_modules或本地环境文件)。

有关最准确且最新的字段参考信息,请参阅 powerpages.config.json 架构。 将匹配 $schema 属性添加到配置文件,以便在支持 JSON 架构的编辑器中启用验证和自动完成。

示例 powerpages.config.json
{
  "$schema": "https://www.schemastore.org/powerpages.config.json",
  "siteName": "Contoso Bank",
  "compiledPath": "dist",
  "defaultLandingPage": "index.html",
  "bundleFilePatterns": [
    "index-*.js",
    "index-*.css"
  ]
}

下载 SPA 站点

使用 pac pages download-code-site 命令将现有网站的代码下载到本地目录,以便编辑或备份。

Syntax

pac pages download-code-site `
  [--environment <env-url-or-guid>] `
  --path <local-target-folder> `
  --webSiteId <site-guid> `
  [--overwrite]

Parameters

参数 别名 必需 Description
--environment -env 否 Dataverse 环境(GUID 或完整 URL)。 默认为活动身份验证配置文件
--path -p 是的 用于下载网站代码的本地目录
--webSiteId -id 是的 Power Pages SPA 站点的网站记录 GUID
--overwrite -o 否 覆盖目标目录中的现有文件(如果存在)

示例

pac pages download-code-site `
  --environment "https://contoso.crm.dynamics.com" `
  --path "./downloaded-site" `
  --webSiteId "11112222-bbbb-3333-cccc-4444dddd5555" `
  --overwrite

激活并测试您的网站

  1. 转到 Power Pages。
  2. 选择非活动网站,找到您的网站,然后选择重新激活。
  3. 当站点处于活动状态时,转到站点的 URL 检查部署情况。

Tip

任何后续的 upload-code-site 命令都会自动更新活动网站。

项目结构和配置

一致的项目布局帮助确保正确的上传行为。

/your-project
│
├─ src/                       ← Your source code, like React components
├─ build/                     ← Compiled assets, output of the `npm run build` command
├─ powerpages.config.json     ← Optional CLI configuration file
└─ README.md

使用可选的 powerpages.config.json 文件自定义 upload-code-site 命令的工作方式。

代码拆分与打包清理

随着单页应用程序的增长,单个 JavaScript 捆绑包变得很大且加载速度缓慢。 新式生成工具通过 代码拆分解决此问题。 此方法将应用分解为浏览器按需下载的较小 区块 (例如,仅当用户导航到特定路由时)。 每个区块在其文件名中使用 内容哈希 发出,例如 Dashboard-BSbmIXoe.js,这样浏览器就可以缓存它很长时间,并且仅在内容发生更改时才重新下载它。

代码拆分带来了 Power Pages SPA 站点特有的一项部署注意事项:由于每次构建都会产生新的带哈希值的文件名,反复运行 upload-code-site 会导致旧的带哈希值的文件遗留在站点上。 经过多次部署,这些孤立的代码块会累积在网站的 web-files 中。 bundleFilePatterns中的powerpages.config.json字段用于清理它们。

启用代码拆分

代码拆分由前端生成工具处理,而不是Power Pages处理,因此方法取决于使用的框架和捆绑程序。 最常见的技术是通过动态导入来加载应用的各个部分,通常应用在路由或视图层级,这样每个部分只有在用户导航到该部分时才会下载(延迟加载)。

Vite、webpack 和 esbuild 等捆绑程序还可以显式将模块分组到命名区块中。 有关确切的配置,请参阅框架和捆绑程序的文档。

dist/assets/
├─ index-BJltBIP-.js        ← app entry
├─ index-DMwMk7hv.css       ← styles
├─ Dashboard-BSbmIXoe.js    ← lazy route chunk
├─ InvoiceList-DwjrGrAI.js  ← lazy route chunk
└─ InvoiceDetail-D3DVGkeM.js← lazy route chunk

无论你选择哪种方法,结果都是一样的,而这正是对部署至关重要的部分:构建会生成多个输出文件,每个文件的名称中都包含内容哈希值。 由于这些哈希值会随着文件内容的变化而变化,因此每次构建都会产生一组不同的文件名。 后续部分介绍如何在更改这些名称时保持 Dataverse 环境干净。

upload-code-site 如何清理过期的打包文件

在上传已编译的资源文件之前,upload-code-site 会删除站点的 web-files 中与 bundleFilePatterns 里的通配符模式匹配的所有文件,然后上传当前构建版本。 这种“先删除再上传”的行为可使已部署的文件集与最新编译输出保持一致,而不是在上一次构建结果之上层层叠加每次构建的内容。

为了使清理生效,bundleFilePatterns 中的通配符模式必须与您的构建生成的文件名相匹配。 有两种方法可以使其准确,具体取决于生成工具如何命名文件。

选项 1:直接列出通配符模式

许多生成工具保留稳定的名称前缀,并仅更改内容哈希,例如 index-[hash].js。 当输出文件名遵循如此类可预测的模式时,请在 bundleFilePatterns 中为每个文件名列出一个通配符模式。 无需额外的工具:

{
  "$schema": "https://www.schemastore.org/powerpages.config.json",
  "siteName": "Contoso Bank",
  "compiledPath": "dist",
  "defaultLandingPage": "index.html",
  "bundleFilePatterns": [
    "index-*.js",
    "index-*.css"
  ]
}

像 index-*.js 这样的通配符模式会在每次构建时匹配该文件,而不考虑哈希值。 为每个输出文件添加一个条目,并在构建开始生成新的输出文件时添加一个新模式。

选项 2:使用构建后脚本生成通配符模式

如果你的输出文件名不遵循可预测的模式,或者你的应用会生成大量文件,且这些文件的名称会随着你添加和删除路由而变化,从而使手动维护的列表容易出错,请使用这种方法。 一个在构建完成后运行的简短脚本,会扫描编译后的输出,并将 bundleFilePatterns 重写为适用于每个输出文件的通配符模式。 例如,当生成工具将文件命名为 [name]-[hash].[ext]时,脚本会 Dashboard-BSbmIXoe.js 减少到模式 Dashboard-*.js。

scripts/postbuild.js:

#!/usr/bin/env node

/**
 * Post-build script: scans dist/assets/ and updates powerpages.config.json
 * with bundleFilePatterns that match all Vite-generated chunks.
 *
 * This ensures `pac pages upload-code-site` cleans up old hashed bundles
 * on each deploy instead of accumulating stale files.
 *
 * Usage: node scripts/postbuild.js
 * Or via npm: "postbuild": "node scripts/postbuild.js" in package.json
 */

import { readdirSync, readFileSync, writeFileSync } from 'fs'
import { join } from 'path'

const ROOT = join(import.meta.dirname, '..')
const DIST_ASSETS = join(ROOT, 'dist', 'assets')
const CONFIG_PATH = join(ROOT, 'powerpages.config.json')

// Vite output format: [name]-[hash].[ext]
// We want to extract "name" and "ext" to produce "name-*.ext" patterns
const HASH_PATTERN = /^(.+)-[A-Za-z0-9_-]{6,12}\.(js|css)$/

try {
  const files = readdirSync(DIST_ASSETS)
  const patternSet = new Set()

  for (const file of files) {
    const match = file.match(HASH_PATTERN)
    if (match) {
      const [, baseName, ext] = match
      patternSet.add(`${baseName}-*.${ext}`)
    }
  }

  const patterns = [...patternSet].sort()

  if (patterns.length === 0) {
    console.log('No hashed bundles found in dist/assets/ — skipping config update.')
    process.exit(0)
  }

  // Read current config
  const config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'))
  const oldPatterns = config.bundleFilePatterns || []

  // Check if update is needed
  const oldSet = new Set(oldPatterns)
  const newSet = new Set(patterns)
  const changed = oldSet.size !== newSet.size || [...newSet].some(p => !oldSet.has(p))

  if (!changed) {
    console.log(`bundleFilePatterns already up-to-date (${patterns.length} patterns).`)
    process.exit(0)
  }

  // Update config
  config.bundleFilePatterns = patterns
  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf-8')

  console.log(`Updated powerpages.config.json with ${patterns.length} bundle patterns:`)
  for (const p of patterns) {
    console.log(`  ${p}`)
  }
} catch (err) {
  console.error('postbuild error:', err.message)
  process.exit(1)
}

将该脚本集成到构建流程中,以便它始终在打包工具之后运行:

{
  "scripts": {
    "build": "tsc -b && vite build && node scripts/postbuild.js"
  }
}

现在,部署只需两条命令,站点也永远不会累积孤立的代码块:

npm run build
pac pages upload-code-site --rootPath .

构建后,powerpages.config.json 会准确反映当前的 bundle,例如:

{
  "$schema": "https://www.schemastore.org/powerpages.config.json",
  "siteName": "Contoso Bank",
  "compiledPath": "dist",
  "defaultLandingPage": "index.html",
  "bundleFilePatterns": [
    "Dashboard-*.js",
    "InvoiceDetail-*.js",
    "InvoiceList-*.js",
    "index-*.css",
    "index-*.js"
  ]
}

身份验证和授权

Power Pages SPA 站点使用与传统Power Pages站点相同的安全模型。

配置身份提供者

  1. 转到 Power Pages。
  2. 找到您的网站并选择编辑。
  3. 选择 安全>标识提供者。
  4. 添加或设置 身份提供者,例如 Microsoft Entra ID。
  5. 每个新站点天然有一个默认 Microsoft Entra ID 提供者。

在代码中访问用户上下文

在客户端上获取身份验证元数据:

  • 机构 URL:

    Microsoft Entra ID的颁发机构或登录 URL 为:

    https://login.windows.net/<tenantId>
    
  • 要查找其他已配置标识提供者的机构 URL,转到 Power Pages><your site>>安全性>标识提供者>配置设置。

  • 用户详细信息:

    window["Microsoft"].Dynamic365.Portal.User
    

示例 React 流

import { IconButton, Tooltip } from '@mui/material';
import {
    Login,
    Logout
} from '@mui/icons-material';
import React from 'react';
export const AuthButton = () => {
    const username = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.userName ?? "";
    const firstName = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.firstName ?? "";
    const lastName = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.lastName ?? "";
    const tenantId = (window as any)["Microsoft"]?.Dynamic365?.Portal?.tenant ?? "";
    const isAuthenticated = username !== "";
    const [token, setToken] = React.useState<string>("");

    React.useEffect(() => {
        const fetchAntiForgeryToken = async (): Promise<string> => {
            try {
                const tokenEndpoint = "/_layout/tokenhtml";

                const response = await fetch(tokenEndpoint, {});

                if (response.status !== 200) {
                    throw new Error(`Failed to fetch token: ${response.status}`);
                }

                const tokenResponse = await response.text();                
                const valueString = 'value="';
                const terminalString = '" />';
                const valueIndex = tokenResponse.indexOf(valueString);

                if (valueIndex === -1) {
                    throw new Error('Token not found in response');
                }

                const requestVerificationToken = tokenResponse.substring(
                    valueIndex + valueString.length,
                    tokenResponse.indexOf(terminalString, valueIndex)
                );

                return requestVerificationToken || '';
            } catch (error) {
                console.warn('[Impersonation] Failed to fetch anti-forgery token:', error);
                return '';
            }
        };

        const getToken = async () => {
            try {
                const token = await fetchAntiForgeryToken();
                setToken(token);
            } catch (error) {
                console.error('Error fetching token:', error);
            }
        };
        getToken();
    }, []);

    return (
        <div className="flex items-center gap-4">
            {isAuthenticated ? (
                <>
                    <span className="text-sm">Welcome {firstName + " " + lastName}</span>
                    <Tooltip title="Logout">
                        <IconButton color="primary" onClick={() => window.location.href = "/Account/Login/LogOff?returnUrl=%2F"}>
                            <Logout />
                        </IconButton>
                    </Tooltip>
                </>
            ) : (
                <form action="/Account/Login/ExternalLogin" method="post">
                    <input name="__RequestVerificationToken" type="hidden" value={token} />
                    <Tooltip title="Login">
                        <IconButton name="provider" type="submit" color="primary" value={`https://login.windows.net/${tenantId}/`}>
                            <Login />
                        </IconButton>
                    </Tooltip>
                </form>
            )}
        </div>
    );
};

使用 Power Pages Web API

开发人员可以使用 Power Pages Web API 将内容加载到 UI 或创建、更新和删除记录。 使用这些 API 之前,请确保启用所需的 Web API,并正确配置适当的表权限和 Web 角色。


// Create query to get all cards from Dataverse
const fetchCards = async () => {
    const response = await fetch("/_api/cr7ae_creditcardses");
    const data = await response.json();
    const cards = data.value;
    const returnData = [];

    // Loop through the cards and get the name and id of each card
    for (let i = 0; i < cards.length; i++) {
        const card = cards[i];
        const cardName = card.cr7ae_name;
        const cardId = card.cr7ae_creditcardsid;
        const features = card.cr7ae_features
            ?.split(',')
            .map((feature: string) => feature.trim());
        const type = card.cr7ae_type;
        const image = card.cr7ae_image;
        const category = card.cr7ae_category
            ?.split(',')
            .map((cat: string) => cat.trim());
        
        // ...additional processing/pushing to returnData...
    }

    return returnData;
};

设置本地开发环境,通过 Microsoft Entra ID 身份验证允许从 localhost 进行 Web API 调用

生成应用程序时,开发人员需要更快的迭代周期、本地调试和热重载功能。 SPA 通过使用 Microsoft Entra ID (Azure AD) v1 身份验证,支持从 localhost 进行安全的 Web API 调用,以实现这些工作流。

通过此设置,你可以:

  • 使用完全身份验证支持在本地运行应用。
  • 使用 Vite 等新式开发工具进行热重载和快速反馈。
  • 在调用 Power Pages Web API 时避免 CORS 问题。
  • 无需将更改部署到门户即可加速开发。

此配置为 SPA 提供了高效的本地开发体验,因此开发人员可以使用完整的 API 访问和身份验证支持快速生成、测试和迭代。

Important

  • 仅使用 Microsoft Entra v1 端点进行身份验证。
  • 持有者身份验证仅在门户版本 9.7.6.6 或更高版本中受支持。
  • 仅在开发环境中应用这些设置。

配置步骤

  1. 启用 SPA 身份验证

    1. 在 Azure 门户中,打开为门户注册的Microsoft Entra应用。
    2. 启用 单页应用程序(SPA) 身份验证。
    3. 使用localhost平台配置,将添加为重定向 URI。 有关详细信息,请参阅 如何在应用程序中添加重定向 URI。
      • 重定向 URI: http://localhost:<port>/。
  2. 添加网站设置

    Authentication/BearerAuthentication/Enabled = true
    Authentication/BearerAuthentication/Protocol = OpenIdConnect
    Authentication/BearerAuthentication/Provider = AzureAD
    
  3. 使用 ADAL.js 进行身份验证

    • 使用 ADAL.js实现客户端身份验证。

    注释

    MSAL.js 不兼容,因为 Power Pages 使用 Microsoft Entra v1 终结点,而 MSAL 则使用 v2。 颁发者格式因版本而异。

  4. 添加授权标头

    • 在所有 Web API 请求中包含此标头:
    Authorization: Bearer <id_token>
    
  5. 将网站可见性设置为“公共”

    • 此设置允许 localhost 访问站点以进行开发和测试。
  6. 配置开发代理

    • 如果使用 Vite,请添加此代码以避免 vite.config.js CORS 问题:
    export default defineConfig({
      plugins: [react()],
      server: {
        proxy: {
          '/_api': {
            target: 'https://site-foo.powerappsportals.com',
            changeOrigin: true,
            secure: true
          }
        }
      }
    });
    

与现有Power Pages网站的差异

下表总结了使用此功能创建的 SPA 站点与传统Power Pages站点之间的主要差异:

功能 SPA 站点行为
服务器端刷新 始终返回站点的根页,客户端路由器呈现子路由。
路由冲突 客户端路由优先,硬刷新回退到根。
页面工作区 页面工作区不受支持。 使用客户端路由和客户端站点页面。 为了达到页面级安全性,使用全局用户对象检查分配的 Web 角色,并有条件地呈现 UI。
样式工作区 使用样式工作区进行样式设置不被支持。 使用框架提供的样式,例如 CSS、CSS-in-JS 或工具类。
本地化 仅支持单一语言。 实现客户端资源加载。
Liquid 模板化 Liquid 代码和 Liquid 模板不被支持。 使用框架的模板引擎和 Web API 访问数据。

FAQ

单元测试和集成测试提供哪些支持?

目前,没有对单元和集成测试的内置支持。 制作者应在本地或 CI/CD 管道中编写并执行这些测试。

是否支持使用 WebAssembly 进行 Power Fx 集成?

此功能目前不受支持。

源代码在Power Pages中是否可用?

目前,制造商可以使用 TypeScript 或 GitHub Copilot 代理生成网站。 编译的 JavaScript 和 CSS 文件可访问,可在Visual Studio Code中编辑。 但是,目前不支持对 HTML 文件进行直接和广泛的编辑。

是否可以使用此功能在外部创建组件并将其引入Power Pages站点?

否,无法使用此功能将外部生成的组件引入现有Power Pages站点。

我可以添加现成的组件,如列表和窗体吗?

当前不支持添加现成的组件,如列表和窗体。 但是,可以使用 React 框架和 Web API 生成自定义窗体和列表。

是否可以从“设置”工作区将 SPA 站点启用为 PWA 应用?

No. SPA 网站不支持设置工作区中的渐进式 Web 应用(PWA)设置。 此限制意味着不能使用 “移动 ”部分将网站启用为 PWA。 若要添加 PWA 功能(如可安装的应用体验和脱机页面),请在框架代码中实现它们。 例如,添加 Web 应用清单和 Service Worker。

源代码管理是如何工作的?

开发人员可以使用 Power Platform Git 集成进行源代码管理。 然而,只有编译后的网页文件会被添加到仓库中,而非完整的源代码。

这些站点支持 SEO 吗?

由于 SPA 站点是使用 React 框架构建并使用客户端呈现的,因此 SEO 支持有限。

SPA 站点提供哪些 Power Pages 安全和治理支持?

Power Pages在 Web API 调用中强制实施表权限和安全 Web 角色,确保数据访问与用户角色保持一致。 使用 window["Microsoft"].Dynamic365.Portal.User 对象检索基本用户属性并根据用户角色定制体验。

此外,SPA 网站支持:

  • 公共和私有网站配置
  • 治理设置,包括对匿名数据访问的控制
  • 身份验证提供程序配置

这些功能有助于确保Power Pages中自定义组件的安全性和合规集成。