> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/it/app/custom-frontends.md).

# 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](/powershell-universal/it/piattaforma/published-folders.md) e chiami le API di PowerShell Universal dal browser.

Questo differisce dalle [app statiche](/powershell-universal/it/app/static-apps.md), 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`.

```typescript
import { defineConfig } from 'vite'

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

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

```powershell
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](/powershell-universal/it/config/settings.md#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.

```powershell
npm install bootstrap
```

```javascript
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](/powershell-universal/it/api/endpoints.md) 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.

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

Dal frontend, chiami l'endpoint con `fetch`.

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

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

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

```javascript
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](/powershell-universal/it/api/endpoints.md) e [Sicurezza delle API](/powershell-universal/it/api/security.md) per maggiori dettagli.

## Documentazione delle API con OpenAPI

La documentazione [OpenAPI](/powershell-universal/it/api/openapi.md) è 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.

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

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

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

```http
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](/powershell-universal/it/sicurezza/app-tokens.md) per indicazioni sulla gestione dei token.

## Hosting delle risorse statiche

Utilizzi le [cartelle pubblicate](/powershell-universal/it/piattaforma/published-folders.md) 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.

```powershell
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
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](https://github.com/Devolutions/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.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/it/app/custom-frontends.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.