Frontend personalizzati

Frontend personalizzati

I frontend personalizzati sono applicazioni web statiche che crea con strumenti web standard e ospita con PowerShell Universal. Sono utili quando desidera utilizzare un framework JavaScript, riutilizzare un sistema di progettazione esistente o avere il pieno controllo dell'esperienza lato client.

PowerShell Universal non ha bisogno di compilare o comprendere il codice sorgente del suo frontend. Crei l'applicazione con gli strumenti che preferisce, pubblichi i file generati con una cartella pubblicata e chiami le API di PowerShell Universal dal browser.

Questo differisce dalle app statiche, che vengono create a partire dalle definizioni delle App di PowerShell Universal. I frontend personalizzati utilizzano direttamente HTML, CSS e JavaScript standard.

Utilizzo delle librerie JavaScript

Può utilizzare React, Vue, Angular, Svelte o qualsiasi altra libreria frontend che produca file statici. PowerShell Universal serve l'output compilato, come una cartella dist, build o wwwroot.

Un flusso di lavoro tipico è:

1. Creare il progetto frontend con gli strumenti del framework.
2. Configurare la build per utilizzare il percorso di richiesta che pubblicherà in PowerShell Universal.
3. Compilare il frontend.
4. Pubblicare l'output della build come cartella pubblicata.

Quando ospita l'applicazione sotto un percorso come /dashboard, configuri il percorso di base del suo bundler in modo che gli URL di JavaScript, CSS, immagini e font vengano risolti correttamente. Eviti /portal perché è in conflitto con il Portal integrato di PowerShell Universal.

Per le applicazioni basate su Vite, imposti l'opzione base.

import { defineConfig } from 'vite'

export default defineConfig({
	base: '/dashboard/'
})

Per le applicazioni Angular, imposti il base href durante la compilazione.

ng build --base-href /dashboard/

Se l'applicazione utilizza il routing lato client, configuri il router per utilizzare il percorso di richiesta pubblicato. Può anche utilizzare il routing basato su hash quando non desidera che il server gestisca direttamente i deep link.

Durante lo sviluppo, può eseguire il server di sviluppo locale del framework e chiamare le API di PowerShell Universal dal browser. Se il server di sviluppo viene eseguito su un'origine diversa da quella di PowerShell Universal, configuri CorsHosts o utilizzi la funzionalità proxy del server di sviluppo del frontend. In produzione, preferisca URL relativi in modo che le chiamate tornino alla stessa istanza di PowerShell Universal che ha servito il frontend.

Utilizzo dei framework CSS

Può utilizzare framework CSS come Tailwind CSS, Bootstrap, Bulma o librerie di componenti specifiche del framework. Includa il CSS nello stesso modo in cui lo farebbe in qualsiasi applicazione web statica.

Per la maggior parte delle applicazioni, installi il framework CSS tramite il suo gestore di pacchetti e lo includa nel bundle. In questo modo l'applicazione rimane autonoma ed evita di dipendere da CDN esterni.

npm install bootstrap

import 'bootstrap/dist/css/bootstrap.min.css'

Il frontend personalizzato è indipendente dalla Admin Console e dall'App Framework di PowerShell Universal. Includa nell'output della build tutti gli stili, i font e le risorse richiesti dalla sua applicazione, oppure li serva da un'altra cartella pubblicata.

Chiamata delle API di PSU

I frontend personalizzati possono chiamare sia endpoint API personalizzati sia la Management API di PowerShell Universal.

Utilizzi endpoint API personalizzati per dati e azioni specifici dell'applicazione. Questo è l'approccio consigliato per la maggior parte dei frontend personalizzati perché controlla la route, la convalida degli input, la forma della risposta, l'autenticazione e i requisiti di ruolo.

New-PSUEndpoint -Url '/frontend/profile' -Method Get -Authentication -Endpoint {
		[PSCustomObject]@{
				UserName = $User.Identity.Name
				ServerTime = Get-Date
		}
}

Dal frontend, chiami l'endpoint con fetch.

const response = await fetch('/frontend/profile', {
	credentials: 'same-origin'
})

if (!response.ok) {
	throw new Error(`Request failed: ${response.status}`)
}

const profile = await response.json()

Per le richieste JSON, invii l'header Content-Type e analizzi il body nell'endpoint oppure utilizzi un blocco param.

New-PSUEndpoint -Url '/frontend/tickets' -Method Post -Authentication -Endpoint {
		$Ticket = ConvertFrom-Json $Body

		[PSCustomObject]@{
				Id = [guid]::NewGuid()
				Title = $Ticket.Title
				Created = Get-Date
		}
}

await fetch('/frontend/tickets', {
	method: 'POST',
	credentials: 'same-origin',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({ title: 'Reset development environment' })
})

La Management API è disponibile sotto /api/v1 ed è destinata alle operazioni amministrative. La utilizzi quando sta creando un frontend amministrativo e l'utente connesso dispone delle autorizzazioni richieste. Per i flussi di lavoro rivolti agli utenti, valuti di esporre un endpoint API personalizzato più ristretto che esegua solo l'operazione necessaria al frontend.

Eviti di creare URL di endpoint personalizzati in conflitto con gli URL interni della Management API. Consulti Endpoint API e Sicurezza delle API per maggiori dettagli.

Documentazione delle API con OpenAPI

La documentazione OpenAPI è utile durante la creazione di frontend personalizzati perché descrive il contratto dell'API in un formato standard. Gli sviluppatori e gli agenti IA possono utilizzarla per comprendere route, metodi HTTP, parametri, requisiti di autenticazione, corpi delle richieste, forme delle risposte e codici di stato prima di scrivere il codice del frontend.

Crei una definizione di documentazione degli endpoint per l'API utilizzata dal suo frontend e le assegni gli endpoint correlati.

New-PSUEndpointDocumentation -Name 'Dashboard API' -Url '/dashboard-api' -Description 'APIs used by the custom dashboard.'

New-PSUEndpoint -Url '/frontend/tickets' -Method Get -Authentication -Documentation 'Dashboard API' -Endpoint {
    <#
    .SYNOPSIS
    Returns tickets displayed by the custom dashboard.

    .DESCRIPTION
    Returns the ticket list for the signed-in user. Operators receive assigned tickets and administrators receive all tickets.

    .OUTPUTS
    200:
      Description: Ticket list returned successfully.
    401:
      Description: The user is not authenticated.
    #>
    Get-Ticket | Select-Object Id, Title, Status, AssignedTo
}

Le definizioni OpenAPI compaiono nella dashboard Swagger integrata.

http://localhost:5000/swagger/index.html

Utilizzi la guida basata su commenti negli script degli endpoint per documentare lo scopo dell'endpoint e i suoi parametri. Per contratti API più ricchi, definisca i tipi di input e output nella definizione di documentazione degli endpoint e li referenzi dalle sezioni .INPUTS e .OUTPUTS. Questo aiuta i client generati, gli strumenti di test e gli agenti IA a produrre richieste più accurate.

Quando lavora con un agente IA, fornisca il documento OpenAPI o l'URL di Swagger insieme ai requisiti del frontend. L'agente può utilizzare il contratto per generare client API tipizzati, helper per le richieste, form, convalida, stati di caricamento e gestione degli errori che corrispondono agli endpoint reali.

Autenticazione

Le cartelle pubblicate e gli endpoint API possono richiedere autenticazione e ruoli in modo indipendente.

Per richiedere agli utenti di accedere prima di caricare i file del frontend, abiliti l'autenticazione sulla cartella pubblicata.

New-PSUPublishedFolder -Name 'Dashboard' -Path 'C:\Apps\Dashboard\dist' -RequestPath '/dashboard' -DefaultDocument 'index.html' -Authentication -Role 'Operator'

Per proteggere dati e azioni, abiliti l'autenticazione sugli endpoint API chiamati dal frontend.

New-PSUEndpoint -Url '/frontend/admin-data' -Method Get -Authentication -Role 'Administrator' -Endpoint {
		Get-Date
}

Quando il frontend viene servito dalla stessa istanza di PowerShell Universal, l'autenticazione tramite cookie funziona naturalmente per gli utenti connessi. Utilizzi credentials: 'same-origin' con fetch in modo che le credenziali del browser vengano incluse nelle richieste agli endpoint autenticati.

I token dell'app sono utili per l'automazione, le integrazioni esterne e le chiamate server-to-server. Non incorpori i token dell'app nel JavaScript del browser, non li memorizzi nel local storage e non li includa nei commit con il codice sorgente del frontend. Se un frontend deve eseguire un'operazione che richiede autorizzazioni elevate, crei un endpoint API personalizzato con l'autenticazione, i controlli dei ruoli e la logica lato server appropriati.

Quando ha effettivamente bisogno di chiamare le API con un token dell'app da un client attendibile, lo invii nell'header Authorization.

Authorization: Bearer <app-token>

PowerShell Universal supporta anche l'header X-PSU-Authorization per gli scenari in cui un reverse proxy deve utilizzare l'header Authorization standard per un altro scopo. Consulti Token dell'app per indicazioni sulla gestione dei token.

Hosting delle risorse statiche

Utilizzi le cartelle pubblicate per ospitare i file compilati del frontend. La cartella pubblicata associa un percorso del file system locale a un percorso di richiesta sul server web di PowerShell Universal.

New-PSUPublishedFolder -Name 'Dashboard' -Path 'C:\Apps\Dashboard\dist' -RequestPath '/dashboard' -DefaultDocument 'index.html'

Dopo la pubblicazione, gli utenti possono aprire il frontend al percorso di richiesta.

http://localhost:5000/dashboard

Il parametro -DefaultDocument serve index.html quando l'utente richiede la radice della cartella. Questo è importante per le applicazioni a pagina singola. Per i collegamenti diretti a route lato client annidate, utilizzi il routing basato su hash o si assicuri che il suo percorso di hosting possa restituire il punto di ingresso del frontend per tali route.

Pubblichi solo la cartella di output compilata. Non pubblichi cartelle sorgente che contengono file di configurazione, metadati dei pacchetti, file di ambiente o altri contenuti che non dovrebbero essere scaricabili.

Le risorse statiche come immagini, font e chunk JavaScript generati possono risiedere all'interno della stessa cartella di output della build. Se deve condividere risorse tra più frontend o app, pubblichi una cartella separata come /assets e la referenzi dal frontend.

Creazione con agenti IA

Gli agenti IA di codifica possono aiutare a impostare e iterare un frontend personalizzato, soprattutto se fornisce in anticipo i vincoli di PowerShell Universal. Fornisca all'agente il percorso di richiesta, il framework, le route API, le aspettative di autenticazione e il comando di build che intende utilizzare.

Le skill di PowerShell Universal possono fornire agli agenti IA istruzioni, script e riferimenti riutilizzabili specifici per PSU. Devolutions gestisce una raccolta di queste skill nel repository powershell-universal-skills. Queste skill seguono il formato Agent Skills e possono aiutare gli agenti a eseguire attività comuni di PowerShell Universal con un contesto più specifico del prodotto.

Ad esempio, il repository include una skill install-sandbox-psu per installare PowerShell Universal in un ambiente sandbox per test e sviluppo. Può installare la raccolta con la CLI delle skill.

npx skills add devolutions/powershell-universal-skills

Una volta installate, gli agenti di codifica supportati possono utilizzare automaticamente le skill quando viene rilevata un'attività pertinente di PowerShell Universal. Questo può essere utile quando desidera che un agente crei un frontend personalizzato e configuri anche un'istanza PSU locale, imposti le risorse di supporto o convalidi il frontend rispetto a un ambiente sandbox.

Ad esempio:

Build a React and Vite frontend for PowerShell Universal. It will be hosted at /dashboard from a published folder. Configure the Vite base path for /dashboard/. Use relative fetch calls to /frontend/profile and /frontend/tickets with same-origin credentials. Do not store app tokens in the browser. Include loading, error, and empty states.

I dettagli utili da includere nei prompt sono:

• Il framework e il gestore di pacchetti da utilizzare.
• Il percorso di richiesta della cartella pubblicata.
• Gli URL previsti degli endpoint API e le forme JSON.
• Il documento OpenAPI o l'URL di Swagger per le API del frontend.
• Se il frontend è pubblico o richiede autenticazione.
• Il comportamento specifico dei ruoli che l'interfaccia utente deve mostrare o nascondere.
• La cartella di output della build che verrà pubblicata.
• Eventuali skill dell'agente di PowerShell Universal installate che l'agente dovrebbe utilizzare.

Dopo che l'agente ha creato il frontend, riveda la configurazione della build, esegua la build di produzione e pubblichi solo la cartella di output generata con New-PSUPublishedFolder o la pagina Platform / Published Folders.