Frontends personnalisés

Interfaces frontales personnalisées

Les interfaces frontales personnalisées sont des applications Web statiques que vous créez avec des outils Web standard et que vous hébergez avec PowerShell Universal. Elles sont utiles lorsque vous souhaitez utiliser un cadre JavaScript, réutiliser un système de design existant ou avoir un contrôle complet sur l'expérience côté client.

PowerShell Universal n'a pas besoin de compiler ni de comprendre le code source de votre interface frontale. Créez l'application avec les outils de votre choix, publiez les fichiers générés avec un dossier publié, et appelez les API de PowerShell Universal à partir du navigateur.

Cela diffère des applis statiques, qui sont construites à partir de définitions d'applications PowerShell Universal. Les interfaces frontales personnalisées utilisent directement du HTML, du CSS et du JavaScript standard.

Utilisation de bibliothèques JavaScript

Vous pouvez utiliser React, Vue, Angular, Svelte ou toute autre bibliothèque frontale qui produit des fichiers statiques. PowerShell Universal sert la sortie compilée, comme un dossier dist, build ou wwwroot.

Un flux de travail typique est :

1. Créez le projet d'interface frontale avec les outils du cadre.
2. Configurez la construction pour utiliser le chemin de requête que vous publierez dans PowerShell Universal.
3. Construisez l'interface frontale.
4. Publiez la sortie de construction comme dossier publié.

Lorsque vous hébergez l'application sous un chemin tel que /dashboard, configurez le chemin de base de votre bundler afin que les URL JavaScript, CSS, d'images et de polices soient résolues correctement. Évitez /portal, car cela entre en conflit avec le PowerShell Universal Portal intégré.

Pour les applications basées sur Vite, définissez l'option base.

import { defineConfig } from 'vite'

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

Pour les applications Angular, définissez le base href lors de la construction.

ng build --base-href /dashboard/

Si l'application utilise le routage côté client, configurez le routeur pour utiliser le chemin de requête publié. Vous pouvez aussi utiliser le routage basé sur le hachage lorsque vous ne voulez pas que le serveur gère directement les liens profonds.

Pendant le développement, vous pouvez exécuter le serveur de développement local du cadre et appeler les API de PowerShell Universal à partir du navigateur. Si le serveur de développement s'exécute sur une origine différente de celle de PowerShell Universal, configurez CorsHosts ou utilisez la fonctionnalité de proxy du serveur de développement frontal. En production, privilégiez les URL relatives afin que les appels reviennent à la même instance de PowerShell Universal qui a servi l'interface frontale.

Utilisation de cadres CSS

Vous pouvez utiliser des cadres CSS tels que Tailwind CSS, Bootstrap, Bulma ou des bibliothèques de composants propres à un cadre. Incluez le CSS de la même façon que dans n'importe quelle application Web statique.

Pour la plupart des applications, installez le cadre CSS avec votre gestionnaire de paquets et incluez-le dans le bundle. Cela permet à l'application de rester autonome et évite de dépendre de CDN externes.

npm install bootstrap

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

L'interface frontale personnalisée est indépendante de la console d'administration et du PowerShell Universal App Framework. Incluez tous les styles, polices et actifs requis par votre application dans la sortie de construction ou servez-les à partir d'un autre dossier publié.

Appel des API PSU

Les interfaces frontales personnalisées peuvent appeler à la fois des terminaux d'API personnalisés et l'API de gestion de PowerShell Universal.

Utilisez des terminaux d'API personnalisés pour les données et les actions propres à l'application. C'est l'approche recommandée pour la plupart des interfaces frontales personnalisées, car vous contrôlez la route, la validation des entrées, la forme de la réponse, l'authentification et les exigences de rôle.

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

À partir de l'interface frontale, appelez le terminal avec 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()

Pour les requêtes JSON, envoyez l'en-tête Content-Type et analysez le corps dans le terminal ou utilisez un bloc 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' })
})

L'API de gestion est disponible sous /api/v1 et est destinée aux opérations administratives. Utilisez-la lorsque vous construisez une interface frontale administrative et que l'utilisateur connecté possède les permissions requises. Pour les flux de travail destinés aux utilisateurs, envisagez d'exposer un terminal d'API personnalisé plus restreint qui exécute uniquement l'opération dont l'interface frontale a besoin.

Évitez de créer des URL de terminaux personnalisés qui entrent en conflit avec les URL internes de l'API de gestion. Consultez Terminaux d'API et Sécurité des API pour plus de détails.

Documenter les API avec OpenAPI

La documentation OpenAPI est utile lors de la création d'interfaces frontales personnalisées, car elle décrit le contrat d'API dans un format standard. Les développeurs et les agents d'IA peuvent l'utiliser pour comprendre les routes, les méthodes HTTP, les paramètres, les exigences d'authentification, les corps de requête, les formes de réponse et les codes de statut avant d'écrire le code frontal.

Créez une définition de documentation de terminaux pour l'API utilisée par votre interface frontale et assignez-y les terminaux connexes.

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
}

Les définitions OpenAPI apparaissent dans le tableau de bord Swagger intégré.

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

Utilisez l'aide basée sur les commentaires dans les scripts de terminaux pour documenter l'objectif du terminal et ses paramètres. Pour des contrats d'API plus riches, définissez les types d'entrée et de sortie dans la définition de documentation des terminaux et référencez-les dans les sections .INPUTS et .OUTPUTS. Cela aide les clients générés, les outils de test et les agents d'IA à produire des requêtes plus exactes.

Lorsque vous travaillez avec un agent d'IA, fournissez le document OpenAPI ou l'URL Swagger ainsi que les exigences de l'interface frontale. L'agent peut utiliser le contrat pour générer des clients d'API typés, des assistants de requête, des formulaires, la validation, les états de chargement et la gestion des erreurs qui correspondent aux terminaux réels.

Authentification

Les dossiers publiés et les terminaux d'API peuvent exiger une authentification et des rôles indépendamment.

Pour obliger les utilisateurs à se connecter avant de charger les fichiers de l'interface frontale, activez l'authentification sur le dossier publié.

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

Pour protéger les données et les actions, activez l'authentification sur les terminaux d'API que l'interface frontale appelle.

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

Lorsque l'interface frontale est servie à partir de la même instance de PowerShell Universal, l'authentification par témoin fonctionne naturellement pour les utilisateurs connectés. Utilisez credentials: 'same-origin' avec fetch afin que les identifiants du navigateur soient inclus dans les requêtes vers les terminaux authentifiés.

Les jetons d'appli sont utiles pour l'automatisation, les intégrations externes et les appels de serveur à serveur. N'intégrez pas de jetons d'appli dans le JavaScript du navigateur, ne les stockez pas dans le stockage local et ne les archivez pas avec le code source de l'interface frontale. Si une interface frontale doit effectuer une opération qui exige des permissions élevées, créez un terminal d'API personnalisé avec l'authentification appropriée, des vérifications de rôle et une logique côté serveur.

Lorsque vous devez appeler des API avec un jeton d'appli à partir d'un client de confiance, envoyez-le dans l'en-tête Authorization.

Authorization: Bearer <app-token>

PowerShell Universal prend aussi en charge l'en-tête X-PSU-Authorization pour les scénarios où un proxy inverse doit utiliser l'en-tête Authorization standard à d'autres fins. Consultez Jetons d'appli pour des conseils sur la gestion des jetons.

Hébergement des actifs statiques

Utilisez des dossiers publiés pour héberger les fichiers compilés de l'interface frontale. Le dossier publié mappe un chemin du système de fichiers local à un chemin de requête sur le serveur Web de PowerShell Universal.

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

Après la publication, les utilisateurs peuvent ouvrir l'interface frontale au chemin de requête.

http://localhost:5000/dashboard

Le paramètre -DefaultDocument sert index.html lorsque l'utilisateur demande la racine du dossier. C'est important pour les applications monopages. Pour les liens directs vers des routes imbriquées côté client, utilisez le routage basé sur le hachage ou assurez-vous que votre chemin d'hébergement peut retourner le point d'entrée de l'interface frontale pour ces routes.

Publiez uniquement le dossier de sortie compilée. Ne publiez pas de dossiers sources contenant des fichiers de configuration, des métadonnées de paquets, des fichiers d'environnement ou tout autre contenu qui ne devrait pas être téléchargeable.

Les actifs statiques tels que les images, les polices et les fragments JavaScript générés peuvent se trouver dans le même dossier de sortie de construction. Si vous devez partager des actifs entre plusieurs interfaces frontales ou applis, publiez un dossier distinct tel que /assets et référencez-le à partir de l'interface frontale.

Construction avec des agents d'IA

Les agents de codage d'IA peuvent aider à échafauder et à faire évoluer une interface frontale personnalisée, particulièrement lorsque vous fournissez d'emblée les contraintes de PowerShell Universal. Donnez à l'agent le chemin de requête, le cadre, les routes d'API, les attentes en matière d'authentification et la commande de construction que vous prévoyez utiliser.

Les compétences PowerShell Universal peuvent fournir aux agents d'IA des instructions, des scripts et des références réutilisables propres à PSU. Devolutions maintient une collection de ces compétences dans le dépôt powershell-universal-skills. Ces compétences suivent le format Agent Skills et peuvent aider les agents à effectuer des tâches courantes de PowerShell Universal avec plus de contexte propre au produit.

Par exemple, le dépôt inclut une compétence install-sandbox-psu pour installer PowerShell Universal dans un environnement de bac à sable à des fins de test et de développement. Vous pouvez installer la collection avec l'interface de ligne de commande des compétences.

npx skills add devolutions/powershell-universal-skills

Une fois installées, les agents de codage pris en charge peuvent utiliser les compétences automatiquement lorsqu'une tâche PowerShell Universal pertinente est détectée. Cela peut être utile lorsque vous voulez qu'un agent crée une interface frontale personnalisée et configure aussi une instance PSU locale, configure des ressources de soutien ou valide l'interface frontale par rapport à un environnement de bac à sable.

Par exemple :

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.

Les détails utiles à inclure dans les invites sont :

• Le cadre et le gestionnaire de paquets à utiliser.
• Le chemin de requête du dossier publié.
• Les URL de terminaux d'API attendues et les formes JSON.
• Le document OpenAPI ou l'URL Swagger pour les API de l'interface frontale.
• Si l'interface frontale est publique ou exige une authentification.
• Le comportement propre aux rôles que l'interface utilisateur devrait afficher ou masquer.
• Le dossier de sortie de construction qui sera publié.
• Toutes les compétences d'agent PowerShell Universal installées que l'agent devrait utiliser.

Après que l'agent a créé l'interface frontale, examinez la configuration de construction, exécutez la construction de production et publiez uniquement le dossier de sortie généré avec New-PSUPublishedFolder ou la page Plateforme / Dossiers publiés.