Создание и развертывание одностраничного приложения в Power Pages

Power Pages поддерживает интеграцию кода одностраничного приложения (SPA), созданного с помощью средств, поддерживающих ИИ следующего поколения, например GitHub Copilot. Эта возможность позволяет разработчикам использовать современные интерфейсные интерфейсы на основе компонентов в Power Pages с помощью естественного языка в качестве интерфейса кодирования.

Направляя, тестируя и совершенствуя сгенерированный ИИ код, создатели могут перемещать свое внимание с повторяющихся задач реализации на более высокоуровневую оркестровку. Этот подход обеспечивает более интуитивно понятное, творческое развитие, сохраняя качество и стандарты корпоративного уровня.

В этой статье показано, как:

• Создайте и настройте проект SPA для Power Pages с помощью интерфейса командной строки Power Platform CLI (CLI PAC).
• Отправка ресурсов кода на сайт Power Pages и загрузка этих ресурсов с сайта Power Pages.
• Создание безопасной и удобной в обслуживании структуры проекта.
• Узнайте о ключевых различиях между реализациями на основе SPA и традиционными Power Pages.

Prerequisites

Прежде чем начать, убедитесь, что у вас есть:

• Среда Power Pages с правами admin.
• Интерфейс командной строки Power Platform (PAC CLI) версии 1.44.x или более поздней, установленный и прошедший проверку подлинности.
• Сайт Power Pages версии 9.7.4.x или более поздней.
• Разрешить отправку файлов JavaScript в средах Dataverse.
• Локальный репозиторий Git с пользовательским интерфейсным проектом, например React, Angular или Vue.

Разрешить отправку файлов 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 в списке Inactive sites. Активируйте сайт, чтобы сделать его доступным для пользователей.

Отправка сайта 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

Example

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

Если у вас нет существующего проекта, попробуйте примеры реализаций сайтов SPA с помощью React, Angular и Vue.

Определение параметров отправки с помощью powerpages.config.json

Настройте поведение upload-code-site команды, включив файл в корневую powerpages.config.json папку сайта. Если этот файл присутствует, запустите upload-code-site, указав только параметр --rootPath. Команда считывает оставшиеся значения из файла конфигурации. Если указать аргументы командной строки и значения конфигурации, аргументы командной строки имеют приоритет.

Поля конфигурации

Наиболее точный и актуальный справочник по полям см. в 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

Example

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-адресу сайта, чтобы проверить развертывание.

Структура и конфигурация проекта

Единообразный макет проекта помогает обеспечить правильное поведение при отправке.

/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, поэтому браузеры могут кэшировать его долгое время и загружать заново только при изменении его содержимого.

Разделение кода вносит особенность, которую нужно учитывать при развертывании и которая характерна только для SPA-сайтов Power Pages: поскольку каждая сборка создает новые хэшированные имена файлов, при повторных запусках 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 отражает точные текущие пакеты, например:

{
  "$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 СПА-сайты используют ту же модель безопасности, что и традиционные сайты Power Pages.

Настройка поставщиков удостоверений

1. Перейдите к Power Pages.
2. Найдите свой сайт и выберите Изменить.
3. Выберите Безопасность>Поставщики удостоверений.
4. Добавьте или настройте поставщиков удостоверений, таких как Microsoft Entra ID.
5. У каждого нового сайта автоматически есть поставщик по умолчанию Microsoft Entra ID.

Доступ к контексту пользователя в коде

Получите метаданные проверки подлинности на клиенте:

• URL-адрес центра:

  URL-адрес центра авторизации или входа для Microsoft Entra ID:

  https://login.windows.net/<tenantId>
  

• Найдите URL-адрес Authority для других настроенных поставщиков удостоверений, перейдя в Power Pages><your site>>Security>Identity providers> параметры конфигурации.

• Сведения о пользователе:

  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>
    );
};

Используйте веб-API Power Pages

Разработчики могут использовать Power Pages веб-API для загрузки содержимого в пользовательский интерфейс или для создания, обновления и удаления записей. Прежде чем использовать эти API, убедитесь, что необходимые веб-API включены, а соответствующие разрешения таблицы и веб-роли настроены правильно.

// 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;
};

Настройка локальной разработки путем включения вызовов веб-API из localhost с помощью проверки подлинности идентификатора Microsoft Entra

Разработчикам требуются более быстрые циклы итерации, локальная отладка и возможности горячей перезагрузки при создании приложений. SPA поддерживает эти рабочие процессы, обеспечивая безопасные вызовы веб-API через аутентификацию Microsoft Entra ID (Azure AD) версии 1.

Эта настройка позволяет:

• Запустите приложение локально с полной поддержкой проверки подлинности.
• Используйте современные средства разработки, такие как Vite , для горячей перезагрузки и быстрой обратной связи.
• Избегайте проблем CORS при вызове веб-API Power Pages.
• Ускорьте разработку без развертывания изменений на портале.

Эта конфигурация обеспечивает продуктивную локальную разработку для SPA, чтобы разработчики могли создавать, тестировать и выполнять итерацию быстро с полным доступом к API и поддержкой проверки подлинности.

Действия по настройке

1. Включение проверки подлинности SPA

   1. На портале Azure откройте приложение Microsoft Entra, зарегистрированного на портале.
   2. Включите проверку подлинности одностраничного приложения (SPA).
   3. Добавьте localhost в качестве URI перенаправления, используя конфигурацию платформы Одностраничное приложение. Дополнительные сведения см. в разделе "Добавление URI перенаправления" в приложение.
      • URI перенаправления: http://localhost:<port>/.

2. Добавление параметров сайта

   • Добавьте следующие параметры сайта в Power Pages:

   Authentication/BearerAuthentication/Enabled = true
   Authentication/BearerAuthentication/Protocol = OpenIdConnect
   Authentication/BearerAuthentication/Provider = AzureAD
   

3. Использование ADAL.js для проверки подлинности

   • Реализуйте проверку подлинности на стороне клиента с помощью ADAL.js.

   Замечание

   MSAL.js несовместим, так как Power Pages использует конечные точки Microsoft Entra версии 1, а MSAL использует версию 2. Формат издателя отличается между версиями.

4. Добавление заголовка авторизации

   • Включите этот заголовок во все запросы веб-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:

FAQ

Какая предусмотрена поддержка модульного и интеграционного тестирования?

В настоящее время встроенной поддержки модульного и интеграционного тестирования нет. Создатели должны писать и выполнять эти тесты локально или в своих конвейерах CI/CD.

Есть ли поддержка интеграции Power Fx с помощью WebAssembly?

Эта возможность в настоящий момент не поддерживается.

Доступен ли исходный код в Power Pages?

В настоящее время разработчики могут создавать веб-сайты с помощью TypeScript или агента GitHub Copilot. Скомпилированные файлы JavaScript и CSS доступны и могут быть изменены в Visual Studio Code. Однако прямое и расширенное редактирование HTML-файлов в настоящее время не поддерживается.

Можно ли создать компонент внешне с помощью этой функции и перенести его на сайт Power Pages?

Нет, вы не можете перенести внешний созданный компонент на существующий сайт Power Pages с помощью этой функции.

Можно ли добавлять готовые компоненты, такие как списки и формы?

Добавление готовых компонентов, таких как списки и формы, в настоящее время не поддерживается. Однако вы можете создавать пользовательские формы и списки с помощью платформы React и веб-API.

Можно ли включить сайт SPA в качестве PWA из рабочей области "Настройка"?

No. Веб-сайты SPA не поддерживают параметр прогрессивного веб-приложения (PWA) в настроенной рабочей области. Это ограничение означает, что вы не можете использовать раздел Mobile для включения сайта в качестве PWA. Чтобы добавить возможности PWA, такие как возможности установки приложений и автономные страницы, реализуйте их в коде платформы. Например, добавьте манифест веб-приложения и служебный сценарий.

Как работает управление версиями?

Разработчики могут использовать для управления версиями интеграцию Power Platform с Git. Однако в репозиторий добавляются только скомпилированные веб-файлы, а не весь исходный код.

Поддерживают ли эти сайты SEO?

Поскольку сайты SPA создаются с помощью фреймворка React и используют отрисовку на стороне клиента, поддержка SEO ограничена.

Какие возможности поддержки безопасности и управления предоставляют сайты SPA в рамках Power Pages?

Power Pages применяет разрешения для таблиц и роли безопасности на обращения к Web API, обеспечивая, чтобы доступ к данным соответствовал ролям пользователей. Используйте объект window["Microsoft"].Dynamic365.Portal.User для получения основных свойств пользователя и настройки взаимодействий на основе пользовательских персон.

Кроме того, сайты SPA поддерживают:

• Общедоступные и частные конфигурации сайтов
• Параметры управления, включая контроль над анонимным доступом к данным
• Конфигурации поставщиков проверки подлинности

Эти функции помогают обеспечить безопасную и совместимую интеграцию пользовательских компонентов в Power Pages.

Связанные сведения

• интерфейс командной строки Microsoft Power Platform
• Учебник: использование Microsoft Power Platform CLI с Power Pages
• Использование расширения Visual Studio Code