Opprette og distribuere et enkeltsideprogram i Power Pages

Power Pages støtter integrering av enkeltsideprogram (SPA)-kode opprettet med neste generasjons AI-assisterte verktøy, for eksempel GitHub Copilot. Med denne funksjonen kan utviklere bringe moderne, komponentbaserte frontopplevelser inn i Power Pages ved å bruke naturlig språk som kodegrensesnitt.

Når utviklere veileder, tester og finjusterer kode generert av kunstig intelligens, kan de skifte fokus fra gjentakende implementeringsoppgaver til iverksetting på høyere nivå. De kan dermed konsentrere seg om mer intuitiv, kreativ utvikling og samtidig opprettholde kvalitet og standarder i bedriftsklassen.

Denne artikkelen viser deg hvordan du gjør følgende:

• Opprett og konfigurer et SPA-prosjekt for Power Pages ved hjelp av Power Platform CLI (PAC CLI).
• Last opp og last ned koderessurser til og fra Power Pages nettstedet.
• Sett opp en sikker prosjektstruktur som kan vedlikeholdes.
• Lær viktige forskjeller mellom SPA-baserte og tradisjonelle Power Pages implementeringer.

Forutsetninger

Før du begynner, må du kontrollere at du har:

• Et Power Pages miljø med admin-rettigheter.
• Power Platform CLI (PAC CLI), versjon 1.44.x eller nyere installert og autentisert.
• Et Power Pages nettsted på versjon 9.7.4.x eller nyere.
• Tillat JavaScript-filopplastinger i dataverse miljøer.
• Et lokalt Git-repositorium med det egendefinerte frontprosjektet, for eksempel React, Angular eller Vue.

Tillat JavaScript-filopplastinger

Som standard blokkerer noen dataverse miljøer opplastingen av JavaScript-filer (.js). Hvis du støter på feilen «Import mislyktes: Vedlegget er enten ikke en gyldig type eller er for stor. Den kan ikke lastes opp eller lastes ned.»Oppdater miljøinnstillingene for å tillate denne filtypen.

Hvis du vil justere innstillingene i administrasjonssenteret for Power Platform for et miljø, gjør du følgende:

1. Logg på Power Platform-administrasjonssenteret.
2. Velg Administrer i navigasjonsruten.
3. I Administrer-ruten, velg Miljøer.
4. Velg et miljø.
5. Velg Innstillinger på kommandolinjen.
6. Utvid Produkt, og velg deretter Personvern og sikkerhet.
7. Fjern fra listen over filtyper i inndelingen js Blokkerte vedlegg.
8. Velg Lagre.

Opprett og distribuer et enkeltsideappnettsted

Power Pages SPA-områder administreres ved hjelp av PAC CLI-kommandoene upload-code-site og download-code-site. Når du har lastet opp et nettsted, vises det i Power Pages i listen Inaktive nettsteder. Aktiver nettstedet for å gjøre det tilgjengelig for brukerne.

Last opp et enkeltsideappnettsted

Bruk kommandoen pac pages upload-code-site til å laste opp lokale kilder og kompilerte ressurser til Power Pages miljøet.

Syntaks

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

Parametere

Eksempel

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

Hvis du ikke har et eksisterende prosjekt, kan du prøve eksempelimplementeringene av SPA-nettsteder ved hjelp av React, Angular og Vue.

Definere opplastingsparametere med powerpages.config.json

Tilpass virkemåten til upload-code-site kommandoen ved å inkludere en powerpages.config.json fil i rotmappen for området. Når denne filen finnes, kjører du upload-code-site bare med parameteren --rootPath . Kommandoen leser de gjenværende verdiene fra konfigurasjonsfilen. Hvis du angir både kommandolinjeargumenter og konfigurasjonsverdier, har kommandolinjeargumentene prioritet.

Konfigurasjonsfelt

For den mest nøyaktige og oppdaterte feltreferansen, se powerpages.config.jsonskjema. Legg til den samsvarende $schema egenskapen i konfigurasjonsfilen for å aktivere validering og autofullføring i redigeringsprogram som støtter JSON-skjema.

Eksempel powerpages.config.json

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

Last ned et enkeltsideappnettsted

Bruk kommandoen pac pages download-code-site til å laste ned koden for et eksisterende nettsted til en lokal katalog, slik at du kan redigere eller sikkerhetskopiere den.

Syntaks

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

Parametere

Eksempel

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

Aktiver og test nettstedet

1. Gå til Power Pages.
2. Velg Inaktive nettsteder, finn nettstedet ditt, og velg Aktiver på nytt.
3. Når nettstedet er aktivt, går du til nettadressen for nettstedet for å sjekke distribusjonen.

Prosjektstruktur og konfigurasjon

Et konsekvent prosjektoppsett bidrar til å sikre riktig opplastingsvirkemåte.

/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

Bruk den valgfrie filen powerpages.config.json til å tilpasse hvordan kommandoen upload-code-site skal fungere.

Kodesplitting og pakkeopprydding

Etter hvert som et enkeltsideprogram vokser, blir en enkelt JavaScript-pakke stor og treg til å lastes inn. Moderne byggverktøy løser dette med kodesplitting, som bryter appen inn i mindre deler som nettleseren laster ned ved behov (for eksempel bare når brukeren navigerer til en bestemt rute). Hver del sendes ut med en hash-kode for innhold i filnavnet, for eksempel , slik at Dashboard-BSbmIXoe.jsnettlesere kan bufre den i lange perioder og bare laste den ned på nytt når innholdet endres.

Kodesplitting introduserer en distribusjonsvurdering som er unik for Power Pages SPA-nettsteder: Fordi hvert bygg produserer nye hash-filnavn, vil gjentatte upload-code-site kjøringer legge igjen de gamle hash-filene på nettstedet. Etter mange utrullinger akkumuleres disse frittstående bitene i nettstedets web-files. bundleFilePatterns-feltet i powerpages.config.json er der for å rydde opp i dem.

Aktiver kodesplitting

Kodesplitting håndteres av frontbyggverktøyet, ikke av Power Pages, så tilnærmingen avhenger av rammeverket og bundleren du bruker. Den vanligste teknikken er å laste inn deler av appen med dynamisk import, ofte brukt på ruten eller visningsnivået, slik at hver inndeling bare lastes ned når en bruker navigerer til den (lat lasting).

Bundlers som Vite, webpack og esbuild kan også gruppere moduler i navngitte deler eksplisitt. Hvis du vil ha nøyaktig konfigurasjon, kan du se dokumentasjonen for rammeverket og bundleren.

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

Uansett hvilken tilnærming du velger, er resultatet det samme, og det er delen som er viktig for distribusjon: bygget avgir flere utdatafiler, hver med en innholdsnummer i navnet. Fordi disse hash-kodene endres når innholdet i en fil endres, produserer hvert bygg et annet sett med filnavn. De neste avsnittene forklarer hvordan du holder dataverse miljøene rene etter hvert som navnene endres.

Hvordan upload-code-site rydder opp foreldede bunter

Før du laster opp de kompilerte ressursene, upload-code-site sletter du alle filer i området web-files som samsvarer med et jokertegnmønster i bundleFilePatterns, og laster deretter opp gjeldende bygg. Denne virkemåten for sletting og deretter opplasting holder den distribuerte filen identisk med de nyeste kompilerte utdataene i stedet for å legge hver versjon oppå den forrige.

For at oppryddingen skal fungere, må jokertegnmønstrene i bundleFilePatterns samsvare med filnavnene byggingen din genererer. Det finnes to måter å holde dem nøyaktige på, avhengig av hvordan byggeverktøyet navngir filer.

Alternativ 1: Vise jokertegnmønstre direkte

Mange byggverktøy har et stabilt navneprefiks og endrer bare innholdsnummeret, for eksempel index-[hash].js. Når utdatafilnavnene følger et forutsigbart mønster som dette, viser du et jokertegnmønster for hver av dem i bundleFilePatterns. Ingen ekstra verktøy er nødvendig:

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

Et jokertegnmønster som index-*.js samsvarer med denne filen på hvert bygg, uavhengig av hash-koden. Legg til én oppføring per utdatafil, og legg til et nytt mønster når bygget begynner å produsere en ny utdatafil.

Alternativ 2: Generer jokertegnmønstre med et skript etter bygg

Bruk denne fremgangsmåten når utdatafilnavnene ikke følger et forutsigbart mønster, eller når appen produserer mange filer med navn som endres når du legger til og fjerner ruter, noe som gjør en feilutsatt liste for hånd. Et kort skript som kjøres etter bygget, skanner kompilerte utdata og skrives bundleFilePatterns om med et jokertegnmønster for hver fil som sendes ut. Når et byggverktøy for eksempel navngir filer som [name]-[hash].[ext], reduseres Dashboard-BSbmIXoe.js skriptet til mønsteret 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)
}

Koble skriptet til bygget, slik at det alltid kjører etter bundleren:

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

Nå består en utrulling av to kommandoer, og nettstedet samler aldri opp frittstående biter:

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

Etter bygget gjenspeiler powerpages.config.json du nøyaktig gjeldende bunter, for eksempel:

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

Godkjenning og autorisasjon

Power Pages SPA-nettsteder bruker samme sikkerhetsmodell som tradisjonelle Power Pages nettsteder.

Konfigurer identitetsleverandører

1. Gå til Power Pages.
2. Finn nettstedet ditt, og velg Rediger.
3. Velgsikkerhetsidentitetsleverandører>.
4. Legg til eller konfigurer identitetsleverandører, for eksempel Microsoft Entra ID.
5. Hvert nye område har automatisk en standardleverandør Microsoft Entra ID.

Få tilgang til brukerkontekst i kode

Hent metadata for godkjenning på klienten:

• Nettadresse til instans:

  Myndigheten eller påloggings-URL-adressen for Microsoft Entra ID er:

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

• Finn url-adressen Autorisitet for andre konfigurerte identitetsleverandører ved å gå til Power Pages><your site>>Security>Identity providers> configuration settings.

• Brukerdetaljer:

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

Eksempel på React-flyt

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

Bruke Power Pages web-API-er

Utviklere kan bruke Power Pages web-API-er til å laste inn innhold i brukergrensesnittet eller til å opprette, oppdatere og slette poster. Før du bruker disse API-ene, må du kontrollere at de nødvendige web-API-ene er aktivert, og at riktige tabelltillatelser og nettroller er riktig konfigurert.

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

Konfigurer lokal utvikling ved å aktivere web-API-anrop fra localhost ved hjelp av Microsoft Entra ID-godkjenning

Utviklere trenger raskere gjentakelsessykluser, lokal feilsøking og hurtiginnlastingsfunksjoner når de bygger programmer. SPA støtter disse arbeidsflytene ved å aktivere sikre web-API-kall fra localhost ved hjelp av Microsoft Entra ID (Azure AD) v1-godkjenning.

Med dette oppsettet kan du gjøre følgende:

• Kjør appen lokalt med full godkjenningsstøtte.
• Bruk moderne utviklingsverktøy som Vite for hurtiglasting og rask tilbakemelding.
• Unngå CORS-problemer når du kaller Power Pages Web API-er.
• Få fart på utviklingen uten å distribuere endringer i portalen.

Denne konfigurasjonen muliggjør en produktiv lokal utviklingsopplevelse for SPA, slik at utviklere kan bygge, teste og iterere raskt med full API-tilgang og godkjenningsstøtte.

Konfigurasjonstrinn

1. Aktiver SPA-godkjenning

   1. Åpne Azure-portalen i Microsoft Entra-appen som er registrert for portalen.
   2. Aktiver godkjenning av enkeltsideprogram (SPA ).
   3. Legg til localhost som en omadresserings-URI ved hjelp av plattformkonfigurasjonen for enkeltsiders programplattform . Hvis du vil ha mer informasjon, kan du se Slik legger du til en omadresserings-URI i programmet.
      • Omadresserings-URI: http://localhost:<port>/.

2. Legg til områdeinnstillinger

   • Legg til disse områdeinnstillingene i Power Pages:

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

3. Bruk ADAL.js for godkjenning

   • Implementere godkjenning på klientsiden ved hjelp av ADAL.js.

   Notat

   MSAL.js er ikke kompatibel fordi Power Pages bruker Microsoft Entra v1-endepunkter, mens MSAL bruker v2. Utstederformatet er forskjellig mellom versjoner.

4. Legg til autorisasjonshode

   • Inkluder denne overskriften i alle web-API-forespørsler:

   Authorization: Bearer <id_token>
   

5. Angi synlighet for område til Offentlig

   • Denne innstillingen gir localhost tilgang til området for utviklings- og testformål.

6. Konfigurer utviklingsproxy

   • Hvis du bruker Vite, kan du legge til denne koden for å vite.config.js unngå PROBLEMER med CORS:

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

Forskjeller fra eksisterende Power Pages områder

Tabellen nedenfor oppsummerer viktige forskjeller mellom SPA-områder som er opprettet med denne funksjonen og tradisjonelle Power Pages nettsteder:

vanlige spørsmål

Hvordan er støtten for enhets- og integrasjonstesting?

For øyeblikket er det ingen innebygd støtte for enhets- og integrasjonstesting. Utviklere må skrive og kjøre disse testene lokalt eller i CI/CD-kanalene.

Finnes det støtte for Power Fx-integrasjon ved hjelp av WebAssembly?

Denne funksjonaliteten støttes for øyeblikket ikke.

Er kildekode tilgjengelig i Power Pages?

For øyeblikket kan beslutningstakere bygge nettsteder ved hjelp av TypeScript eller GitHub Copilot Agent. De kompilerte JavaScript- og CSS-filene er tilgjengelige og kan redigeres i Visual Studio Code. Direkte og omfattende redigering av HTML-filer støttes imidlertid ikke for øyeblikket.

Kan jeg opprette en komponent eksternt ved hjelp av denne funksjonen og hente den til et Power Pages nettsted?

Nei, du kan ikke hente en eksternt generert komponent til et eksisterende Power Pages nettsted ved hjelp av denne funksjonen.

Kan jeg legge til standardkomponenter som lister og skjemaer?

Å legge til standardkomponenter som lister og skjemaer støttes for øyeblikket ikke. Du kan imidlertid bygge egendefinerte skjemaer og lister ved hjelp av React-rammeverket og web-API-er.

Hvordan fungerer kildekontroll?

Utviklere kan bruke Power Platform Git-integrering til kildekontroll. Imidlertid er det bare de kompilerte nettfilene som legges til i repositoriet, ikke den fullstendige kildekoden.

Støtter disse nettstedene SEO?

Fordi enkeltsideappnettsteder er bygd med React-rammeverket og bruker gjengivelse på klientsiden, er SEO-støtte begrenset.

Hvilken Power Pages støtte for sikkerhet og styring tilbyr SPA-nettsteder?

Power Pages fremtvinger tabelltillatelser og nettroller for sikkerhet på web-API-kall, slik at datatilgangen samsvarer med brukerroller. Bruk objektet window["Microsoft"].Dynamic365.Portal.User til å hente egenskaper for Basic-bruker og skreddersy funksjoner basert på brukeridentiteter.

I tillegg støtter enkeltsideappnettsteder følgende:

• Konfigurasjoner for offentlige og private nettsteder
• Styringsinnstillinger, inkludert kontroll over anonym datatilgang
• Konfigurasjoner for godkjenningsleverandør

Disse funksjonene bidrar til å sikre sikker og kompatibel integrering av egendefinerte komponenter i Power Pages.

Relatert informasjon

• Microsoft Power Platform CLI
• Tutorial: Bruk Microsoft Power Platform CLI med Power Pages
• Bruk Visual Studio Code-utvidelsen