Frontends personalizados

Frontends personalizados

Los frontends personalizados son aplicaciones web estáticas que se crean con herramientas web estándar y se alojan con PowerShell Universal. Son útiles cuando desea utilizar un framework de JavaScript, reutilizar un sistema de diseño existente o tener control total sobre la experiencia del lado del cliente.

PowerShell Universal no necesita compilar ni comprender el código fuente de su frontend. Cree la aplicación con las herramientas que prefiera, publique los ficheros generados con una carpeta publicada y llame a las API de PowerShell Universal desde el navegador.

Esto se diferencia de las aplicaciones estáticas, que se crean a partir de definiciones de aplicaciones de PowerShell Universal. Los frontends personalizados utilizan HTML, CSS y JavaScript estándar directamente.

Uso de bibliotecas de JavaScript

Puede utilizar React, Vue, Angular, Svelte o cualquier otra biblioteca de frontend que produzca ficheros estáticos. PowerShell Universal sirve la salida compilada, como una carpeta dist, build o wwwroot.

Un flujo de trabajo típico es:

1. Cree el proyecto de frontend con las herramientas del framework.
2. Configure la compilación para que utilice la ruta de solicitud que publicará en PowerShell Universal.
3. Compile el frontend.
4. Publique la salida de la compilación como una carpeta publicada.

Cuando aloje la aplicación en una ruta como /dashboard, configure la ruta base de su empaquetador para que las URL de JavaScript, CSS, imágenes y fuentes se resuelvan correctamente. Evite /portal, ya que entra en conflicto con el Portal integrado de PowerShell Universal.

Para las aplicaciones basadas en Vite, establezca la opción base.

import { defineConfig } from 'vite'

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

Para las aplicaciones de Angular, establezca el base href al compilar.

ng build --base-href /dashboard/

Si la aplicación utiliza enrutamiento del lado del cliente, configure el enrutador para que utilice la ruta de solicitud publicada. También puede utilizar enrutamiento basado en hash cuando no desee que el servidor gestione directamente los enlaces profundos.

Durante el desarrollo, puede ejecutar el servidor de desarrollo local del framework y llamar a las API de PowerShell Universal desde el navegador. Si el servidor de desarrollo se ejecuta en un origen distinto al de PowerShell Universal, configure CorsHosts o utilice la función de proxy del servidor de desarrollo del frontend. En producción, es preferible utilizar URL relativas para que las llamadas regresen a la misma instancia de PowerShell Universal que sirvió el frontend.

Uso de frameworks CSS

Puede utilizar frameworks CSS como Tailwind CSS, Bootstrap, Bulma o bibliotecas de componentes específicas de un framework. Incluya el CSS de la misma manera que lo haría en cualquier aplicación web estática.

Para la mayoría de las aplicaciones, instale el framework CSS mediante su gestor de paquetes e inclúyalo en el paquete. Así la aplicación se mantiene autónoma y se evita depender de CDN externas.

npm install bootstrap

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

El frontend personalizado es independiente de la Consola de administración y del App Framework de PowerShell Universal. Incluya todos los estilos, fuentes y recursos que necesite su aplicación en la salida de la compilación o sírvalos desde otra carpeta publicada.

Llamar a las API de PSU

Los frontends personalizados pueden llamar tanto a endpoints de API personalizados como a la API de administración de PowerShell Universal.

Utilice endpoints de API personalizados para los datos y las acciones específicas de la aplicación. Este es el enfoque recomendado para la mayoría de los frontends personalizados, ya que usted controla la ruta, la validación de la entrada, la forma de la respuesta, la autenticación y los requisitos de roles.

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

Desde el frontend, llame al endpoint con 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()

Para las solicitudes JSON, envíe el encabezado Content-Type y analice el cuerpo en el endpoint o utilice un bloque 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' })
})

La API de administración está disponible en /api/v1 y está destinada a operaciones administrativas. Utilícela cuando esté creando un frontend administrativo y el usuario que ha iniciado sesión tenga los permisos necesarios. Para los flujos de trabajo orientados al usuario, considere exponer un endpoint de API personalizado más reducido que realice únicamente la operación que necesita el frontend.

Evite crear URL de endpoints personalizados que entren en conflicto con las URL internas de la API de administración. Consulte Endpoints de API y Seguridad de la API para obtener más detalles.

Documentar API con OpenAPI

La documentación de OpenAPI es útil al crear frontends personalizados porque describe el contrato de la API en un formato estándar. Los desarrolladores y los agentes de IA pueden utilizarla para comprender las rutas, los métodos HTTP, los parámetros, los requisitos de autenticación, los cuerpos de las solicitudes, las formas de las respuestas y los códigos de estado antes de escribir el código del frontend.

Cree una definición de documentación de endpoints para la API que utiliza su frontend y asígnele los endpoints relacionados.

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
}

Las definiciones de OpenAPI aparecen en el panel integrado de Swagger.

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

Utilice la ayuda basada en comentarios en los scripts de los endpoints para documentar el propósito del endpoint y sus parámetros. Para contratos de API más completos, defina los tipos de entrada y salida en la definición de documentación de endpoints y referéncielos desde las secciones .INPUTS y .OUTPUTS. Esto ayuda a que los clientes generados, las herramientas de pruebas y los agentes de IA produzcan solicitudes más precisas.

Cuando trabaje con un agente de IA, proporcione el documento de OpenAPI o la URL de Swagger junto con los requisitos del frontend. El agente puede utilizar el contrato para generar clientes de API con tipos, ayudantes de solicitudes, formularios, validación, estados de carga y gestión de errores que coincidan con los endpoints reales.

Autenticación

Las carpetas publicadas y los endpoints de API pueden requerir autenticación y roles de forma independiente.

Para exigir que los usuarios inicien sesión antes de cargar los ficheros del frontend, habilite la autenticación en la carpeta publicada.

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

Para proteger los datos y las acciones, habilite la autenticación en los endpoints de API a los que llama el frontend.

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

Cuando el frontend se sirve desde la misma instancia de PowerShell Universal, la autenticación por cookies funciona de forma natural para los usuarios que han iniciado sesión. Utilice credentials: 'same-origin' con fetch para que las credenciales del navegador se incluyan en las solicitudes a los endpoints autenticados.

Los tokens de aplicación son útiles para la automatización, las integraciones externas y las llamadas de servidor a servidor. No incruste tokens de aplicación en el JavaScript del navegador, no los almacene en el almacenamiento local ni los confirme con el código fuente del frontend. Si un frontend necesita realizar una operación que requiere permisos elevados, cree un endpoint de API personalizado con la autenticación adecuada, comprobaciones de roles y lógica del lado del servidor.

Cuando realmente necesite llamar a las API con un token de aplicación desde un cliente de confianza, envíelo en el encabezado Authorization.

Authorization: Bearer <app-token>

PowerShell Universal también admite el encabezado X-PSU-Authorization para escenarios en los que un proxy inverso necesita utilizar el encabezado Authorization estándar para otro propósito. Consulte Tokens de aplicación para obtener orientación sobre la gestión de tokens.

Alojar recursos estáticos

Utilice carpetas publicadas para alojar los ficheros compilados del frontend. La carpeta publicada asigna una ruta del sistema de ficheros local a una ruta de solicitud en el servidor web de PowerShell Universal.

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

Después de la publicación, los usuarios pueden abrir el frontend en la ruta de solicitud.

http://localhost:5000/dashboard

El parámetro -DefaultDocument sirve index.html cuando el usuario solicita la raíz de la carpeta. Esto es importante para las aplicaciones de una sola página. Para los enlaces directos a rutas anidadas del lado del cliente, utilice enrutamiento basado en hash o asegúrese de que su ruta de alojamiento pueda devolver el punto de entrada del frontend para esas rutas.

Publique únicamente la carpeta de salida compilada. No publique carpetas de origen que contengan ficheros de configuración, metadatos de paquetes, ficheros de entorno u otro contenido que no deba poder descargarse.

Los recursos estáticos, como imágenes, fuentes y fragmentos de JavaScript generados, pueden residir en la misma carpeta de salida de la compilación. Si necesita compartir recursos entre varios frontends o aplicaciones, publique una carpeta independiente, como /assets, y referéncela desde el frontend.

Desarrollo con agentes de IA

Los agentes de codificación con IA pueden ayudar a crear la estructura de un frontend personalizado e iterar sobre él, especialmente si proporciona de antemano las restricciones de PowerShell Universal. Indique al agente la ruta de solicitud, el framework, las rutas de la API, las expectativas de autenticación y el comando de compilación que piensa utilizar.

Las skills de PowerShell Universal pueden proporcionar a los agentes de IA instrucciones, scripts y referencias reutilizables específicas de PSU. Devolutions mantiene una colección de estas skills en el repositorio powershell-universal-skills. Estas skills siguen el formato Agent Skills y pueden ayudar a los agentes a realizar tareas habituales de PowerShell Universal con más contexto específico del producto.

Por ejemplo, el repositorio incluye una skill install-sandbox-psu para instalar PowerShell Universal en un entorno de sandbox destinado a pruebas y desarrollo. Puede instalar la colección con la CLI de skills.

npx skills add devolutions/powershell-universal-skills

Una vez instaladas, los agentes de codificación compatibles pueden utilizar las skills automáticamente cuando se detecta una tarea relevante de PowerShell Universal. Esto puede resultar útil cuando desea que un agente cree un frontend personalizado y también configure una instancia local de PSU, configure recursos de apoyo o valide el frontend en un entorno de sandbox.

Por ejemplo:

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.

Algunos detalles útiles que incluir en los prompts son:

• El framework y el gestor de paquetes que se debe utilizar.
• La ruta de solicitud de la carpeta publicada.
• Las URL esperadas de los endpoints de API y las formas del JSON.
• El documento de OpenAPI o la URL de Swagger de las API del frontend.
• Si el frontend es público o requiere autenticación.
• El comportamiento específico de cada rol que la interfaz de usuario debe mostrar u ocultar.
• La carpeta de salida de la compilación que se publicará.
• Cualquier skill de agente de PowerShell Universal instalada que el agente deba utilizar.

Después de que el agente cree el frontend, revise la configuración de compilación, ejecute la compilación de producción y publique únicamente la carpeta de salida generada con New-PSUPublishedFolder o con la página Plataforma / Carpetas publicadas.