> 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 Erstellen Sie benutzerdefinierte Frontends für PowerShell Universal mit React, Vue oder einfachem HTML und CSS und hosten Sie sie dann als veröffentlichte Ordner und rufen Sie PSU-API-Endpunkte auf. ## Benutzerdefinierte Frontends Benutzerdefinierte Frontends sind statische Webanwendungen, die Sie mit gängigen Web-Werkzeugen erstellen und mit PowerShell Universal hosten. Sie sind nützlich, wenn Sie ein JavaScript-Framework verwenden, ein bestehendes Designsystem wiederverwenden oder die volle Kontrolle über die clientseitige Erfahrung haben möchten. PowerShell Universal muss Ihren Frontend-Quellcode 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 gängiges 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, beispielsweise 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 Basis-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 hashbasiertes 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 auf einem anderen Ursprung als PowerShell Universal läuft, konfigurieren Sie [CorsHosts](/powershell-universal/de/config/settings.md#corshosts) oder verwenden Sie die Proxy-Funktion des Frontend-Entwicklungsservers. Verwenden Sie in der Produktion vorzugsweise relative URLs, 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. Fügen Sie das CSS auf dieselbe Weise ein wie in jeder anderen statischen Webanwendung. Installieren Sie für die meisten Anwendungen das CSS-Framework über Ihren Paketmanager und binden Sie es in das Bundle ein. Dadurch bleibt die Anwendung eigenständig und vermeidet die Abhängigkeit von externen CDNs. ```powershell npm install bootstrap ``` ```javascript import 'bootstrap/dist/css/bootstrap.min.css' ``` Das benutzerdefinierte Frontend ist unabhängig von der Admin Console und dem PowerShell Universal App Framework. Fügen Sie alle Stile, Fonts und Assets, die Ihre Anwendung benötigt, in die Build-Ausgabe ein oder stellen Sie sie aus einem 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 Antwortstruktur, die Authentifizierung und die Rollenanforderungen steuern. ```powershell New-PSUEndpoint -Url '/frontend/profile' -Method Get -Authentication -Endpoint { [PSCustomObject]@{ UserName = $User.Identity.Name ServerTime = Get-Date } } ``` Rufen Sie den Endpunkt vom Frontend aus 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 `Content-Type`-Header 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 hat. Erwägen Sie für benutzerorientierte Workflows, einen kleineren benutzerdefinierten API-Endpunkt bereitzustellen, der nur den Vorgang ausführt, den das Frontend benötigt. Vermeiden Sie das Erstellen benutzerdefinierter Endpunkt-URLs, die mit internen Management-API-URLs in Konflikt stehen. Weitere Details 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 Standardformat beschreibt. Entwickler und KI-Agenten können sie nutzen, um Routen, HTTP-Methoden, Parameter, Authentifizierungsanforderungen, Anfrage-Bodies, Antwortstrukturen und Statuscodes zu 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. Definieren Sie für umfangreichere API-Verträge 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, präzisere 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-Helfer, Formulare, Validierung, Ladezustände und Fehlerbehandlung zu generieren, die den tatsächlichen Endpunkten entsprechen. ## Authentifizierung Veröffentlichte Ordner und API-Endpunkte können unabhängig voneinander Authentifizierung und Rollen erfordern. Um Benutzer zur Anmeldung zu verpflichten, bevor die Frontend-Dateien geladen werden, 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 mitgesendet werden. App-Token sind nützlich für Automatisierung, externe Integrationen und Server-zu-Server-Aufrufe. Betten Sie App-Token nicht in Browser-JavaScript ein, speichern Sie sie nicht im Local Storage und committen Sie sie nicht mit dem 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 tatsächlich mit einem App-Token von einem vertrauenswürdigen Client aufrufen müssen, senden Sie es im `Authorization`-Header. ````http Authorization: ****** Universal also supports the `X-PSU-Authorization` header for scenarios where a reverse proxy needs to use the standard `Authorization` header for another purpose. See [App Tokens](/pages/ybubDKrhYyjSXn4SbSJH) for token management guidance. ## Hosting Static Assets Use [published folders](/pages/7K71tKGBkFetUzIPmCdd) to host the compiled frontend files. The published folder maps a local file system path to a request path on the PowerShell Universal web server. ```powershell New-PSUPublishedFolder -Name 'Dashboard' -Path 'C:\Apps\Dashboard\dist' -RequestPath '/dashboard' -DefaultDocument 'index.html' ```` Nach der Veröffentlichung können Benutzer das Frontend über den Anforderungspfad öffnen. ```http http://localhost:5000/dashboard ``` Der Parameter `-DefaultDocument` stellt `index.html` bereit, wenn der Benutzer den Ordner-Root anfordert. Dies ist für Single-Page-Anwendungen wichtig. Verwenden Sie für direkte Links zu verschachtelten clientseitigen Routen hashbasiertes Routing oder stellen Sie sicher, dass Ihr Hosting-Pfad den Frontend-Einstiegspunkt für diese Routen 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 im selben Build-Ausgabeordner liegen. 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 Aufsetzen und Weiterentwickeln eines benutzerdefinierten Frontends helfen, insbesondere 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 dabei helfen, gängige PowerShell Universal-Aufgaben mit mehr produktspezifischem Kontext auszuführen. Beispielsweise enthält das Repository einen `install-sandbox-psu`-Skill zur Installation von PowerShell Universal in einer Sandbox-Umgebung für Tests 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 zugleich 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 Details, die in Prompts enthalten sein sollten: * Das zu verwendende Framework und der Paketmanager. * Der Anforderungspfad des veröffentlichten Ordners. * Die erwarteten API-Endpunkt-URLs und JSON-Strukturen. * 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 ein- 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 **Build > 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.