Skapa och distribuera ett ensidesprogram i Power Pages

Power Pages stöder integrering av spa-kod (single-page application) som skapats med nästa generations AI-assisterade verktyg, till exempel GitHub Copilot. Med den här funktionen kan utvecklare använda moderna, komponentbaserade klientdelsupplevelser i Power Pages med naturligt språk som kodningsgränssnitt.

Genom att vägleda, testa och förfina AI-genererad kod kan tillverkare skifta sitt fokus från repetitiva implementeringsuppgifter till orkestrering på högre nivå. Den här metoden ger mer intuitiv, kreativ utveckling samtidigt som kvalitet och standarder i företagsklass bibehålls.

Den här artikeln visar hur du gör följande:

• Skapa och konfigurera ett SPA-projekt för Power Pages med hjälp av Power Platform CLI (PAC CLI).
• Ladda upp och ladda ner kodfiler till och från din Power Pages-webbplats.
• Skapa en säker och underhållsbar projektstruktur.
• Lär dig viktiga skillnader mellan SPA-baserade och traditionella Power Pages implementeringar.

Förutsättningar

Innan du kan börja bör du kontrollera att du har:

• En Power Pages miljö med admin privileges.
• Power Platform CLI (PAC CLI) version 1.44.x eller senare installerad och autentiserad.
• En Power Pages webbplats på version 9.7.4.x eller senare.
• Tillåt JavaScript-filöverföringar i Dataverse-miljöer.
• En lokal Git-lagringsplats med ditt anpassade klientdelsprojekt, till exempel React, Angular eller Vue.

Tillåt JavaScript-filuppladdningar

Som standard blockerar vissa Dataverse-miljöer uppladdningen av JavaScript-filer (.js). Om du får felet "Importen misslyckades: Den bifogade filen är antingen inte en giltig typ eller för stor. Det går inte att ladda upp eller ladda ned.", uppdatera miljöinställningarna så att den här filtypen tillåts.

Följ dessa steg om du vill justera inställningarna i Power Platform administrationscentret för en miljö:

1. Logga in på Power Platform-administratörscenter.
2. I navigeringsfönstret väljer du Hantera.
3. I rutan Hantera väljer du Miljöer.
4. Välj en miljö.
5. I kommandofältet väljer du Inställningar.
6. Utöka Produkt och välj sedan Sekretess och säkerhet.
7. I avsnittet Blockerade bifogade filer tar du bort js från listan över filnamnstillägg.
8. Välj Spara.

Skapa och distribuera en SPA-webbplats

Power Pages SPA-platser hanteras med PAC CLI-kommandona upload-code-site och download-code-site. När du har laddat upp en webbplats visas den i listan Power Pages i listan Inaktiva webbplatser. Aktivera webbplatsen som du vill göra tillgänglig för användarna.

Ladda upp en SPA-webbplats

Använd kommandot pac pages upload-code-site för att ladda upp din lokala källa och kompilerade tillgångar till din Power Pages miljö.

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"

Om du inte har ett befintligt projekt kan du prova exempelimplementeringarna av SPA-webbplatser med React, Angular och Vue.

Definiera uppladdningsparametrar med powerpages.config.json

Anpassa kommandots upload-code-site beteende genom att inkludera en powerpages.config.json fil i webbplatsens rotmapp. När den här filen finns, kör du upload-code-site endast med parametern --rootPath. Kommandot läser de återstående värdena från konfigurationsfilen. Om du anger både kommandoradsargument och konfigurationsvärden har kommandoradsargumenten företräde.

Konfigurationsfält

Den mest exakta och up-to-date-fältreferensen finns i powerpages.config.json schemat. Lägg till matchande $schema egenskap i konfigurationsfilen för att aktivera validering och automatisk komplettering i redigeringsprogram som stöder JSON-schema.

Exempel på powerpages.config.json

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

Ladda ned en SPA-webbplats

Använd kommandot pac pages download-code-site för att ladda ned en befintlig webbplatsens kod till en lokal katalog för redigering eller säkerhetskopiering.

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

Aktivera och testa din webbplats

1. Gå till Power Pages.
2. Välj Inaktiva webbplatser, leta reda på din plats och välj Återaktivera.
3. När webbplatsen är aktiv går du till webbplatsens URL för att kontrollera distributionen.

Projektstruktur och konfiguration

Med en konsekvent projektlayout kan du säkerställa att uppladdningen sker korrekt.

/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

Använd den valfria powerpages.config.json-filen för att anpassa hur upload-code-site-kommandot fungerar.

Koddelning och upprensning av bundlar

När ett ensidesprogram växer blir ett enda JavaScript-paket stort och långsamt att läsa in. Moderna byggverktyg löser det här problemet med koddelning. Den här tekniken delar upp appen i mindre segment som webbläsaren laddar ned på begäran (till exempel endast när användaren navigerar till en specifik väg). Varje segment genereras med en innehållshash i filnamnet, till exempel Dashboard-BSbmIXoe.js, så att webbläsare kan cachelagrar det under långa perioder och ladda ned det igen endast när innehållet ändras.

Koddelning medför en driftsättningsaspekt som är specifik för Power Pages SPA-webbplatser: eftersom varje build genererar nya hashade filnamn skulle de gamla hashade filerna bli kvar på webbplatsen vid upprepade upload-code-site-körningar. Under många distributioner ackumuleras dessa överblivna segment i webbplatsens web-files. Fältet bundleFilePatterns i powerpages.config.json finns för att rensa dem.

Aktivera uppdelning av kod

Koddelning hanteras av klientdelsverktyget, inte av Power Pages, så metoden beror på vilket ramverk och bundler du använder. Den vanligaste tekniken är att ladda in delar av appen med dynamisk import, ofta på rout- eller vynivå, så att varje del bara laddas ned när användaren navigerar till den (lazy loading).

Paketerare som Vite, webpack och esbuild kan också gruppera moduler i namngivna segment explicit. Den exakta konfigurationen finns i dokumentationen för ditt ramverk och 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

Oavsett vilken metod du väljer är resultatet detsamma och det är den del som är viktig för distributionen: bygget genererar flera utdatafiler, var och en med en innehållshash i sitt namn. Eftersom dessa hashvärden ändras när en fils innehåll ändras, skapar varje version en annan uppsättning filnamn. I nästa avsnitt förklaras hur du håller dina Dataverse-miljöer rena när namnen ändras.

Hur upload-code-site rensar upp föråldrade paket

Innan du laddar upp dina kompilerade tillgångar tar upload-code-site bort alla filer i webbplatsens web-files som matchar ett jokerteckenmönster i bundleFilePatterns, och laddar sedan upp den aktuella versionen. Det här beteendet för att ta bort och sedan ladda upp håller den distribuerade filuppsättningen identisk med dina senaste kompilerade utdata i stället för att lägga varje version ovanpå den tidigare.

För att rensningen ska fungera måste jokerteckenmönstren i bundleFilePatterns stämma överens med filnamnen som din version genererar. Det finns två sätt att hålla dem korrekta, beroende på hur byggverktyget namnger filer.

Alternativ 1: Visa mönster för jokertecken direkt

Många byggverktyg har ett stabilt namnprefix och ändrar bara innehållshashen, till exempel index-[hash].js. När utdatafilnamnen följer ett förutsägbart mönster som det här anger du ett jokerteckenmönster för var och en i bundleFilePatterns. Inga extra verktyg behövs:

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

Ett jokerteckenmönster som index-*.js matchar filen i varje version, oavsett hash. Lägg till en post per utdatafil och lägg till ett nytt mönster när bygget börjar producera en ny utdatafil.

Alternativ 2: Generera jokerteckenmönster med ett skript som körs efter bygget

Använd den här metoden när utdatafilnamnen inte följer ett förutsägbart mönster, eller när din app producerar många filer vars namn ändras när du lägger till och tar bort vägar, vilket gör en handhållen lista felbenägen. Ett kort skript som körs efter bygget genomsöker kompilerade utdata och skriver om bundleFilePatterns med ett jokerteckenmönster för varje genererad fil. När ett byggverktyg till exempel ger filer namn som [name]-[hash].[ext], reducerar skriptet Dashboard-BSbmIXoe.js till mönstret 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)
}

Koppla skriptet till din version så att det alltid körs efter paketeraren:

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

Nu är en distribution två kommandon och webbplatsen ackumulerar aldrig överblivna segment:

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

Efter bygget powerpages.config.json visar de exakta aktuella paketen, till exempel:

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

Autentisering och auktorisering

Power Pages SPA-webbplatser använder samma säkerhetsmodell som traditionella Power Pages webbplatser.

Konfigurera identitetsprovidrar

1. Gå till Power Pages.
2. Leta reda på din webbplats och välj Redigera.
3. Välj Säkerhet>Identitetsleverantörer.
4. Lägg till eller konfigurera identity providers, till exempel Microsoft Entra ID.
5. Varje ny webbplats har automatiskt en standardprovider för Microsoft Entra ID.

Få åtkomst till användarkontext i kod

Hämta autentiseringsmetadata på klienten:

• URL för utfärdare:

  Utfärdaren eller inloggnings-URL:en för Microsoft Entra ID är:

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

• Leta reda på URL för utfärdare för andra konfigurerade identitetsproviders genom att gå till konfigurationsinställningarna Power Pages><your site>>Säkerhet>Identitetproviders>.

• Användarinformation:

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

Exempel på React-flöde

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

Använda Power Pages webb-API:er

Utvecklare kan använda Power Pages webb-API:er för att läsa in innehåll i användargränssnittet eller för att skapa, uppdatera och ta bort poster. Innan du använder dessa API:er kontrollerar du att nödvändiga webb-API:er är aktiverade och att lämpliga tabellbehörigheter och webbroller är korrekt konfigurerade.

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

Konfigurera lokal utveckling genom att aktivera webb-API-anrop från localhost med hjälp av Microsoft Entra ID-autentisering

Utvecklare behöver snabbare iterationscykler, lokal felsökning och funktioner för snabb inläsning när de skapar program. SPA stöder dessa arbetsflöden genom att möjliggöra säkra webb-API-förfrågningar från localhost genom att använda Microsoft Entra ID (Azure AD) v1-autentisering.

Med den här konfigurationen kan du:

• Kör appen lokalt med fullständigt autentiseringsstöd.
• Använd moderna utvecklingsverktyg som Vite för snabb omladdning och snabb feedback.
• Undvik CORS-problem när du anropar Power Pages-webb-API:er.
• Påskynda utvecklingen utan att distribuera ändringar till portalen.

Den här konfigurationen möjliggör en produktiv lokal utvecklingsupplevelse för SPA, så att utvecklare kan skapa, testa och iterera snabbt med fullständig API-åtkomst och autentiseringsstöd.

Konfigurationssteg

1. Aktivera SPA-autentisering

   1. I Azure portal öppnar du den Microsoft Entra app som är registrerad för portalen.
   2. Aktivera SPA-autentisering (Single Page Application).
   3. Lägg till localhost som omdirigerings-URI med hjälp av plattformskonfigurationen Enkelsidesapp. Mer information finns i Lägga till en omdirigerings-URI i ditt program.
      • omdirigerings-URI: http://localhost:<port>/.

2. Lägg till webbplatsinställningar

   • Lägg till de här webbplatsinställningarna i Power Pages:

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

3. Använda ADAL.js för autentisering

   • Implementera autentisering på klientsidan med hjälp avADAL.js.

   Anmärkning

   MSAL.js är inte kompatibelt eftersom Power Pages använder Microsoft Entra v1-slutpunkter, medan MSAL använder v2. Utfärdarformatet skiljer sig mellan olika versioner.

4. Lägg till auktoriseringsheader

   • Inkludera den här rubriken i alla webb-API-begäranden:

   Authorization: Bearer <id_token>
   

5. Ange webbplatsens synlighet till Offentlig

   • Med den här inställningen kan localhost du komma åt webbplatsen i utvecklings- och testsyfte.

6. Konfigurera utvecklingsproxy

   • Om du använder Vite lägger du till den här koden för vite.config.js att undvika CORS-problem:

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

Skillnader från befintliga Power Pages webbplatser

I följande tabell sammanfattas viktiga skillnader mellan SPA-webbplatser som skapats med den här funktionen och traditionella Power Pages webbplatser:

FAQ

Vilket stöd finns för enhets- och integrationstestning?

För närvarande finns det inget inbyggt stöd för enhets- och integrationstestning. Utvecklare bör skriva och köra dessa tester lokalt eller i sina CI/CD-pipelines.

Finns det stöd för Power Fx-integration med WebAssembly?

Denna funktion stöds för närvarande inte.

Är källkoden tillgänglig i Power Pages?

För närvarande kan tillverkare skapa webbplatser med Hjälp av TypeScript eller GitHub Copilot Agent. Kompilerade JavaScript- och CSS-filer är tillgängliga och kan redigeras i Visual Studio Code. Direkt och omfattande redigering av HTML-filer stöds dock inte för närvarande.

Kan jag skapa en komponent externt med hjälp av den här funktionen och ta den till en Power Pages webbplats?

Nej, du kan inte ta med en externt genererad komponent till en befintlig Power Pages webbplats med hjälp av den här funktionen.

Kan jag lägga till färdiga komponenter som listor och formulär?

Det finns för närvarande inte stöd för att lägga till färdiga komponenter som listor och formulär. Du kan dock skapa anpassade formulär och listor med hjälp av React-ramverket och webb-API:er.

Kan jag aktivera en SPA-webbplats som en PWA från arbetsytan Konfigurera?

No. SPA-webbplatser stöder inte inställningen progressiv webbapp (PWA) i konfigurera arbetsyta. Den här begränsningen innebär att du inte kan använda avsnittet Mobil för att aktivera en webbplats som en PWA. Om du vill lägga till PWA-funktioner, till exempel installationsbara appupplevelser och offlinesidor, implementerar du dem i din ramverkskod. Du kan till exempel lägga till ett webbappsmanifest och en tjänstarbetare.

Hur fungerar källkontrollen?

Utvecklare kan använda Power Platform Git-integration för källkontroll. Det är dock bara de kompilerade webbfilerna som läggs till på lagringsplatsen, inte den fullständiga källkoden.

Har dessa webbplatser stöd för SEO?

Eftersom SPA-webbplatser är byggda med React-ramverket och använder återgivning på klientsidan är SEO-stödet begränsat.

Vilket säkerhets- och styrningsstöd för Power Pages erbjuder SPA-webbplatser?

Power Pages framtvingar tabellbehörigheter och säkerhetswebbroller i webb-API-anrop, vilket säkerställer att dataåtkomsten överensstämmer med användarroller. Använd objektet window["Microsoft"].Dynamic365.Portal.User för att hämta grundläggande användaregenskaper och skräddarsy upplevelser baserat på användarprofiler.

SPA webbplatser har dessutom stöd för:

• Offentliga och privata webbplatskonfigurationer
• Styrningsinställningar, inklusive kontroll över anonym dataåtkomst
• Autentiserings- och providerkonfigurationer

De här funktionerna hjälper till att säkerställa säker och kompatibel integrering av anpassade komponenter i Power Pages.

Relaterad information

• Microsoft Power Platform CLI
• Tutorial: Använd Microsoft Power Platform CLI med Power Pages
• Använd tillägget Visual Studio Code