Guide d’installation détaillé

Une fois que vous avez accès au code (dans Codespaces ou localement) en suivant le guide de prise en main, procédez comme suit :

Étape 1 : Exécuter le script d’installation

Le script d’installation automatise la plupart des configurations (inscription d’application, valeurs par défaut, etc.).

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

Notes de script d’installation :

• WorkloadName doit suivre le modèle Organization.WorkloadName. Pour le développement, utilisez Org.[YourWorkloadName].
• Si vous réutilisez une application Microsoft Entra existante, vérifiez que les URI de redirection SPA sont configurés comme décrit dans le guide de configuration manuelle des référentiels.
• Sur macOS/Linux, utilisez-le pwsh pour exécuter des scripts.
• Assurez-vous que la stratégie d’exécution de PowerShell est définie sur Non restreint et que les fichiers sont débloqués si vous êtes invité à indiquer si les fichiers PowerShell doivent être démarrés.
• Suivez les instructions fournies par le script pour tout configurer.

Le script d’installation peut être exécuté plusieurs fois. Si des valeurs sont déjà présentes, vous êtes invité à les remplacer. Si vous souhaitez remplacer tout, utilisez le paramètre Force.

Étape 2 : Démarrer l’environnement de développement

Exécutez le serveur de développement (front-end + API) et inscrivez votre instance locale auprès de Fabric via 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

Étape 3 : Activer les fonctionnalités du développeur dans Fabric

Accédez au portail Fabric et configurez les paramètres requis :

3.1 Configurer les paramètres du locataire dans le portail d’administration :

Accédez aux paramètres du portail d’administration et activez les paramètres de locataire suivants :

• Les administrateurs de capacité et les contributeurs peuvent ajouter et supprimer des charges de travail supplémentaires
• Les administrateurs d’espace de travail peuvent développer des charges de travail partenaires
• Les utilisateurs peuvent voir et utiliser des charges de travail supplémentaires non validées par Microsoft

3.2 Activer le mode développeur Fabric :

Accédez aux paramètres du développeur Fabric et activez le mode développeur Fabric :

Vous êtes maintenant prêt à créer votre premier élément Hello World dans Fabric.

Étape 4 : Tester l’élément HelloWorld

Vous pouvez accéder à la charge de travail à partir du hub de charge de travail (recherchez le nom de votre charge de travail) ou naviguer directement. Créez ensuite un élément Hello World.

Étapes :

1. Open Fabric Workload Hub : recherchez votre charge de travail (par exemple). Org.MyWorkload

   • Navigation directe : https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
   • Remplacez <WORKLOAD_NAME> par le nom de votre charge de travail réelle (par exemple, Org.MyWorkload)

2. Créez un élément : sélectionnez le type d’élément Hello World et choisissez votre espace de travail de développement.

3. Vérifier la fonctionnalité : l’éditeur s’ouvre ; vérifiez que l’élément fonctionne comme prévu et apparaît comme un artefact natif dans l’espace de travail.

Félicitations! Vous avez créé votre premier élément à partir de votre environnement de développement.

Étape 5 : Démarrer le codage

Maintenant que vous êtes tous configurés, vous pouvez commencer à créer vos propres éléments personnalisés. Suivez notre guide complet pour découvrir comment créer des éléments Fabric personnalisés :

📖 Guide de création d’éléments en tissu personnalisés - ce guide fournit deux approches pour la création d’éléments :

• Approche assistée par l'IA : Utiliser GitHub Copilot pour obtenir des conseils interactifs (recommandé pour les nouveaux développeurs)
• Approche de script manuel : utiliser des scripts PowerShell automatisés pour la configuration rapide (recommandé pour les développeurs expérimentés)

Options de démarrage rapide :

• Mettez à jour l’éditeur HelloWorld existant : Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
• Vous pouvez également créer la structure d’un nouvel élément avec le script : ./scripts/Setup/CreateNewItem.ps1

Bon codage ! 🚀

Meilleures pratiques

• Cloner le dépôt : Clonez le dépôt Starter-Kit et utilisez votre copie comme base de votre projet.
• Restez synchronisé : maintenez votre fork synchronisé avec l’amont pour récupérer des améliorations.
• Maintenir la cohérence de la structure du projet : conservez la structure de projet et les modèles d’organisation du Starter-Kit pour garantir la compatibilité avec les futures mises à jour et maintenir la clarté du code.
• Intégration régulière Starter-Kit : intégrez régulièrement des modifications de code du Starter-Kit dans votre projet pour tirer parti des correctifs de bogues, des nouvelles fonctionnalités et des mises à jour de sécurité. Configurez un processus pour examiner et fusionner régulièrement les modifications en amont (mensuelles ou trimestrielles).
• Valider les manifestes au début : Validez votre manifeste de travail tôt et suivez les autorisations de moindre privilège.
• Utilisez des conteneurs de développement : utilisez un conteneur de développement ou des espaces de code pour un environnement cohérent et jetable.
• Utilisez des scripts fournis : utilisez les scripts fournis (setup, StartDevServer, StartDevGateway) pour automatiser l’installation et le flux de travail quotidien.

Résolution des problèmes courants

Erreur d’installation de PowerShell

Si vous rencontrez une erreur lors de l’exécution du script d’installation, vérifiez que vous disposez de la dernière version de PowerShell installée et configurée dans l’environnement que vous exécutez le script.

Erreur de stratégie d’exécution de script

Si vous rencontrez : cannot be loaded because the execution policy is unrestricted :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Le port 5173 est utilisé

Si DevServer ne peut pas démarrer sur le port 5173, recherchez et arrêtez le processus :

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

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

Erreurs de dépendances

Si vous rencontrez des erreurs concernant les dépendances manquantes :

# From Workload folder
cd Workload
npm install

Problèmes d’authentification DevGateway

Si l’authentification échoue lors du démarrage de DevGateway :

1. Vérifiez les URI de redirection de l'inscription des applications dans Microsoft Entra
2. Vérifiez que les paramètres du locataire autorisent les fonctionnalités de développeur requises
3. Vérifiez que vous êtes connecté au locataire approprié dans DevGateway

Pour obtenir des informations complètes sur la résolution des problèmes, reportez-vous au fichier README du référentielStarter-Kit.

Remarques importantes

Nouvelles restrictions d’accès au réseau local Chrome

Google a introduit de nouvelles restrictions d’accès au réseau local (LNA) dans Chrome qui interrompront le développement local avec le DevServer. Ces restrictions empêchent les sites web d’accéder aux ressources de réseau local sans autorisation explicite de l’utilisateur.

Action requise pour le développement local : vous devez modifier votre configuration Chrome pour continuer à développer des charges de travail localement :

1. Accédez à chrome://flags/#local-network-access-check dans Chrome
2. Définir l’indicateur sur « Désactivé »
3. Redémarrer Chrome

Pourquoi cela est nécessaire : les nouvelles restrictions bloquent la communication entre votre charge de travail s’exécutant dans Fabric et le serveur DevGateway local, ce qui est essentiel pour le flux de travail de développement.

Ressources supplémentaires :

• Accès au réseau local - Développeurs Chrome - Documentation officielle sur les modifications apportées à l’accès au réseau local

Étapes suivantes

• Découvrez l’architecture et la façon dont l’hôte, votre application et les services Fabric interagissent
• Lire la vue d’ensemble du manifeste pour le schéma et les bonnes pratiques
• Comprendre la structure et la configuration du manifeste de charge de travail
• Développer avec DevGateway pour les tests locaux
• Publiez votre charge de travail lorsque vous êtes prêt à la partager largement