Dela via

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å. Detta möjliggör en mer intuitiv och kreativ utveckling samtidigt som kvalitet och standarder i företagsklass upprätthå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.

Anteckning

  • En SPA-webbplats är en Power Pages webbplats som körs helt i användarens webbläsare (återgivning på klientsidan). Till skillnad från traditionella Power Pages platser hanteras SPA-platser endast via cli-verktyg (källkod och kommandoradsgränssnitt).
  • Power Platform Git-integrering stöds inte för webbplatser med appar på en sida (SPA) i Power Pages.

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 (). 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-administratörscentret 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. Välj Inställningar i kommandofältet.
  6. Utöka Produkt och välj sedan Sekretess och säkerhet.
  7. I avsnittet Blockerade bifogade filer tar du bort 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>]

Parametrar

Parameter Alias Obligatoriskt Beskrivning
--rootPath -rp Ja Lokal mapp som innehåller webbplatsens källfiler
--compiledPath -cp Nej Sökväg till kompilerade tillgångar, till exempel React
--siteName -sn Nej Visningsnamn för din Power Pages webbplats

Exempel

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

Anpassa -kommandots beteende genom att inkludera en -fil på din webbplats. Placera den här konfigurationsfilen i webbplatsens rotmapp. När du använder konfigurationsbaserade webbplatsuppladdningar kör du kommandot med bara parametern . Kommandot läser automatiskt andra värden, till exempel sökvägen till kompilerade resurser och webbplatsens visningsnamn, från -filen. Om du anger både kommandoradsargument och konfigurationsvärden har kommandoradsargumenten företräde.

Exempel :

{
  "siteName": "Contoso Bank",
  "defaultLandingPage": "index.html",
  "compiledPath": "C:\\PowerPages\\your-project\\dist"
}

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]

Parametrar

Parameter Alias Obligatoriskt Beskrivning
--environment -env Nej Dataverse-miljö (GUID eller fullständig URL). Standardvärdet är din aktiva autentiseringsprofil
--path -p Ja Lokal katalog för att ladda ned webbplatskoden
--webSiteId -id Ja Webbplatsens post-GUID för Power Pages SPA-webbplatsen
--overwrite -o Nej Skriv över befintliga filer i målkatalogen om sådana finns

Exempel

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.

Tips

Alla senare -kommandon uppdaterar automatiskt den aktiva webbplatsen.

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 -filen för att anpassa hur -kommandot fungerar.

Autentisering och auktorisering

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

Konfigurera identitetsprovider

  1. Gå till Power Pages.
  2. Leta reda på din webbplats och välj Redigera.
  3. Välj SäkerhetIdentitetsleverantö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 bör du se till att de webb-API:er som krävs ä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 aktivera säkra webb-API-anrop från localhost med hjälp av 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.

Viktigt!

  • Använd endast Microsoft Entra v1-slutpunkter för autentisering.
  • Ägarautentisering stöds endast i portalversionerna 9.7.6.6 eller senare.
  • Använd endast de här inställningarna i utvecklingsmiljöer.

Konfigurationssteg

  1. Aktivera SPA-autentisering

    1. I https://portal.azure.com öppnar du den Microsoft Entra app som är registrerad för portalen.
    2. Aktivera SPA-autentisering (Single Page Application).
    3. Lägg till som en omdirigerings-URI med hjälp av ensidesapplikationens plattformskonfiguration. Mer information finns i Så här lägger du till en omdirigerings-URI i ditt program .
      • omdirigerings-URI: .

  2. Lägg till webbplatsinställningar

    • Lägg till dessa inställningar för site i Power Pages:
    Authentication/BearerAuthentication/Enabled = true
Authentication/BearerAuthentication/Protocol = OpenIdConnect
Authentication/BearerAuthentication/Provider = AzureAD

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

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

    Anteckning

    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 du komma åt webbplatsen i utvecklings- och testsyfte.

  6. Konfigurera utvecklingsproxy

    • Om du använder Vite, lägg till detta i för 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:

Egenskap SPA webbplatsbeteende
Serveruppdatering Returnerar alltid webbplatsens rotsida och routern på klientsidan återger underordnade rutter.
Ruttkonflikter Rutter på klientsidan har företräde och en hård uppdatering återgår till rot.
Arbetsyta för sida Arbetsytor för sida stöds inte. Använd klientroutning och webbplatssidor på klientsidan. För säkerhet på sidnivå kontrollerar du tilldelade webbroller med det globala användarobjektet och återger användargränssnittet villkorligt.
Formateringsarbetsyta Formatering med formatarbetsytan stöds inte. Använd ramverkets formatmallar, till exempel CSS, CSS-in-JS eller verktygsklasser.
Lokalisering Stöd för ett språk. Implementera resursinläsning på klientsidan.
Liquid-mallanvändning Liquid-kod och Liquid-mallar stöds inte. Få åtkomst till data med hjälp av ramverkets mallmotor och webb-API:er.

Vanliga frågor och svar

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 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 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.

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 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.

  • Last updated on