Creare e distribuire un'applicazione a pagina singola in Power Pages

Power Pages supporta l'integrazione del codice applicazione a pagina singola creato con strumenti di intelligenza artificiale di nuova generazione, ad esempio GitHub Copilot. Questa funzionalità consente agli sviluppatori di offrire esperienze front-end moderne basate su componenti in Power Pages usando il linguaggio naturale come interfaccia di codifica.

Guidando, testando e perfezionando il codice generato dall'intelligenza artificiale, gli autori possono spostare la loro attenzione dalle attività di implementazione ripetitive all'orchestrazione di livello superiore. Ciò consente uno sviluppo più intuitivo e creativo, mantenendo al contempo qualità e standard di livello aziendale.

Questo articolo illustra come:

Creare e configurare un progetto SPA per Power Pages usando la Power Platform CLI (PAC CLI).
Carica e scarica risorse di codice da e verso il tuo sito Power Pages.
Configura una struttura di progetto sicura e gestibile.
Informazioni sulle differenze principali tra implementazioni di Power Pages basate su SPA e tradizionali.

Nota

Un sito SPA è un sito Power Pages che viene eseguito interamente nel browser dell'utente (rendering lato client). A differenza dei siti di Power Pages tradizionali, i siti spa vengono gestiti solo tramite il codice sorgente e gli strumenti dell'interfaccia della riga di comando.
integrazione Power Platform Git non è supportata per i siti Web per applicazioni a pagina singola (SAP) in Power Pages.

Prerequisiti

Prima di iniziare, verifica di disporre di:

Un ambiente Power Pages con privilegi admin.
Power Platform CLI (PAC CLI) versione 1.44.x o successiva installata e autenticata.
Sito Power Pages nella versione 9.7.4.x o successiva.
Consenti caricamenti di file JavaScript negli ambienti Dataverse.
Un repository Git locale con il progetto front-end personalizzato, ad esempio React, Angular o Vue.

Consenti caricamenti di file JavaScript

Per impostazione predefinita, alcuni ambienti Dataverse bloccano il caricamento di file JavaScript (). Se viene visualizzato l'errore "Importazione non riuscita: l'allegato non è un tipo valido o è troppo grande. Non può essere caricato o scaricato.", aggiornare le impostazioni dell'ambiente per consentire questo tipo di file.

Per regolare le impostazioni nell'interfaccia di amministrazione di Power Platform per un ambiente, segui questi passaggi:

Accedi all'interfaccia di amministrazione di Power Platform.
Nel riquadro di spostamento seleziona Gestisci.
Nel riquadro Gestisci, seleziona Ambienti.
Seleziona un ambiente.
Seleziona Impostazioni nella barra dei comandi.
Espandi Prodotto, quindi seleziona Privacy + Sicurezza.
Nella sezione Allegati bloccati rimuovere dall'elenco delle estensioni di file.
Seleziona Salva.

Creare e distribuire un sito SPA

I siti Power Pages SPA vengono gestiti utilizzando i comandi CLI PAC upload-code-site e download-code-site. Dopo aver caricato un sito, viene visualizzato nell'elenco Power Pages nell'elenco Inactive sites. Attiva il sito per renderlo disponibile agli utenti.

Caricare un sito SPA

Usare il comando pac pages upload-code-site per caricare l'origine locale e gli asset compilati nell'ambiente Power Pages.

Sintassi

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

Parametri

Parametro	Alias	Richiesto	Descrizione
`--rootPath`	`-rp`	Sì	Cartella locale che contiene i file di origine del sito
`--compiledPath`	`-cp`	No	Percorso delle risorse compilate, ad esempio React
`--siteName`	`-sn`	No	Nome visualizzato per il sito Power Pages

Esempio

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

Se non si ha un progetto esistente, provare le implementazioni di esempio dei siti SPA usando React, Angular e Vue.

Definizione dei parametri di caricamento con

Personalizza il comportamento del comando includendo un file nel tuo sito. Inserisci il file di configurazione nella cartella principale del sito. Quando usi i caricamenti del sito basati sulla configurazione, esegui il comando solo con il parametro . Il comando legge automaticamente altri valori, come il percorso delle risorse compilate e il nome visualizzato del sito, dal file . Se fornisci sia gli argomenti della riga di comando che i valori config, gli argomenti della riga di comando hanno la precedenza.

Esempio :

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

Scaricare un sito SPA

Utilizza il comando pac pages download-code-site per scaricare un codice di un sito esistente in una directory locale a scopo di modifica o backup.

Sintassi

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

Parametri

Parametro	Alias	Richiesto	Descrizione
`--environment`	`-env`	No	Ambiente Dataverse (GUID o URL completo). L'impostazione predefinita è il profilo di autenticazione attivo
`--path`	`-p`	Sì	Directory locale per scaricare il codice del sito
`--webSiteId`	`-id`	Sì	GUID del record del sito Web del sito SPA di Power Pages
`--overwrite`	`-o`	No	Sovrascrivere i file esistenti nella directory di destinazione, se esistono

Esempio

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

Attivare e testare il tuo sito

Passare a Power Pages.
Seleziona Siti inattivi, trova il tuo sito e seleziona Riattiva.
Quando il sito è attivo, vai all'URL del sito per controllare la distribuzione.

Mancia

Qualsiasi comando successivo aggiorna automaticamente il sito attivo.

Struttura e configurazione del progetto

Un layout del progetto coerente aiuta a garantire il corretto comportamento di caricamento.

/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

Utilizzare il file facoltativo per personalizzare il funzionamento del comando .

Autenticazione e autorizzazione

I siti SPA di Power Pages utilizzano lo stesso modello di sicurezza, dei siti tradizionali di Power Pages.

Configurazione dei provider di identità

Passare a Power Pages.
Trova il sito e seleziona Modifica.
Selezionare SicurezzaProvider di identità.
Aggiungi o configura i provider di identità, ad esempio Microsoft Entra ID.
Ogni nuovo sito ha automaticamente un provider di Microsoft Entra ID predefinito.

Accedere al contesto utente nel codice

Ottenere i metadati di autenticazione nel client:

URL autorità:

L'autorità o l'URL di accesso per Microsoft Entra ID è:
```
https://login.windows.net/<tenantId>
```
Trovare l'URL di Authority per gli altri provider di identità configurati accedendo alle impostazioni di configurazione di Power Pages><your site>>Security>Identity providers>.

Dettagli utente:

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

Esempio di flusso 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>
    );
};

Usare le API Web di Power Pages

Gli sviluppatori possono sfruttare Power Pages API Web per caricare il contenuto nell'interfaccia utente o per creare, aggiornare ed eliminare record. Prima di usare queste API, assicurati che le API Web necessarie siano abilitate e che le autorizzazioni di tabella e i ruoli Web appropriati siano configurati correttamente.


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

Configurare lo sviluppo locale abilitando le chiamate API Web da localhost usando l'autenticazione Microsoft Entra ID

Gli sviluppatori necessitano di cicli di iterazione più veloci, debug locale e funzionalità di ricaricamento rapido durante la compilazione di applicazioni. SPA supporta questi flussi di lavoro abilitando chiamate API Web sicure da localhost usando l'autenticazione Microsoft Entra ID (Azure AD) v1.

Questa configurazione consente di:

Eseguire l'app in locale con supporto completo per l'autenticazione.
Utilizzare strumenti di sviluppo moderni come Vite per la ricarica live e feedback immediato.
Evitare problemi di CORS quando si chiamano le API Web di Power Pages.
Accelerare lo sviluppo senza distribuire le modifiche nel portale.

Questa configurazione consente un'esperienza di sviluppo locale produttiva per SPA, consentendo agli sviluppatori di compilare, testare ed eseguire rapidamente l'iterazione con il supporto completo per l'accesso e l'autenticazione delle API.

Importante

Usare solo Microsoft Entra endpoint v1 per l'autenticazione.
L'autenticazione tramite bearer è supportata solo nelle versioni del portale 9.7.6.6 o successive.
Applicare queste impostazioni solo negli ambienti di sviluppo.

Passaggi di configurazione

Abilitazione dell'autenticazione SPA
1. In https://portal.azure.com, apri l'app Microsoft Entra registrata per il tuo portale.
2. Abilitare l'autenticazione a pagina singola dell'applicazione (SPA).
3. Aggiungere come URI di reindirizzamento usando la configurazione della piattaforma dell'applicazione a pagina singola . Per altri dettagli, vedere Come aggiungere un URI di reindirizzamento nell'applicazione .
  - URI di reindirizzamento: .

Aggiungere le impostazioni del sito

Aggiungi queste impostazioni del sito in Power Pages:

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

Usare ADAL.js per l'accesso
- Implementare l'accesso lato client utilizzando ADAL.js.
Nota

MSAL.js non è compatibile perché Power Pages usa endpoint Microsoft Entra v1, mentre MSAL usa la versione 2. Il formato dell'autorità emittente differisce tra le versioni.
Aggiungere l'intestazione dell'autorizzazione
- Includere questa intestazione in tutte le richieste API Web:
```
Authorization: Bearer <id_token>
```
Impostare la visibilità del sito su Pubblico
- Questa impostazione consente di accedere al sito per scopi di sviluppo e test.

Configurare il proxy di sviluppo

Se si usa Vite, aggiungi questo a per evitare problemi CORS.

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

Differenze rispetto ai siti di Power Pages esistenti

La tabella seguente riepiloga le principali differenze tra i siti SPA creati con questa funzionalità e i siti di Power Pages tradizionali:

Funzionalità	Comportamento del sito SPA
Aggiornamento lato server	Restituisce sempre la pagina principale del sito e il router lato client esegue il rendering delle route secondarie.
Conflitti di instradamento	Gli instradamenti lato client hanno la precedenza e un aggiornamento forzato torna alla radice.
Area di lavoro Pagina	L'area di lavoro Pagine non è supportata. Usare il routing client e le pagine del sito client. Per la sicurezza a livello di pagina, controlla i ruoli Web assegnati con l'oggetto utente globale ed esegui il rendering condizionale dell'interfaccia utente.
Area di lavoro Stile	L'applicazione dello stile in corso con l'area di lavoro Stile non è supportata. Usa lo stile del tuo framework, ad esempio CSS, CSS-in-JS o le classi di utilità.
Localizzazione	Supporto singola lingua. Implementare il caricamento delle risorse lato client.
Creazione di modelli Liquid	Il codice Liquid e i modelli Liquid non sono supportati. Accedere ai dati usando il motore di modelli e le API Web del framework.

Domande frequenti

Quale supporto è disponibile per i test unitari e di integrazione?

Al momento non è disponibile alcun supporto predefinito per i test unitari e i test di integrazione. Gli autori devono scrivere ed eseguire questi test localmente o all'interno delle pipeline CI/CD.

È disponibile il supporto per l'integrazione Power Fx tramite WebAssembly?

Questa capacità non è attualmente supportata.

Il codice sorgente è disponibile in Power Pages?

Attualmente, i creatori possono creare siti Web usando TypeScript o GitHub Copilot Agent. I file JavaScript e CSS compilati sono accessibili e possono essere modificati in Visual Studio Code. Tuttavia, la modifica diretta ed estesa dei file HTML non è attualmente supportata.

È possibile creare un componente esternamente usando questa funzionalità e portarlo in un sito Power Pages?

No, non è possibile portare un componente generato esternamente in un sito di Power Pages esistente usando questa funzionalità.

Puoi aggiungere componenti predefiniti come elenchi e moduli?

L'aggiunta di componenti predefiniti come elenchi e moduli non è attualmente supportata. Tuttavia, è possibile creare moduli ed elenchi personalizzati utilizzando il framework React e le API Web.

Come funziona il controllo del codice sorgente?

Gli sviluppatori possono usare l'integrazione Power Platform Git per il controllo del codice sorgente. Tuttavia, solo i file Web compilati vengono aggiunti al repository, non il codice sorgente completo.

Questi siti supportano SEO?

Poiché i siti SPA sono costruiti con il framework React e utilizzano il rendering lato client, il supporto SEO è limitato.

Quali supporti per la sicurezza e la governance offrono i siti Power Pages SPA?

Power Pages applica le autorizzazioni di tabella e i ruoli Web di sicurezza nelle chiamate API Web, assicurandosi che l'accesso ai dati sia allineato ai ruoli utente. Utilizzare l'oggetto per recuperare le proprietà utente di base e personalizzare le esperienze in base agli utenti tipo.

Inoltre, i siti SPA supportano:

Configurazioni dei siti pubblici e privati
Impostazioni di governance, incluso il controllo sull'accesso anonimo ai dati
Configurazioni dei provider di autenticazione

Queste funzionalità consentono di garantire l'integrazione sicura e conforme dei componenti personalizzati all'interno di Power Pages.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-07

Creare e distribuire un'applicazione a pagina singola in Power Pages

Prerequisiti

Consenti caricamenti di file JavaScript

Creare e distribuire un sito SPA

Caricare un sito SPA

Sintassi

Parametri

Esempio

Definizione dei parametri di caricamento con

Scaricare un sito SPA

Sintassi

Parametri

Esempio

Attivare e testare il tuo sito

Struttura e configurazione del progetto

Autenticazione e autorizzazione

Configurazione dei provider di identità

Accedere al contesto utente nel codice

Esempio di flusso React

Usare le API Web di Power Pages

Configurare lo sviluppo locale abilitando le chiamate API Web da localhost usando l'autenticazione Microsoft Entra ID

Passaggi di configurazione

Differenze rispetto ai siti di Power Pages esistenti

Domande frequenti

Quale supporto è disponibile per i test unitari e di integrazione?

È disponibile il supporto per l'integrazione Power Fx tramite WebAssembly?

Il codice sorgente è disponibile in Power Pages?

È possibile creare un componente esternamente usando questa funzionalità e portarlo in un sito Power Pages?

Puoi aggiungere componenti predefiniti come elenchi e moduli?

Come funziona il controllo del codice sorgente?

Questi siti supportano SEO?

Quali supporti per la sicurezza e la governance offrono i siti Power Pages SPA?

Informazioni correlate

Commenti e suggerimenti

Risorse aggiuntive