Guía de configuración detallada

Una vez que tenga acceso al código (ya sea en Codespaces o localmente) siguiendo la guía De introducción, siga estos pasos:

Paso 1: Ejecutar el script de instalación

El script de instalación automatiza la mayoría de la configuración (registro de aplicaciones, valores predeterminados, etc.).

# From the repo root
pwsh ./scripts/Setup/Setup.ps1 -WorkloadName "Org.MyWorkload"

Notas del script de instalación:

• WorkloadName debe seguir el patrón Organization.WorkloadName. Para el desarrollo, use Org.[YourWorkloadName].
• Si reutiliza una aplicación existente de Microsoft Entra, asegúrese de que los URI de redirección de SPA están configurados como se describe en la guía de configuración manual de repositorios.
• En macOS/Linux, use pwsh para ejecutar scripts.
• Asegúrese de que la directiva de ejecución de PowerShell esté establecida en Sin restricciones y que los archivos se desbloqueen si se le pregunta si se deben iniciar los archivos de PowerShell.
• Siga las instrucciones que proporciona el Script para configurar todo.

El script de instalación se puede ejecutar varias veces. Si los valores ya están presentes, se le preguntará si deben sobrescribirse. Si desea sobrescribir todo, use el parámetro Force.

Paso 2: Iniciar el entorno de desarrollo

Ejecute el servidor de desarrollo (front-end + API) y registre la instancia local con Fabric mediante DevGateway.

# Terminal 1: start local dev server
pwsh ./scripts/Run/StartDevServer.ps1

# Terminal 2: start DevGateway to register your local instance with Fabric
pwsh ./scripts/Run/StartDevGateway.ps1

Paso 3: Habilitación de las características de desarrollador en Fabric

Vaya al portal de Fabric y configure las opciones necesarias:

3.1 Configuración de las opciones de inquilino en el Portal de administración:

Vaya a la configuración del Portal de administración y habilite las siguientes configuraciones del tenant:

• Los administradores y colaboradores de capacidad pueden agregar y quitar cargas de trabajo adicionales
• Los administradores del área de trabajo pueden desarrollar cargas de trabajo de asociados
• Los usuarios pueden ver y trabajar con cargas de trabajo adicionales no validadas por Microsoft

3.2 Activar el modo de desarrollador de Fabric:

Vaya a La configuración del desarrollador de Fabric y habilite el modo de desarrollador de Fabric:

Ya está listo para crear su primer elemento Hello World en Fabric.

Paso 4: Probar el elemento HelloWorld

Puede acceder a la carga de trabajo desde el Hub de Cargas de Trabajo (busque el nombre de la carga de trabajo) o navegue directamente. A continuación, cree un elemento Hola Mundo.

Steps:

1. Open Fabric Workload Hub: busque la carga de trabajo (por ejemplo, Org.MyWorkload).

   • Navegación directa: https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
   • Reemplace <WORKLOAD_NAME> por el nombre real de la carga de trabajo (por ejemplo, Org.MyWorkload)

2. Crear un nuevo elemento: seleccione el tipo de elemento Hola mundo y elija el área de trabajo de desarrollo.

3. Comprobar la funcionalidad: se abre el editor; confirme que el elemento funciona según lo esperado y aparece como un artefacto nativo en el área de trabajo.

¡Felicidades! Has creado tu primer elemento desde tu entorno de desarrollo.

Paso 5: Iniciar la codificación

Ahora que está configurado, puede empezar a crear sus propios elementos personalizados. Siga nuestra guía completa para aprender a crear elementos de Fabric personalizados:

📖 Guía de creación de elementos de tejido personalizado : esta guía proporciona dos enfoques para crear elementos:

• Enfoque asistido por IA: Use GitHub Copilot para obtener orientación interactiva (recomendado para nuevos desarrolladores)
• Enfoque manual con scripts: uso de scripts automatizados de PowerShell para la configuración rápida (recomendado para desarrolladores experimentados)

Opciones de inicio rápido:

• Actualice el editor HelloWorld existente: Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
• Cree un nuevo elemento con el script: ./scripts/Setup/CreateNewItem.ps1

¡Feliz codificación! 🚀

procedimientos recomendados

• Bifurque el repositorio: Haga un fork del repositorio Starter-Kit y use este fork como base de su proyecto.
• Manténgase sincronizado: mantenga la bifurcación sincronizada con la cadena ascendente para recoger mejoras.
• Mantener la coherencia de la estructura del proyecto: conserve la estructura del proyecto y los patrones de organización de Starter-Kit para garantizar la compatibilidad con las actualizaciones futuras y mantener la claridad del código.
• Integración de Starter-Kit normal: integre periódicamente los cambios de código del Starter-Kit en el proyecto para beneficiarse de correcciones de errores, nuevas características y actualizaciones de seguridad. Configure un proceso para revisar y combinar los cambios ascendentes de forma periódica (mensual o trimestral).
• Validar los manifiestos anticipadamente: valide de forma anticipada el manifiesto de carga de trabajo y siga los permisos con privilegios mínimos.
• Usar contenedores de desarrollo: use un contenedor de desarrollo o Codespaces para un entorno coherente y descartable.
• Usar scripts proporcionados: use los scripts proporcionados (Setup, StartDevServer, StartDevGateway) para automatizar la configuración y el flujo de trabajo diario.

Solución de problemas habituales

Error de instalación de PowerShell

Si se produce un error durante la ejecución del script de instalación, asegúrese de que tiene instalado y configurado powerShell más reciente en el entorno que ejecuta el script.

Error de directiva de ejecución de scripts

Si encuentra: : cannot be loaded because the execution policy is unrestricted

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

El puerto 5173 está en uso

Si el DevServer no se puede iniciar en el puerto 5173, localice y termine el proceso.

# Find process using port
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

# Terminate process
Stop-Process -Id <ProcessId> -Force

Errores de dependencias

Si encuentra errores sobre las dependencias que faltan:

# From Workload folder
cd Workload
npm install

Problemas de autenticación de DevGateway

Si se produce un error en la autenticación al iniciar DevGateway:

1. Verifica los URI de redirección del registro de aplicaciones en Microsoft Entra
2. Compruebe que la configuración del inquilino permita las características de desarrollador necesarias.
3. Asegúrese de que ha iniciado sesión en el inquilino correcto en DevGateway.

Para obtener información completa sobre la solución de problemas, consulte el README del repositorio de Starter-Kit.

Notas importantes

Nuevas restricciones de acceso a la red local de Chrome

Google ha introducido nuevas restricciones de acceso a redes locales (LNA) en Chrome que interrumpirán el desarrollo local con devServer. Estas restricciones impiden que los sitios web accedan a recursos de red local sin permiso explícito de usuario.

Acción necesaria para el desarrollo local: debe cambiar la configuración de Chrome para continuar desarrollando cargas de trabajo localmente:

1. Vaya a chrome://flags/#local-network-access-check en Chrome.
2. Establezca el indicador en "Deshabilitado"
3. Reiniciar Chrome

Por qué esto es necesario: las nuevas restricciones bloquean la comunicación entre la carga de trabajo que se ejecuta en Fabric y el servidor de DevGateway local, que es esencial para el flujo de trabajo de desarrollo.

Recursos adicionales:

• Acceso de red local: desarrolladores de Chrome : documentación oficial de Chrome en cambios de acceso a redes locales

Pasos siguientes

• Obtenga información sobre la arquitectura y cómo interactúa el host, la aplicación y los servicios de Fabric
• Lea la Información general del manifiesto para conocer el esquema y las mejores prácticas.
• Descripción de la estructura y configuración del manifiesto de carga de trabajo
• Desarrollo con DevGateway para pruebas locales
• Publica tu carga de trabajo cuando estés listo para compartirla ampliamente