Crie e implemente uma aplicação de página única no Power Pages

Power Pages suporta a integração de código de aplicação de página única (SPA) criado com ferramentas assistidas por IA de próxima geração, como GitHub Copilot. Esta funcionalidade permite aos programadores trazer experiências modernas de front-end baseadas em componentes para o Power Pages, utilizando a linguagem natural como interface de programação.

Ao orientar, testar e refinar o código gerado por IA, os criadores podem mudar o seu foco de tarefas de implementação repetitivas para a orquestração de nível superior. Isto possibilita um desenvolvimento criativo mais intuitivo, mantendo a qualidade e os padrões de nível empresarial.

Este artigo mostra-lhe como:

• Crie e configure um projeto SPA para Power Pages utilizando a CLI Power Platform (PAC CLI).
• Carregue e transfira ativos de código de e para o seu site do Power Pages.
• Configure uma estrutura de projeto segura e sustentável.
• Aprenda as principais diferenças entre as implementações baseadas em SPA e as tradicionais Power Pages.

Pré-requisitos

Antes de começar, certifique-se de que tem:

• Um ambiente do Power Pages com privilégios de administrador.
• Power Platform CLI (PAC CLI) versão 1.44.x ou posterior instalado e autenticado.
• Um site do Power Pages na versão 9.7.4.x ou posterior.
• Permitir o carregamento de ficheiros JavaScript em ambientes Dataverse.
• Um repositório Git local com o seu projeto front-end personalizado, como React, Angular ou Vue.

Permitir carregamento de ficheiros JavaScript

Por defeito, alguns ambientes Dataverse bloqueiam o carregamento de ficheiros JavaScript (.js). Se encontrar o erro "Importação falhada: O anexo ou não é um tipo válido ou é demasiado grande. Não pode ser carregado nem descarregado.", atualize as definições do seu ambiente para permitir este tipo de ficheiro.

Para ajustar as definições no centro de administração do Power Platform para um ambiente, siga estes passos:

1. Inicie sessão no Centro de administração do Power Platform.
2. No painel de navegação, selecione Gerenciar.
3. No painel Gerir, selecione Ambientes.
4. Selecione um ambiente
5. Na barra de comandos, selecione Configurações.
6. Expanda o Produto e, em seguida, selecione Privacidade + Segurança.
7. Na secção Anexos Bloqueados , remova js da lista de extensões de ficheiro.
8. Selecione Guardar.

Criar e implementar um site de SPA

Power Pages sites SPA são administrados usando os comandos PAC CLI upload-code-site e download-code-site. Depois de carregar um site, ele aparece em Power Pages na lista Sites inativos. Ative o site para o disponibilizar aos utilizadores.

Carregar um site de SPA

Use o comando pac pages-upload-code-site para carregar a sua fonte local e os recursos compilados para o seu ambiente 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"

Se você não tiver um projeto existente, tente as implementações de exemplo de sites SPA usando React, Angular e Vue.

Definição de parâmetros de carregamento com powerpages.config.json

Personalize o comportamento do upload-code-site comando incluindo um powerpages.config.json ficheiro na pasta raiz do seu site. Quando este ficheiro estiver presente, execute upload-code-site apenas com o --rootPath parâmetro. O comando lê os valores restantes do ficheiro de configuração. Se fornecer tanto argumentos de linha de comandos como valores de configuração, os argumentos da linha de comandos têm prioridade.

Campos de configuração

Para obter a referência de campos mais precisa e atualizada, consulte o powerpages.config.json esquema. Adicione a propriedade correspondente $schema ao seu ficheiro de configuração para permitir validação e autocompletamento em editores que suportem JSON Schema.

Exemplo powerpages.config.json

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

Transferir um site de SPA

Use o comando pac pages download-code-site para transferir o código de um site existente para um diretório local para fins de edição ou de cópia de segurança.

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

Ativar e testar o seu site

1. Vai a Power Pages.
2. Selecione Sites inativos, encontre o seu site e selecione Reativar.
3. Quando o site estiver ativo, aceda ao URL do seu site para verificar a implementação.

Estrutura e configuração do projeto

Um esquema de projeto consistente ajuda a garantir o comportamento correto de carregamento.

/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

Use o ficheiro powerpages.config.json opcional para personalizar a forma como o comando upload-code-site funciona.

Divisão de código e limpeza de pacotes

À medida que uma aplicação de página única cresce, um único pacote JavaScript torna-se grande e lento a carregar. As ferramentas modernas de compilação resolvem isto através da divisão de código, que divide a aplicação em partes mais pequenas que o navegador descarrega a pedido (por exemplo, apenas quando o utilizador navega para uma rota específica). Cada bloco é emitido com um hash de conteúdo no nome do ficheiro, como Dashboard-BSbmIXoe.js, para que os navegadores possam armazená-lo em cache durante longos períodos e só voltar a descarregá-lo quando o seu conteúdo muda.

A divisão de código introduz uma consideração de implementação exclusiva dos sites Power Pages do tipo SPA: como cada compilação produz novos nomes de ficheiros com hash, execuções repetidas de upload-code-site deixariam no site os ficheiros antigos com hash. Ao longo de várias implementações, estes segmentos órfãos acumulam-se nos web-files do site. O campo bundleFilePatterns em powerpages.config.json existe para os remover.

Ativar divisão de código

A divisão de código é gerida pela tua ferramenta de construção front-end, não pelo Power Pages, por isso a abordagem depende do framework e do bundler que usas. A técnica mais comum é carregar partes da aplicação com importações dinâmicas, muitas vezes aplicadas ao nível da rota ou da visualização, para que cada secção só seja descarregada quando o utilizador a acede (carregamento preguiçoso).

Bundlers como Vite, webpack e esbuild também podem agrupar módulos em blocos nomeados explicitamente. Para a configuração exata, consulta a documentação do teu framework e do bundler.

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

Qualquer que seja a abordagem escolhida, o resultado é o mesmo, e é a parte que importa para a implementação: a build emite múltiplos ficheiros de saída, cada um com um hash de conteúdo no seu nome. Como esses hashes mudam sempre que o conteúdo de um ficheiro muda, cada build produz um conjunto diferente de nomes de ficheiros. As secções seguintes explicam como manter os seus ambientes Dataverse limpos à medida que esses nomes mudam.

Como upload-code-site limpa bundles obsoletos

Antes de carregar os seus ativos compilados, upload-code-site elimina todos os ficheiros nos web-files do site que correspondam a um padrão de carateres universais em bundleFilePatterns, e depois carrega a compilação atual. Este comportamento de apagar e depois carregar mantém o conjunto de ficheiros implementado idêntico ao teu último resultado compilado, em vez de sobrepor cada build à anterior.

Para que a limpeza funcione, os padrões de carateres universais em bundleFilePatterns têm de corresponder aos nomes dos ficheiros gerados pela compilação. Existem duas formas de os manter precisos, dependendo de como a tua ferramenta de construção nomeia ficheiros.

Opção 1: Listar diretamente os padrões de carateres universais

Muitas ferramentas de compilação mantêm um prefixo de nome estável e alteram apenas o hash do conteúdo, como index-[hash].js. Quando os nomes dos ficheiros de saída seguem um padrão previsível como este, liste um padrão de curingas para cada um em bundleFilePatterns. Não são necessárias ferramentas adicionais:

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

Um padrão de caráter universal como index-*.js corresponde a esse ficheiro em todas as compilações, independentemente do hash. Adicione uma entrada por ficheiro de saída e adicione um novo padrão sempre que a sua build começar a produzir um novo ficheiro de saída.

Opção 2: Gerar padrões de carateres universais com um script pós-compilação

Use esta abordagem quando os nomes dos seus ficheiros de saída não seguem um padrão previsível, ou quando a sua aplicação produz muitos ficheiros cujos nomes mudam à medida que adiciona e remove rotas, o que torna uma lista mantida manualmente propensa a erros. Um script curto que corre após a compilação analisa a saída compilada e reescreve bundleFilePatterns com um padrão de wildcard para cada ficheiro emitido. Por exemplo, quando uma ferramenta de construção nomeia ficheiros como [name]-[hash].[ext], o script reduz-se Dashboard-BSbmIXoe.js ao padrão 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)
}

Liga o script à tua build para que corra sempre depois do bundler:

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

Agora, uma implementação faz-se com dois comandos, e o site nunca acumula fragmentos órfãos:

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

Após a compilação, powerpages.config.json reflete os bundles atuais exatos, por exemplo:

{
  "$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"
  ]
}

Autenticação e autorização

Power Pages sites SPA utilizam o mesmo modelo de segurança que os tradicionais sites Power Pages.

Configurar fornecedores de identidades

1. Vai a Power Pages.
2. Localize o seu site e selecione Editar.
3. Selecione Segurança>Provedores de Identidade.
4. Adicionar ou configurar fornecedores de identidade, como Microsoft Entra ID.
5. Cada novo site tem automaticamente um provedor Microsoft Entra ID padrão.

Aceder ao contexto de utilizador no código

Obter metadados de autenticação no cliente:

• URL da Autoridade:

  A autoridade ou URL de início de sessão para o Microsoft Entra ID é:

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

• Localize o URL da Autoridade para fornecedores de identidade configurados ao aceder às definições de configuração Power Pages><your site>>Segurança>Fornecedores de identidade>.

• Detalhes do utilizador:

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

Fluxo de amostra do 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>
    );
};

Utilizar APIs Web do Power Pages

Os programadores podem usar APIs Web Power Pages para carregar conteúdo na interface ou para criar, atualizar e eliminar registos. Antes de usar estas APIs, certifique-se de que as APIs Web necessárias estão ativadas e que as permissões de tabela e os papéis web apropriados estão devidamente configurados.

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

Configurar o desenvolvimento local ativando chamadas de API da Web a partir do localhost usando a autenticação do Microsoft Entra ID.

Os desenvolvedores precisam de ciclos de iteração mais rápidos, depuração local e recursos de recarga dinâmica ao criar aplicações. O SPA suporta esses fluxos de trabalho ao habilitar chamadas seguras de API Web a partir de localhost usando a autenticação Microsoft Entra ID (Azure AD) v1.

Esta configuração permite-lhe:

• Execute seu aplicativo localmente com suporte total à autenticação.
• Use ferramentas de desenvolvimento modernas como Vite para recarga a quente e feedback rápido.
• Evite problemas de CORS ao chamar APIs Web do Power Pages.
• Acelere o desenvolvimento sem implantar alterações no portal.

Esta configuração permite uma experiência produtiva de desenvolvimento local para o SPA, permitindo que os programadores construam, testem e iterem rapidamente com suporte completo de acesso e autenticação à API.

Etapas de configuração

1. Habilitar autenticação SPA

   1. No portal Azure, abra a aplicação Microsoft Entra registada no seu portal.
   2. Habilite a autenticação de aplicativo de página única (SPA).
   3. Adicione localhost como URI de redirecionamento usando a configuração da plataforma de aplicação de página única . Para mais informações, veja Como adicionar um URI de redirecionamento na sua aplicação.
      • Redirecionar URI: http://localhost:<port>/.

2. Adicionar configurações do site

   • Adicione estas definições de site no Power Pages:

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

3. Use ADAL.js para autenticação

   • Implemente a autenticação do lado do cliente usando ADAL.js.

   Observação

   MSAL.js não é compatível porque Power Pages usa Microsoft Entra endpoints v1, enquanto o MSAL usa v2. O formato do emissor difere entre as versões.

4. Adicionar cabeçalho de autorização

   • Inclua este cabeçalho em todas as solicitações de API da Web:

   Authorization: Bearer <id_token>
   

5. Definir a visibilidade do site como Pública

   • Essa configuração permite localhost acessar o site para fins de desenvolvimento e teste.

6. Configurar proxy de desenvolvimento

   • Se usares Vite, adiciona este código a vite.config.js para evitar problemas de CORS:

   export default defineConfig({
     plugins: [react()],
     server: {
       proxy: {
         '/_api': {
           target: 'https://site-foo.powerappsportals.com',
           changeOrigin: true,
           secure: true
         }
       }
     }
   });
   

Diferenças em relação aos sites existentes do Power Pages

A tabela seguinte resume as principais diferenças entre os sites SPA criados com esta funcionalidade e os sites tradicionais do Power Pages:

FAQ

Que suporte está disponível para os testes de unidade e integração?

Atualmente, não há suporte incorporado para testes de unidade e integração. Os criadores devem escrever e executar estes testes localmente ou dentro dos respetivos pipelines CI/CD.

Existe suporte para a integração do Power Fx usando WebAssembly?

Atualmente, esta capacidade não é suportada.

O código-fonte está disponível no Power Pages?

Atualmente, os criadores podem criar websites usando TypeScript ou GitHub Copilot Agent. Os ficheiros JavaScript e CSS compilados são acessíveis e podem ser editados no Visual Studio Code. No entanto, atualmente, a edição direta e extensiva de ficheiros HTML não é suportada.

Posso criar um componente externamente usando esta funcionalidade e levá-lo para um site do Power Pages?

Não, não pode trazer um componente gerado externamente para um site Power Pages existente usando esta funcionalidade.

Posso adicionar componentes de origem, como listas e formulários?

Atualmente, não há suporte para a adição de componentes de origem, como listas e formulários. No entanto, pode construir formulários e listas personalizados usando o framework React e APIs Web.

Como funciona o controlo de código fonte?

Os programadores podem usar a integração do Git do Power Platform para o controlo de código fonte. No entanto, apenas os ficheiros Web compilados são adicionados ao repositório, não o código fonte completo.

Estes sites suportam SEO?

Como os sites de SPA são criados com a arquitetura do React e usam composição do lado do cliente, o suporte de SEO é limitado.

Que suporte de segurança e governação do Power Pages oferecem os sites SPA?

O Power Pages aplica permissões de tabela e funções web de segurança nas chamadas da API Web, garantindo que o acesso aos dados está alinhado com os papéis do utilizador. Use o objeto window["Microsoft"].Dynamic365.Portal.User para obter propriedades de utilizador básico e personalizar experiências com base em personas de utilizador.

Além disso, os sites de SPA suportam:

• Configurações de sites públicos e privados
• Definições de governação, incluindo controlo sobre o acesso a dados anónimo
• Configurações de fornecedor de autenticação

Estas funcionalidades ajudam a garantir a integração segura e compatível de componentes personalizados dentro do Power Pages.

Informações relacionadas

• Microsoft Power Platform CLI
• Tutorial: Para utilizar o Microsoft Power Platform CLI com o Power Pages
• Use a extensão do Visual Studio Code