Compartir a través de

Introducción al complemento Power Pages para GitHub Copilot CLI y Claude Code (versión preliminar)

El complemento Power Pages para GitHub Copilot CLI y Claude Code proporciona un flujo de trabajo asistido por IA para crear, implementar y administrar aplicaciones modernas single-page (SPA) en Power Pages. En lugar de aplicar scaffolding manualmente a los proyectos, escribir código base de API y configurar permisos, describa lo que desea en lenguaje natural y el complemento gestiona la implementación.

El complemento admite el ciclo de vida completo de desarrollo de sitios a través de habilidades conversacionales, desde crear la estructura de un nuevo sitio hasta implementarlo, configurar modelos de datos de la plataforma Dataverse y configurar la autenticación.

Importante

  • Esta característica se encuentra en su versión preliminar.
  • Las características en vista previa no se han diseñado para un uso de producción y pueden tener una funcionalidad restringida. Estas características están disponibles antes de una versión oficial para que los clientes puedan tener acceso anticipado y proporcionar comentarios.
  • Revisar las propuestas del agente antes de aprobar

Prerrequisitos

Antes de comenzar, compruebe que tiene el software y los permisos necesarios.

Requisitos de software

Componente Versión mínima Información adicional
Node.js. 18.0 o posterior Descargar Node.js
CLI de Power Platform (PAC CLI) 2.6.3 o posterior (necesario para la lógica del servidor) Instalación de la CLI de PAC
CLI de Azure Más reciente Install CLI de Azure
GitHub Copilot CLI o Claude Code Más reciente GitHub Copilot CLI o Claude Code
Extensión de Visual Studio Code y de Power Platform Tools (opcional) Más reciente Descarga de VS Code e instalación de Power Platform Tools

También necesita:

  • Un entorno de Power Platform con Power Pages habilitado.
  • Una sesión autenticada de la CLI de PAC conectada al entorno de destino. Ejecute pac auth create si aún no se ha conectado.
  • Una sesión de la interfaz de línea de comandos de Azure que ha iniciado sesión en el mismo arrendatario. Ejecute az login para autenticarse.

Verificar autenticación:

Compruebe que está autenticado mediante el pac auth list comando .

pac auth list           # Should show authenticated profile

Si no está autenticado, ejecute este comando:

pac auth create --environment <Instance url>        # Authenticate to Power Platform

Sugerencia

Para obtener la dirección URL de la instancia, vaya a Power Pages Home, seleccione el icono Configuración en la esquina superior derecha y, a continuación, seleccione Detalles de la sesión.

Instalación del complemento

Instale el complemento Power Pages desde Marketplace. Si usa GitHub Copilot CLI, consulte la documentación de extensiones de la CLI Copilot para conocer los pasos de instalación equivalentes. Los siguientes comandos usan la sintaxis de Claude Code.

Ejecute el instalador para configurar todos los complementos con la actualización automática habilitada:

Windows (PowerShell):

iwr https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js -OutFile install.js; node install.js; del install.js

macOS/Linux/Windows (cmd):

curl -fsSL https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js | node

El instalador automáticamente:

  • Instala la pac CLI si aún no está instalada.
  • Detecta herramientas disponibles, como Claude Code y GitHub Copilot CLI.
  • Registra el marketplace del complemento e instala todos los complementos enumerados.
  • Habilita la actualización automática para que los complementos permanezcan actualizados.

Después de la instalación, reinicie Claude Code o GitHub Copilot CLI para acceder a las funciones del complemento como comandos slash en la sesión del agente.

Instalación desde Marketplace

  1. Abra Claude Code en su terminal.

  2. Agregue el marketplace de Microsoft:

    /plugin marketplace add microsoft/power-platform-skills

  3. Instale el complemento Power Pages:

    /plugin install power-pages@power-platform-skills

Después de instalar el complemento, reinicie Claude Code o GitHub Copilot CLI para acceder a las funcionalidades del complemento como comandos de barra en la sesión de tu agente.

Sugerencia

Para recibir actualizaciones automáticamente en el mercado y capacidades, active las actualizaciones automáticas. Use el /plugin comando, vaya a Marketplaces, elija Marketplace y active la actualización automática.

Resumen de habilidades

El complemento proporciona aptitudes que cubren el ciclo de vida completo de un sitio de Power Pages. Invoque cada habilidad de forma conversacional, ya sea como un comando o describiendo lo que desea hacer.

Habilidad Comando Qué hace
Crear sitio /create-site Configura un sitio, aplica la dirección del diseño y crea páginas y componentes.
Desplegar sitio /deploy-site Compila el proyecto y lo carga en Power Pages mediante la CLI de PAC
Activar sitio /activate-site Aprovisiona un registro de sitio web y asigna una dirección URL pública
Configuración del modelo de datos /setup-datamodel Crea tablas, columnas y relaciones de Dataverse
Agregar datos de ejemplo (opcional) /add-sample-data Rellena tablas de Dataverse con registros de prueba realistas
Integración de la API web /integrate-webapi Genera código de cliente de API tipado, servicios y permisos de tabla
Configuración de la autenticación /setup-auth Agrega funcionalidad de inicio y cierre de sesión y control de acceso basado en roles
Creación de roles web /create-webroles Genera archivos YAML de rol web para la administración de acceso de usuarios
Agregar lógica de servidor /add-server-logic Genera puntos de conexión de JavaScript seguros del lado servidor para la validación, las llamadas API externas, la administración de secretos y las operaciones de datos.
Adición de flujo de nube /add-cloud-flow Integra los flujos de nube de Power Automate existentes en el sitio para los flujos de trabajo de aprobación, las notificaciones y la automatización programada.
Integrar el backend /integrate-backend Analiza el prototipo, determina el enfoque adecuado (API web, lógica de servidor o flujo de nube) para cada característica y organiza la secuencia de compilación completa.
Optimizar para motores de búsqueda /add-seo Genera robots.txt, sitemap.xml y etiquetas meta

Flujo de trabajo típico

Un flujo de trabajo de un extremo a otro común sigue esta secuencia:

  1. /create-site : Estructurar, diseñar y generar páginas
  2. /deploy-site : Cargar en el entorno de Power Pages
  3. /activate-site : configurar una dirección URL pública
  4. /setup-datamodel : Creación de tablas de Dataverse
  5. /add-sample-data : rellenar tablas con registros de prueba
  6. /integrate-webapi : generación de código de cliente de API y configuración de permisos
  7. /create-webroles : Definir roles de access
  8. /setup-auth : agregar inicio de sesión, cierre de sesión y interfaz de usuario basada en roles
  9. /add-server-logic : agregar puntos de conexión seguros del lado servidor
  10. /add-cloud-flow : Integración de flujos de Power Automate existentes
  11. /add-seo : optimización del motor de búsqueda
  12. /deploy-site : aplicar los cambios finales directamente

Sugerencia

  • No es necesario seguir este orden exacto. Cada aptitud comprueba sus propios requisitos previos e indica si falta algo. Por ejemplo, puede ejecutar /setup-auth antes /integrate-webapi de si el sitio necesita primero la autenticación.
  • Si no está seguro de qué enfoque usar para cada característica, ejecute /integrate-backend en lugar de los pasos 4 a 10 individualmente. Analiza el prototipo, determina si cada característica necesita api web, lógica de servidor o un flujo de nube y organiza las aptitudes en el orden correcto.

Cree su sitio de Power Pages

En este tutorial se describe el ciclo de vida completo de la creación de un sitio de Power Pages con el complemento, desde el andamiaje hasta la implementación. En cada paso se describe lo que se dice y lo que hace el complemento en respuesta.

Paso 1: Crear el sitio

Describa el sitio que desee en lenguaje natural: para qué son las páginas que necesita y las preferencias de diseño, como la combinación de colores, el estilo de diseño o las fuentes. Ejecute /create-site o simplemente describa el sitio y el complemento reconozca la intención.

Si no especifica un marco, el complemento le pide que elija uno (React, Vue, Angular o Astro), entonces:

  1. Prepara el proyecto a partir de una plantilla y aplica el nombre, los colores y los tokens de diseño de tu sitio.
  2. Instala dependencias, inicia un servidor de desarrollo y abre una versión preliminar del explorador activo.
  3. Compila cada página, componente y ruta que solicitó con imágenes pertinentes.
  4. Crea confirmaciones de Git en hitos significativos para tener un historial de reversión integrado.

Paso 2: Implementar el sitio

Ejecute /deploy-site para cargar el sitio en Power Pages. El complemento:

  1. Comprueba que la CLI de PAC está instalada y la sesión de autenticación está activa.
  2. Confirma el entorno de destino con usted antes de continuar.
  3. Ejecuta una compilación de producción y carga la salida compilada.
  4. Crea un directorio de artefactos de implementación, si aún no existe uno.

Nota:

Si el entorno bloquea determinados archivos adjuntos, el complemento detecta el problema y proporciona instrucciones para resolverlo.

Paso 3: Activar el sitio

Ejecute /activate-site para que el sitio sea accesible públicamente. El complemento:

  1. Sugiere un subdominio basado en el nombre del sitio y le permite personalizarlo.
  2. Provisiona un registro de sitio web a través de la API de Power Platform.
  3. Sondea hasta que el sitio está activo y devuelve la dirección URL pública.

En este momento, tiene un sitio de trabajo en una dirección URL pública. Los pasos restantes agregan datos, autenticación y SEO. Omita los pasos que no se apliquen al sitio.

Paso 4: Configuración del modelo de datos

Ejecute /setup-datamodel para crear las tablas de Dataverse que necesita el sitio. Si ya tiene un diagrama er o un esquema específico, proporciónelo directamente en lugar de hacer que el agente analice el código.

El complemento genera un agente de Data Model Architect que:

  1. Analiza el código del sitio para determinar qué datos requieren las páginas y los componentes.
  2. Consulta el entorno de Dataverse para las tablas existentes para evitar duplicados.
  3. Propone un modelo de datos con tablas, columnas, tipos de datos y relaciones, visualizados como diagrama de ER.

Revise y apruebe la propuesta. El complemento no crea nada hasta que confirme. Después de la aprobación, el complemento crea las tablas y columnas a través de llamadas API y guarda un archivo de manifiesto que usan los pasos 5 y 6.

Paso 5: Agregar datos de ejemplo (opcional)

Ejecute /add-sample-data para rellenar las tablas con registros de prueba. Este paso requiere el modelo de datos del paso 4.

El complemento realiza las siguientes acciones:

  1. Lea el manifiesto para comprender las tablas, columnas y relaciones.
  2. Genera valores contextualmente adecuados para cada tipo de columna, como correos electrónicos realistas, fechas viables y cantidades de moneda con formato.
  3. Inserta registros en orden de dependencia (tablas primarias antes de las tablas secundarias) y actualiza los tokens de autenticación automáticamente durante las inserciones masivas.

Paso 6: Integración con la API web de Dataverse

Ejecute /integrate-webapi para reemplazar los datos ficticios por consultas dinámicas de Dataverse. Este paso requiere el modelo de datos del paso 4.

El complemento realiza las siguientes acciones:

  1. Examina el código base para los componentes que usan datos ficticios, llamadas de captura de marcador de posición o matrices codificadas de forma rígida. Asigna estos componentes a las tablas de Dataverse.
  2. Genera un agente de integración de API web para cada tabla que genera:
    • Un cliente de API compartido con administración de tokens anti falsificación y lógica de reintento.
    • Tipos de entidad y mapeadores de dominio de TypeScript.
    • Una capa de servicio CRUD.
    • Patrones específicos de cada marco, como los hooks de React, los composables de Vue o los servicios de Angular.
  3. Genera un agente de Permissions Architect que propone permisos de tabla y configuraciones del sitio.

Revise y aprueba la propuesta de permisos. El complemento no crea ningún archivo de configuración hasta que confirme.

Paso 7: Creación de roles web

Ejecute /create-webroles para definir roles de acceso de usuario. El complemento:

  1. Consulta el entorno para los roles web existentes para evitar duplicados.
  2. Genera definiciones de roles con identificadores únicos.
  3. Exige que cada sitio tenga como máximo un rol anónimo y un rol autenticado.

Paso 8: Configuración de la autenticación

Ejecute /setup-auth para agregar la funcionalidad de inicio de sesión y cierre de sesión. El complemento:

  1. Genera un servicio de autenticación para el flujo de Microsoft Entra ID con gestión de tokens antifalsificación.
  2. Crea un componente de interfaz de usuario de inicio de sesión o cierre de sesión integrado con el diseño del sitio.
  3. Agrega utilidades de control de acceso basadas en roles que muestran o ocultan elementos de interfaz de usuario en función de los roles en la web del usuario.
  4. Usa los patrones de tu framework en todo (ganchos de React, composables de Vue o servicios de Angular).

Paso 9: Agregar lógica de servidor

Ejecute /add-server-logic para agregar puntos de conexión seguros del lado servidor al sitio. Use La lógica del servidor cuando el sitio necesite lógica que no se pueda ejecutar en el explorador, como llamadas API externas, validación del lado servidor, administración de secretos o operaciones de datos entre entidades.

Importante

La compatibilidad con la lógica del servidor requiere la VERSIÓN 2.6.3 o posterior de la CLI de PAC. Use el script de instalación rápida para actualizar a la versión más reciente.

Describa lo que necesita en lenguaje sin formato y el complemento:

  1. Genera un agente de Server Logic Architect que analiza el caso de uso y clasifica su complejidad.
  2. Propone un diseño de punto de conexión, una configuración de seguridad y los permisos de tabla necesarios para su revisión.
  3. Después de aprobarlo, genera el punto de conexión de JavaScript del lado servidor en /_api/serverlogics/<name>.
  4. Crea un servicio cliente tipado para invocar el punto de conexión desde tus componentes.
  5. Actualiza los componentes para llamar al nuevo servicio.
  6. Configura asignaciones de roles web y permisos de tabla para el punto de conexión.

Revise y apruebe la propuesta. No se genera ningún código hasta que confirme.

Casos de uso comunes:

Nota:

Ejecute /add-server-logic una vez por caso de uso. Por ejemplo, si el sitio necesita un punto de conexión de validación de inventario y un punto de conexión de búsqueda global, ejecute la aptitud dos veces.

Paso 10: Integración de flujos en la nube

Ejecute /add-cloud-flow para integrar los flujos existentes en la nube de Power Automate en el sitio. Esta habilidad conecta tu sitio de Power Pages a los flujos que ya has creado en Power Automate. No crea nuevos flujos de nube.

El complemento:

  1. Registra el flujo de nube existente en el sitio.
  2. Genera código cliente para desencadenar el flujo desde sus páginas.
  3. Controla el estado asincrónico del flujo de trabajo y los patrones de devolución de llamada.
  4. Conectan el intercambio de datos entre la página y el flujo.

Use /add-cloud-flow para flujos de trabajo de aprobación, notificaciones por correo electrónico, trabajos programados y automatización controlada por eventos que se gestionan mejor con Power Automate en lugar de los puntos de conexión del lado del servidor.

Alternativa: utilizar /integrate-backend para poder planificar la capa completa de servicio.

Si no está seguro de qué características necesitan web API, lógica de servidor o un flujo de nube, ejecute en lugar de ejecutar /integrate-backend manualmente los pasos del 4 al 10. Esta habilidad actúa como un orquestador que:

  1. Analiza el prototipo para identificar todas las características que necesitan un nivel de servicio.
  2. Clasifica cada característica en el enfoque adecuado: API web para CRUD estándar, Lógica de servidor para la validación del lado servidor y API externas, o flujo de nube para flujos de trabajo de aprobación y automatización.
  3. Propone un plan de ejecución secuenciado con todas las aptitudes, dependencias y configuraciones.
  4. Después de que tú lo apruebes, organiza las habilidades en el orden correcto.

El plan es persistente, reanudable y editable. Deténgase tras cualquier paso para revisar el código generado o probar el sitio, y retómelo desde donde lo dejó ejecutando /integrate-backend de nuevo.

Paso 11: Agregar SEO

Ejecute /add-seo para optimizar el sitio para los motores de búsqueda. El complemento:

  1. Descubre rutas desde la configuración de enrutador de tu framework.
  2. Genera directivas del motor de búsqueda y un mapa del sitio para todas las rutas detectadas.
  3. Agrega etiquetas meta: viewport, charset, descripción, Open Graph, Twitter Card y referencias de favicon.

Paso 12: Implementar el sitio final

Si realiza algún paso opcional, vuelva a ejecutar /deploy-site para insertar los cambios en directo. El complemento ejecuta una compilación de producción y carga el sitio junto con todos los artefactos de implementación (permisos de tabla, configuración del sitio, roles web, archivos lógicos de servidor) en el entorno de Power Pages.

Verifica tu sitio

Después de completar las aptitudes, compruebe que el sitio de Power Pages funciona correctamente.

  1. Vaya a Power Pages.
  2. Busque el sitio en la lista Sitios activos .
  3. Obtenga una vista previa del sitio en el escritorio mediante la opción Vista previa .
  4. Pruebe la funcionalidad.

Sugerencias y procedimientos recomendados

Las siguientes sugerencias le ayudarán a aprovechar al máximo el complemento y el agente de codificación de IA al desarrollar sitios Power Pages.

Vigilar la salida del terminal para detectar herramientas faltantes en la primera ejecución

El complemento proporciona las aptitudes y los flujos de trabajo, pero el agente de codificación de IA ( GitHub Copilot CLI o Claude Code) ejecuta los comandos reales en la máquina. Cuando use estas herramientas por primera vez, observe detenidamente la salida del terminal. El agente de codificación de IA ejecuta comandos y scripts en segundo plano y algunos de estos comandos dependen de herramientas que podrían no instalarse en la máquina. Si se produce un error en un paso, la salida del terminal suele mostrar qué herramienta o comando no pudo encontrar.

Si ve un error como command not found o is not recognized, instale la herramienta que falta y vuelva a desencadenar el flujo de trabajo. El agente de codificación de IA reanuda su trabajo donde lo dejó tan pronto como la herramienta está disponible.

Revisar las propuestas del agente antes de aprobar

Los arquitectos de modelos de datos y los arquitectos de permisos de API web presentan propuestas antes de realizar cambios. Tómese el tiempo para revisar detenidamente estas propuestas.

  • Propuestas del modelo de datos: compruebe que los nombres de tabla, los tipos de columna y las relaciones coinciden con los requisitos empresariales. Es mucho más fácil ajustar una propuesta que cambiar el nombre de las columnas después de insertar los datos.
  • Propuestas de permisos: compruebe que cada rol tiene el nivel de acceso correcto (crear, leer, actualizar, eliminar) para cada tabla. Los permisos de tabla demasiado permisivos son un riesgo de seguridad común.

Pegar errores directamente con el contexto

Cuando se produce un error en algo, ya sea un error de compilación, un error de implementación o una excepción en tiempo de ejecución en el explorador, copie la salida de error completa. Péguelo junto con una breve descripción de lo que estaba haciendo. Cuanto más contexto proporcione, más rápido será la corrección.

Ejemplo: Error de compilación

I ran npm run build and got this error. Fix it.

error TS2339: Property 'jobTitle' does not exist on type 'JobPosting'.

  src/components/JobCard.tsx:24:31
    24   <Text>{posting.jobTitle}</Text>

Sugerencia

Incluya el nombre de archivo, el comando que ejecutó y lo que esperaba que suceda. El complemento usa este contexto para localizar el problema y aplicar una corrección dirigida en lugar de adivinar.

Compartir errores de la API web con la URL completa de la solicitud

Un problema común después de implementar es un error 403 de la API web de Power Pages cuando una columna no está habilitada para el acceso a la API. Cuando encuentre este error, pegue la dirección URL completa de la API y la respuesta de error JSON completa. El mensaje de error indica exactamente qué tabla y columna deben corregirse, y el complemento puede actualizar por usted el archivo YAML de permisos de tabla y la configuración del sitio.

Ejemplo: Columna no habilitada para la API web (403)

I'm getting a 403 error when the documents page loads. Here's the API call and the response. Fix the issue so this API works.

URL:
https://my-site.powerappsportals.com/_api/crd50_documents?$select=crd50_documentid,crd50_name,crd50_documentcategory,crd50_filetype,crd50_filesize,crd50_updateddate,crd50_description,_crd50_propertyid_value

Response:
{
  "error": {
    "code": "90040101",
    "message": "Attribute _crd50_propertyid_value in table crd50_document is not enabled for Web Api.",
    "innererror": {
      "code": "90040101",
      "message": "Attribute _crd50_propertyid_value in table crd50_document is not enabled for Web Api.",
      "type": "AttributePermissionIsMissing"
    }
  }
}

Este error (AttributePermissionIsMissing) significa que la columna _crd50_propertyid_value de búsqueda existe en la tabla Dataverse, pero no aparece en la configuración de permisos de tabla para la API web. El complemento resuelve este error mediante la adición de la columna que falta al permiso de tabla YAML en .powerpages-site/table-permissions/ y la reimplementación.

Nota:

Power Pages API web requiere que todas las columnas devueltas por una llamada API se muestren explícitamente en el permiso de tabla. Las propiedades de búsqueda (precedidas con _ y seguidas con _value) son fáciles de pasar por alto porque su nombre en la API difiere del nombre lógico de la columna en Dataverse. Cuando vea AttributePermissionIsMissing, agregue siempre esa columna a los permisos de la tabla. No cambie la consulta de API.

Sé específico sobre lo que quieras

Las solicitudes vagas producen resultados imprecisos. Indique al complemento exactamente lo que necesita, incluidas las preferencias de diseño, los campos de datos y el comportamiento.

En lugar de Probar
Crear una página de empleos "Crear una página de listados de trabajos con una barra de búsqueda en la parte superior, filtrar chips para ubicación y departamento, y una cuadrícula de tarjetas que muestra título, empresa, rango de salarios y una fecha publicada para cada trabajo"
"Corregir el estilo" "Las tarjetas de trabajo se apilan verticalmente en el escritorio. Haz que se muestren en una cuadrícula de tres columnas con un espacio de 16 píxeles en pantallas más anchas que 768px"
"Agregar algunos datos" "Agregar 20 publicaciones de trabajo de ejemplo en cuatro departamentos (Ingeniería, Marketing, Ventas, RR. HH.) con títulos realistas, rangos de salario entre $60k-$180k y fechas publicadas en los últimos 30 días"
"Configurar la API" "Conecte el componente JobListings a la tabla cr_jobposting Dataverse. Reemplace la matriz codificada por una llamada API real que obtenga el título, el departamento, el salario y la fecha de publicación.

Uso de capturas de pantalla para problemas visuales

Cuando el sitio no se ve bien en el explorador, realice una captura de pantalla y péguela directamente en la conversación o proporcione una ruta de acceso de archivo. El contexto visual ayuda a identificar problemas de diseño, espaciado y estilo difíciles de describir en el texto.

The header overlaps the hero section on mobile. Here's a screenshot:

[paste screenshot or provide path to screenshot file]

Fix the header so it doesn't overlap. It should be a fixed header with the content starting below it.

Itera en pasos pequeños

En lugar de describir todo un sitio en una sola instrucción, construya de manera incremental. Comience con la estructura y el diseño y agregue características de una en una. Este enfoque le ofrece la oportunidad de revisar y corregir el curso en cada paso.

Step 1: /create-site → Get the basic scaffold and layout right
Step 2: "Add a hero section to the home page with a search bar"
Step 3: "Add a job listings page with filter and sort"
Step 4: "Add a job detail page that shows full description"
Step 5: /setup-datamodel → Create tables now that you know the data shape
Step 6: /integrate-webapi → Wire up real data

Sugerencia

Después de cada paso, compruebe la vista previa del explorador. Si algo no es correcto, corrijalo antes de continuar. Es más fácil corregir problemas en un componente que desenredar problemas en todo un sitio.

Pedir una explicación antes de aprobar

Cuando no esté seguro de un cambio propuesto, especialmente en lo que respecta a permisos, modificaciones del modelo de datos o configuración de autenticación, pida al complemento que explique lo que planea hacer y por qué antes de aprobarlo.

Before you create the table permissions, explain what access each role will have and why. I want to understand the security implications.

Ejecutar habilidades de forma independiente para recuperarse de problemas

Si una habilidad falla a mitad de camino, no es necesario empezar de nuevo. Cada habilidad se ejecuta de forma independiente y puede continuar desde donde se quedó. Por ejemplo, si /integrate-webapi falla en la tercera tabla, puede volver a ejecutarlo y reconoce el trabajo ya completado.

/integrate-webapi failed while processing the cr_applications table. Here's the error: [paste error]. Resume the integration from where it stopped.

Contenido relacionado

  • Last updated on