Freigeben über

Erstellen und Bereitstellen einer einzelseitigen Anwendung in Power Pages

Power Pages unterstützt die Integration von Spa-Code (Single Page Application), der mit KI-unterstützten Tools der nächsten Generation erstellt wurde, z. B. GitHub Copilot. Mit dieser Funktion können Entwickler moderne, komponentenbasierte Front-End-Oberflächen in Power Pages mithilfe natürlicher Sprache als Codierungsschnittstelle integrieren.

Durch die Anleitung, das Testen und die Verfeinerung von KI-generiertem Code können Entwickler ihren Fokus von sich wiederholenden Implementierungsaufgaben auf die Orchestrierung auf höherer Ebene verlagern. Dies ermöglicht eine intuitivere und kreativere Entwicklung, während die Qualität und Standards auf Unternehmensniveau beibehalten werden.

Dieser Artikel zeigt Ihnen, wie das geht:

  • Erstellen und Einrichten eines SPA-Projekts für Power Pages mithilfe der Power Platform CLI (PAC CLI).
  • Laden Sie Coderessourcen auf Ihre Power Pages-Seite hoch und herunter.
  • Eine sichere und wartbare Projektstruktur einrichten.
  • Lernen Sie wichtige Unterschiede zwischen SPA-basierten und herkömmlichen Power Pages Implementierungen kennen.

Notiz

  • Eine SPA-Website ist eine Power Pages Website, die vollständig im Browser des Benutzers ausgeführt wird (clientseitiges Rendering). Im Gegensatz zu herkömmlichen Power Pages Websites werden SPA-Websites nur über Quellcode- und Befehlszeilenschnittstellentools verwaltet.
  • Power Platform Git-Integration wird für Single-Page Application (SPA)-Websites in Power Pages nicht unterstützt.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über:

  • Eine Power Pages Umgebung mit admin-Berechtigungen.
  • Power Platform CLI (PAC CLI) Version 1.44.x oder höher ist installiert und authentifiziert.
  • Eine Power Pages Website auf Version 9.7.4.x oder höher.
  • JavaScript-Dateiuploads in Dataverse-Umgebungen zulassen.
  • Ein lokales Git-Repository mit Ihrem benutzerdefinierten Front-End-Projekt, z. B. React, Angular oder Vue.

JavaScript-Dateiuploads zulassen

Standardmäßig blockieren einige Dataverse-Umgebungen den Upload von JavaScript-Dateien (). Wenn der Fehler "Import fehlgeschlagen: Die Anlage ist entweder kein gültiger Typ oder zu groß. Sie kann weder hoch- noch heruntergeladen werden." auftritt, aktualisieren Sie Ihre Umgebungseinstellungen, um das Hochladen dieses Dateityps zu erlauben.

Um die Einstellungen im Power Platform Admin Center für eine Umgebung anzupassen, gehen Sie wie folgt vor:

  1. Melden Sie sich beim Power Platform Admin Center an.
  2. Wählen Sie im Navigationsbereich die Option Verwalten aus.
  3. Wählen Sie im Bereich VerwaltenUmgebungen aus.
  4. Wählen Sie eine Umgebung aus.
  5. Wählen Sie in der Befehlsleiste Einstellungen aus.
  6. Erweitern Sie Produkt und wählen Sie dann Datenschutz und Sicherheit aus.
  7. Im Abschnitt "Blockierte Anlagen" entfernen Sie aus der Liste der Dateierweiterungen.
  8. Wählen Sie Speichern aus.

Eine SPA-Website entwickeln und bereitstellen

Power Pages SPA-Websites werden mithilfe der PAC CLI-Befehle upload-code-site und download-code-site verwaltet. Nachdem Sie eine Website hochgeladen haben, wird sie in Power Pages in der Liste Inaktive Websites angezeigt. Aktivieren der Website, um Sie für Benutzer verfügbar zu machen.

SPA-Website hochladen

Verwenden Sie den Befehl pac pages upload-code-site, um Ihre lokale Quelle und kompilierte Ressourcen in Ihre Power Pages Umgebung hochzuladen.

Syntax

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

Parameter

Parameter Alias Erforderlich Beschreibung
--rootPath -rp Ja Lokaler Ordner mit den Quelldateien Ihrer Website
--compiledPath -cp Nein Pfad zu kompilierten Assets, z. B. React
--siteName -sn Nein Anzeigename für Ihre Power Pages-Website

Beispiel

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

Wenn Sie noch kein Projekt haben, probieren Sie die Beispielimplementierungen von SPA-Websites mit React, Angular und Vue aus.

Definieren von Uploadparametern mit

Passen Sie das Verhalten des Befehls an, indem Sie eine Datei in Ihre Website einfügen. Platzieren Sie diese Konfigurationsdatei im Stammordner der Website. Wenn Sie konfigurationsbasierte Standort-Uploads verwenden, führen Sie den Befehl nur mit dem Parameter aus. Der Befehl liest automatisch andere Werte, z. B. den Pfad der kompilierten Anlagen und den Anzeigenamen des Standorts, aus der Datei. Wenn Sie sowohl Befehlszeilenargumente als auch Konfigurationswerte angeben, haben die Befehlszeilenargumente Vorrang.

Beispiel :

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

Eine SPA-Website herunterladen

Verwenden Sie den Befehl Pac-Seiten download-code-site Befehl, um den Code eines vorhandenen Standorts zu Bearbeitungs- oder Sicherungszwecken in ein lokales Verzeichnis herunterzuladen.

Syntax

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

Parameter

Parameter Alias Erforderlich Beschreibung
--environment -env Nein Dataverse -Umgebung (GUID oder vollständige URL). Standardmäßig wird Ihr aktives Authentifizierungsprofil verwendet
--path -p Ja Lokales Verzeichnis zum Herunterladen des Standortcodes
--webSiteId -id Ja Websitedatensatz-GUID der Power Pages SPA-Website
--overwrite -o Nein Vorhandene Dateien im Zielverzeichnis überschreiben, falls sie bereits existieren

Beispiel

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

Website aktivieren und testen

  1. Wechseln Sie zu Power Pages.
  2. Wählen Sie Inaktive Sites suchen Sie Ihre Site und wählen Wieder aktivieren.
  3. Wenn die Website aktiv ist, rufen Sie die URL Ihrer Website auf, um die Bereitstellung zu überprüfen.

Trinkgeld

Bei jedem späteren Befehl wird die aktive Site automatisch aktualisiert.

Projektstruktur und Konfiguration

Ein konsistentes Projektlayout trägt dazu bei, ein korrektes Upload-Verhalten sicherzustellen.

/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

Verwenden Sie die optionale Datei, um die Funktionsweise des Befehls anzupassen.

Authentifizierung und Autorisierung

Power Pages SPA-Websites verwenden dasselbe Security-Modell wie herkömmliche Power Pages Websites.

Identitätsanbieter konfigurieren

  1. Wechseln Sie zu Power Pages.
  2. Wählen Sie Ihre Website, und wählen Sie dann Bearbeiten aus.
  3. Wählen SieSicherheitsidentitätsanbieter aus.
  4. Fügen Sie Identity-Anbieter hinzu oder richten Sie sie ein, z. B. Microsoft Entra ID.
  5. Jede neue Seite hat automatisch einen Standard-Microsoft-Entra-ID-Anbieter.

Auf den Benutzerkontext im Code zugreifen

Authentifizierungsmetadaten auf dem Client abrufen:

  • Autoritative URL:

    Die Autoritäts- oder Anmelde-URL für Microsoft Entra ID lautet:

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

  • Suchen Sie die Authority-URL für andere konfigurierte Identitätsanbieter, indem Sie zu den Power Pages><your site>>Sicherheits>Identitätsanbieter-Konfigurationseinstellungen gehen.

  • Benutzerdetails:

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

Beispiel für einen React-Flow

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

Verwenden von Power Pages Web-APIs

Entwickler können Power Pages Web-APIs nutzen, um Inhalte in die Benutzeroberfläche zu laden oder Datensätze zu erstellen, zu aktualisieren und zu löschen. Stellen Sie vor der Verwendung dieser APIs sicher, dass die erforderlichen Web-APIs aktiviert sind und die entsprechenden Tabellenberechtigungen sowie Webrollen richtig konfiguriert wurden.


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

Einrichten der lokalen Entwicklung durch Aktivieren von Web-API-Aufrufen von localhost mithilfe Microsoft Entra ID Authentifizierung

Entwickler benötigen schnellere Iterationszyklen, lokales Debuggen und Hot Reload-Funktionen beim Erstellen von Anwendungen. SPA unterstützt diese Workflows, indem sichere Web-API-Aufrufe von localhost mithilfe Microsoft Entra ID (Azure AD) v1-Authentifizierung aktiviert werden.

Mit diesem Setup können Sie:

  • Führen Sie Ihre App lokal mit vollständiger Authentifizierungsunterstützung aus.
  • Verwenden Sie moderne Entwicklungstools wie Vite für hot reload und schnelles Feedback.
  • Vermeiden Sie CORS-Probleme beim Aufrufen Power Pages Web-APIs.
  • Beschleunigen Sie die Entwicklung, ohne Änderungen am Portal bereitzustellen.

Diese Konfiguration ermöglicht eine produktive lokale Entwicklungsumgebung für SPA, sodass Entwickler schnell mit vollständigem API-Zugriff und Authentifizierungsunterstützung erstellen, testen und iterieren können.

Wichtig

  • Verwenden Sie nur Microsoft Entra v1-Endpunkte für die Authentifizierung.
  • Die Bearerauthentifizierung wird nur in Den Portalversionen 9.7.6.6 oder höher unterstützt.
  • Wenden Sie diese Einstellungen nur in Entwicklungsumgebungen an.

Konfigurationsschritte

  1. Aktivieren der SPA-Authentifizierung

    1. Öffnen Sie in https://portal.azure.com die für Ihr Portal registrierte Microsoft Entra-App.
    2. Aktivieren Sie die Single Page Application (SPA) -Authentifizierung.
    3. Fügen Sie als Umleitungs-URI mithilfe der Plattformkonfiguration Einzelseitenanwendung hinzu. Weitere Informationen finden Sie unter Hinzufügen eines Umleitungs-URI in Ihrer Anwendung .
      • Umleitungs-URI: .

  2. Hinzufügen von Websiteeinstellungen

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

  3. Verwenden von ADAL.js für die Anmeldung

    • Implementieren Sie die clientseitige Anmeldung mit ADAL.js.

    Notiz

    MSAL.js ist nicht kompatibel, da Power Pages Microsoft Entra v1-Endpunkte verwendet, während MSAL v2 verwendet. Das Ausstellerformat unterscheidet sich zwischen den Versionen.

  4. Autorisierungsheader hinzufügen

    • Fügen Sie diesen Header in alle Web-API-Anforderungen ein:
    Authorization: Bearer <id_token>

  5. Festlegen der Sichtbarkeit der Website auf "Öffentlich"

    • Diese Einstellung ermöglicht den Zugriff auf die Website für Entwicklungs- und Testzwecke.

  6. Konfigurieren des Entwicklungsproxys

    • Wenn Sie Vite verwenden, fügen Sie dies hinzu, um CORS-Probleme zu vermeiden:
    export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/_api': {
        target: 'https://site-foo.powerappsportals.com',
        changeOrigin: true,
        secure: true
      }
    }
  }
});

Unterschiede zwischen vorhandenen Power Pages Websites

In der folgenden Tabelle sind die wichtigsten Unterschiede zwischen SPA-Websites zusammengefasst, die mit diesem Feature und herkömmlichen Power Pages Websites erstellt wurden:

Funktion SPA-Website-Verhalten
Serverseitige Aktualisierung Gibt immer die Stammseite der Website zurück, und der clientseitige Router rendert Unterweiterleitungen.
Weiterleitungskonflikte Clientseitige Routen haben Vorrang, und eine harte Aktualisierung führt einen Rückgriff auf den Stamm durch.
Seiten-Arbeitsbereich Der Seiten-Arbeitsbereich wird nicht unterstützt. Verwenden Sie Clientrouting und Clientseitenseiten. Für die Sicherheit auf Seitenebene prüfen Sie die zugewiesenen Webrollen mit dem globalen Benutzerobjekt und rendern Sie die Benutzeroberfläche bedingt.
Arbeitsbereich „Stil“ Die Formatierung mit dem Stil-Arbeitsbereich wird nicht unterstützt. Verwenden Sie das Design Ihres Frameworks, z. B. CSS, CSS-in-JS oder Utility-Klassen.
Lokalisierung Einsprachen-Unterstützung Implementieren Sie das clientseitige Laden von Ressourcen.
Liquid-Vorlage Liquid-Code und Liquid-Vorlagen werden nicht unterstützt. Greifen Sie auf Daten zu, indem Sie das Vorlagen-Modul Ihrer Frameworks und Web-APIs verwenden.

Häufig gestellte Fragen

Welche Unterstützung gibt es für Unit- und Integrationstests?

Derzeit gibt es keine integrierte Unterstützung für Einheiten- und Integrationstests. Maker sollten diese Tests lokal oder innerhalb ihrer CI/CD-Pipelines schreiben und ausführen.

Gibt es Unterstützung für die Power Fx Integration mit WebAssembly?

Diese Funktion wird derzeit nicht unterstützt.

Ist Quellcode in Power Pages verfügbar?

Derzeit können Entwickler Websites mit TypeScript oder GitHub Copilot Agent erstellen. Auf die kompilierten JavaScript- und CSS-Dateien kann zugegriffen werden und in Visual Studio Code bearbeitet werden. Die direkte und umfassende Bearbeitung von HTML-Dateien wird derzeit nicht unterstützt.

Kann ich eine Komponente extern mithilfe dieses Features erstellen und auf eine Power Pages-Website übertragen?

Nein, Sie können eine extern generierte Komponente nicht mithilfe dieses Features auf eine vorhandene Power Pages Website übertragen.

Kann ich Standardkomponenten wie Listen und Formulare hinzufügen?

Das Hinzufügen von Standardkomponenten wie Listen und Formularen wird derzeit nicht unterstützt. Sie können jedoch benutzerdefinierte Formulare und Listen mit dem React-Framework und Web-APIs erstellen.

Wie funktioniert die Quellcodeverwaltung?

Entwickler können die Power Platform Git-Integration für die Quellcodeverwaltung verwenden. Allerdings werden nur die kompilierten Webdateien dem Repository hinzugefügt, nicht der vollständige Quellcode.

Unterstützen diese Websites SEO?

Da SPA-Websites mit dem React-Framework erstellt werden und clientseitiges Rendering verwenden, ist die SEO-Unterstützung begrenzt.

Welche Sicherheits- und Governance-Unterstützung bieten Power Pages für SPA-Websites?

Power Pages erzwingt Tabellenberechtigungen und Sicherheitswebrollen für Web-API-Aufrufe, um sicherzustellen, dass der Datenzugriff mit Benutzerrollen übereinstimmt. Verwenden Sie das Objekt, um grundlegende Benutzereigenschaften abzurufen und Erfahrungen basierend auf Benutzer-Personas anzupassen.

Darüber hinaus unterstützen SPA-Sites Folgendes:

  • Private und öffentliche Website-Konfigurationen
  • Governance-Einstellungen, einschließlich Kontrolle über den anonymen Datenzugriff
  • Authentifizierung und Anbieterkonfigurationen

Diese Features tragen dazu bei, die sichere und kompatible Integration von benutzerdefinierten Komponenten in Power Pages sicherzustellen.

  • Last updated on