Benutzerdefinierte Frontends

Benutzerdefinierte Frontends

Benutzerdefinierte Frontends sind statische Webanwendungen, die Sie mit standardmäßigen Web-Werkzeugen erstellen und mit PowerShell Universal hosten. Sie sind nützlich, wenn Sie ein JavaScript-Framework verwenden, ein bestehendes Designsystem wiederverwenden oder die vollständige Kontrolle über die clientseitige Erfahrung haben möchten.

PowerShell Universal muss den Quellcode Ihres Frontends nicht kompilieren oder verstehen. Erstellen Sie die Anwendung mit den Werkzeugen Ihrer Wahl, veröffentlichen Sie die generierten Dateien mit einem veröffentlichten Ordner und rufen Sie PowerShell Universal-APIs aus dem Browser auf.

Dies unterscheidet sich von statischen Apps, die aus PowerShell Universal App-Definitionen erstellt werden. Benutzerdefinierte Frontends verwenden direkt standardmäßiges HTML, CSS und JavaScript.

Verwendung von JavaScript-Bibliotheken

Sie können React, Vue, Angular, Svelte oder jede andere Frontend-Bibliothek verwenden, die statische Dateien erzeugt. PowerShell Universal stellt die kompilierte Ausgabe bereit, etwa einen dist-, build- oder wwwroot-Ordner.

Ein typischer Arbeitsablauf ist:

1. Erstellen Sie das Frontend-Projekt mit den Werkzeugen des Frameworks.
2. Konfigurieren Sie den Build so, dass er den Anforderungspfad verwendet, den Sie in PowerShell Universal veröffentlichen werden.
3. Erstellen Sie das Frontend.
4. Veröffentlichen Sie die Build-Ausgabe als veröffentlichten Ordner.

Wenn Sie die Anwendung unter einem Pfad wie /dashboard hosten, konfigurieren Sie den Basispfad Ihres Bundlers, damit JavaScript-, CSS-, Bild- und Font-URLs korrekt aufgelöst werden. Vermeiden Sie /portal, da dies mit dem integrierten PowerShell Universal Portal in Konflikt steht.

Setzen Sie für Vite-basierte Anwendungen die Option base.

import { defineConfig } from 'vite'

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

Setzen Sie für Angular-Anwendungen die Base-Href beim Erstellen.

ng build --base-href /dashboard/

Wenn die Anwendung clientseitiges Routing verwendet, konfigurieren Sie den Router so, dass er den veröffentlichten Anforderungspfad verwendet. Sie können auch Hash-basiertes Routing verwenden, wenn der Server Deep Links nicht direkt verarbeiten soll.

Während der Entwicklung können Sie den lokalen Entwicklungsserver des Frameworks ausführen und PowerShell Universal-APIs aus dem Browser aufrufen. Wenn der Entwicklungsserver unter einem anderen Origin als PowerShell Universal läuft, konfigurieren Sie CorsHosts oder verwenden Sie die Proxy-Funktion des Frontend-Entwicklungsservers. In der Produktion sind relative URLs zu bevorzugen, damit Aufrufe an dieselbe PowerShell Universal-Instanz zurückgehen, die das Frontend bereitgestellt hat.

Verwendung von CSS-Frameworks

Sie können CSS-Frameworks wie Tailwind CSS, Bootstrap, Bulma oder Framework-spezifische Komponentenbibliotheken verwenden. Binden Sie das CSS auf dieselbe Weise ein wie in jeder anderen statischen Webanwendung.

Für die meisten Anwendungen installieren Sie das CSS-Framework über Ihren Paketmanager und binden es in das Bundle ein. So bleibt die Anwendung eigenständig und ist nicht von externen CDNs abhängig.

npm install bootstrap

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

Das benutzerdefinierte Frontend ist unabhängig von der Admin-Konsole und dem PowerShell Universal App Framework. Nehmen Sie alle Stile, Fonts und Assets, die Ihre Anwendung benötigt, in die Build-Ausgabe auf oder stellen Sie sie über einen anderen veröffentlichten Ordner bereit.

PSU-APIs aufrufen

Benutzerdefinierte Frontends können sowohl benutzerdefinierte API-Endpunkte als auch die PowerShell Universal Management-API aufrufen.

Verwenden Sie benutzerdefinierte API-Endpunkte für anwendungsspezifische Daten und Aktionen. Dies ist der empfohlene Ansatz für die meisten benutzerdefinierten Frontends, da Sie die Route, die Eingabevalidierung, die Antwortform, die Authentifizierung und die Rollenanforderungen kontrollieren.

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

Rufen Sie den Endpunkt vom Frontend mit fetch auf.

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

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

const profile = await response.json()

Senden Sie für JSON-Anfragen den Header Content-Type und parsen Sie den Body im Endpunkt oder verwenden Sie einen param-Block.

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

Die Management-API ist unter /api/v1 verfügbar und ist für administrative Vorgänge vorgesehen. Verwenden Sie sie, wenn Sie ein administratives Frontend erstellen und der angemeldete Benutzer die erforderlichen Berechtigungen besitzt. Für benutzerorientierte Workflows sollten Sie in Erwägung ziehen, einen kleineren benutzerdefinierten API-Endpunkt bereitzustellen, der nur den vom Frontend benötigten Vorgang ausführt.

Vermeiden Sie das Erstellen benutzerdefinierter Endpunkt-URLs, die mit internen Management-API-URLs in Konflikt stehen. Weitere Einzelheiten finden Sie unter API-Endpunkte und API-Sicherheit.

APIs mit OpenAPI dokumentieren

OpenAPI-Dokumentation ist beim Erstellen benutzerdefinierter Frontends hilfreich, da sie den API-Vertrag in einem standardisierten Format beschreibt. Entwickler und KI-Agenten können damit Routen, HTTP-Methoden, Parameter, Authentifizierungsanforderungen, Anfrage-Bodys, Antwortformen und Statuscodes verstehen, bevor sie Frontend-Code schreiben.

Erstellen Sie eine Endpunkt-Dokumentationsdefinition für die von Ihrem Frontend verwendete API und weisen Sie ihr zugehörige Endpunkte zu.

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
}

OpenAPI-Definitionen erscheinen im integrierten Swagger-Dashboard.

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

Verwenden Sie kommentarbasierte Hilfe in Endpunktskripten, um den Zweck des Endpunkts und seine Parameter zu dokumentieren. Für umfangreichere API-Verträge definieren Sie Eingabe- und Ausgabetypen in der Endpunkt-Dokumentationsdefinition und referenzieren Sie diese aus den Abschnitten .INPUTS und .OUTPUTS. Dies hilft generierten Clients, Testwerkzeugen und KI-Agenten, genauere Anfragen zu erzeugen.

Wenn Sie mit einem KI-Agenten arbeiten, stellen Sie das OpenAPI-Dokument oder die Swagger-URL zusammen mit den Frontend-Anforderungen bereit. Der Agent kann den Vertrag nutzen, um typisierte API-Clients, Anfrage-Helper, Formulare, Validierung, Ladezustände und Fehlerbehandlung zu generieren, die zu den tatsächlichen Endpunkten passen.

Authentifizierung

Veröffentlichte Ordner und API-Endpunkte können unabhängig voneinander Authentifizierung und Rollen erfordern.

Um Benutzer vor dem Laden der Frontend-Dateien zur Anmeldung zu verpflichten, aktivieren Sie die Authentifizierung für den veröffentlichten Ordner.

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

Um Daten und Aktionen zu schützen, aktivieren Sie die Authentifizierung für die API-Endpunkte, die das Frontend aufruft.

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

Wenn das Frontend von derselben PowerShell Universal-Instanz bereitgestellt wird, funktioniert die Cookie-Authentifizierung für angemeldete Benutzer auf natürliche Weise. Verwenden Sie credentials: 'same-origin' mit fetch, damit Browser-Anmeldeinformationen bei Anfragen an authentifizierte Endpunkte einbezogen werden.

App-Tokens sind nützlich für Automatisierung, externe Integrationen und Server-zu-Server-Aufrufe. Betten Sie App-Tokens nicht in Browser-JavaScript ein, speichern Sie sie nicht im Local Storage und committen Sie sie nicht mit Frontend-Quellcode. Wenn ein Frontend einen Vorgang ausführen muss, der erhöhte Berechtigungen erfordert, erstellen Sie einen benutzerdefinierten API-Endpunkt mit der entsprechenden Authentifizierung, Rollenprüfungen und serverseitiger Logik.

Wenn Sie APIs doch mit einem App-Token von einem vertrauenswürdigen Client aufrufen müssen, senden Sie es im Authorization-Header.

Authorization: Bearer <app-token>

PowerShell Universal unterstützt außerdem den Header X-PSU-Authorization für Szenarien, in denen ein Reverse-Proxy den standardmäßigen Authorization-Header für einen anderen Zweck benötigt. Hinweise zur Token-Verwaltung finden Sie unter App-Tokens.

Statische Assets hosten

Verwenden Sie veröffentlichte Ordner, um die kompilierten Frontend-Dateien zu hosten. Der veröffentlichte Ordner ordnet einen lokalen Dateisystempfad einem Anforderungspfad auf dem PowerShell Universal-Webserver zu.

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

Nach der Veröffentlichung können Benutzer das Frontend unter dem Anforderungspfad öffnen.

http://localhost:5000/dashboard

Der Parameter -DefaultDocument stellt index.html bereit, wenn der Benutzer den Stammordner anfordert. Dies ist für Single-Page-Anwendungen wichtig. Verwenden Sie für direkte Links zu verschachtelten clientseitigen Routen Hash-basiertes Routing oder stellen Sie sicher, dass Ihr Hosting-Pfad für diese Routen den Frontend-Einstiegspunkt zurückgeben kann.

Veröffentlichen Sie nur den Ordner mit der kompilierten Ausgabe. Veröffentlichen Sie keine Quellordner, die Konfigurationsdateien, Paket-Metadaten, Umgebungsdateien oder andere Inhalte enthalten, die nicht herunterladbar sein sollten.

Statische Assets wie Bilder, Fonts und generierte JavaScript-Chunks können sich im selben Build-Ausgabeordner befinden. Wenn Sie Assets über mehrere Frontends oder Apps hinweg teilen müssen, veröffentlichen Sie einen separaten Ordner wie /assets und referenzieren Sie ihn aus dem Frontend.

Erstellen mit KI-Agenten

KI-Coding-Agenten können beim Erstellen und Iterieren eines benutzerdefinierten Frontends helfen, besonders wenn Sie die PowerShell Universal-Einschränkungen im Vorfeld angeben. Geben Sie dem Agenten den Anforderungspfad, das Framework, die API-Routen, die Authentifizierungserwartungen und den Build-Befehl an, den Sie verwenden möchten.

PowerShell Universal-Skills können KI-Agenten wiederverwendbare PSU-spezifische Anweisungen, Skripte und Referenzen bereitstellen. Devolutions pflegt eine Sammlung dieser Skills im Repository powershell-universal-skills. Diese Skills folgen dem Agent Skills-Format und können Agenten helfen, gängige PowerShell Universal-Aufgaben mit mehr produktspezifischem Kontext auszuführen.

Das Repository enthält zum Beispiel einen install-sandbox-psu-Skill zum Installieren von PowerShell Universal in einer Sandbox-Umgebung für Test und Entwicklung. Sie können die Sammlung mit der Skills-CLI installieren.

npx skills add devolutions/powershell-universal-skills

Nach der Installation können unterstützte Coding-Agenten die Skills automatisch verwenden, wenn eine relevante PowerShell Universal-Aufgabe erkannt wird. Dies kann nützlich sein, wenn ein Agent ein benutzerdefiniertes Frontend erstellen und außerdem eine lokale PSU-Instanz einrichten, unterstützende Ressourcen konfigurieren oder das Frontend gegen eine Sandbox-Umgebung validieren soll.

Zum Beispiel:

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.

Nützliche Angaben für Prompts sind:

• Das zu verwendende Framework und der Paketmanager.
• Der Anforderungspfad des veröffentlichten Ordners.
• Die erwarteten API-Endpunkt-URLs und JSON-Formen.
• Das OpenAPI-Dokument oder die Swagger-URL für die Frontend-APIs.
• Ob das Frontend öffentlich ist oder eine Authentifizierung erfordert.
• Rollenspezifisches Verhalten, das die Benutzeroberfläche anzeigen oder ausblenden soll.
• Der Build-Ausgabeordner, der veröffentlicht wird.
• Alle installierten PowerShell Universal-Agent-Skills, die der Agent verwenden soll.

Nachdem der Agent das Frontend erstellt hat, überprüfen Sie die Build-Konfiguration, führen Sie den Produktions-Build aus und veröffentlichen Sie nur den generierten Ausgabeordner mit New-PSUPublishedFolder oder über die Seite Platform / Published Folders.