> 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/de/apps/custom-frontends.md). # 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](/powershell-universal/de/plattform/published-folders.md) und rufen Sie PowerShell Universal-APIs aus dem Browser auf. Dies unterscheidet sich von [statischen Apps](/powershell-universal/de/apps/static-apps.md), 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`. ```typescript import { defineConfig } from 'vite' export default defineConfig({ base: '/dashboard/' }) ``` Setzen Sie für Angular-Anwendungen die Base-Href beim Erstellen. ```powershell 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](/powershell-universal/de/config/settings.md#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. ```powershell npm install bootstrap ``` ```javascript 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](/powershell-universal/de/api/endpoints.md) 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. ```powershell 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. ```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() ``` Senden Sie für JSON-Anfragen den Header `Content-Type` und parsen Sie den Body im Endpunkt oder verwenden Sie einen `param`-Block. ```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' }) }) ``` 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](/powershell-universal/de/api/endpoints.md) und [API-Sicherheit](/powershell-universal/de/api/security.md). ## APIs mit OpenAPI dokumentieren [OpenAPI](/powershell-universal/de/api/openapi.md)-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. ```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 } ``` OpenAPI-Definitionen erscheinen im integrierten Swagger-Dashboard. ```http 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. ```powershell 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. ```powershell 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. ```http Authorization: Bearer ``` 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](/powershell-universal/de/sicherheit/app-tokens.md). ## Statische Assets hosten Verwenden Sie [veröffentlichte Ordner](/powershell-universal/de/plattform/published-folders.md), um die kompilierten Frontend-Dateien zu hosten. Der veröffentlichte Ordner ordnet einen lokalen Dateisystempfad einem Anforderungspfad auf dem PowerShell Universal-Webserver zu. ```powershell 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 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](https://github.com/Devolutions/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. ```powershell 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. --- # 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/de/apps/custom-frontends.md?ask=&goal= ``` `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.