Partager via

Créer un nouvel élément de Fabric

Ce guide complet vous montre comment créer des éléments personnalisés dans Microsoft Fabric à l’aide du Kit de ressources d’extensibilité. Vous pouvez choisir entre deux approches en fonction de votre préférence et de votre niveau d’expérience.

Prerequisites

Avant de créer un élément personnalisé, vérifiez que vous disposez des éléments suivants :

  • ✅ Terminer le Guide d'installation et disposer d'un environnement de développement fonctionnel
  • ✅ Votre charge de travail s’exécute localement et est accessible dans Fabric.
  • ✅ Familiarité avec TypeScript et React (pour la personnalisation)

Choisir votre approche

🤖 approche AI-Assisted (recommandée pour les nouveaux développeurs)

Utilisez GitHub Copilot pour vous guider tout au long du processus de manière interactive. Parfait pour :

  • Développeurs nouveaux dans l'utilisation du Fabric Extensibility Toolkit
  • Apprentissage des modèles de plateforme et des meilleures pratiques
  • Obtenir des explications et des conseils au fur et à mesure que vous travaillez

🛠️ Approche scriptée manuelle (recommandée pour les développeurs expérimentés)

Utilisez le script PowerShell automatisé pour la configuration rapide. Parfait pour :

  • Développeurs familiarisés avec la structure du kit de ressources
  • Création efficace de plusieurs éléments
  • Flux de travail de production et automatisation

🤖 Création d'Éléments Assistée par l'IA

Prise en main de GitHub Copilot

GitHub Copilot peut vous guider tout au long de la création d’un élément Fabric personnalisé complet en suivant toutes les bonnes pratiques. L’IA comprend les modèles du Kit de ressources d’extensibilité et vous aidera à les implémenter correctement.

Exemples d’invites qui fonctionnent

Voici des invites éprouvées qui vous permettront de commencer à créer des éléments :

Création d’éléments de base :

@fabric create a new item called MyDataReport that shows data analysis reports

Exigences spécifiques :

@fabric create a custom item for managing data pipelines with these features:
- Pipeline configuration interface
- Status monitoring dashboard  
- Error handling and retry logic

Élément complexe avec intégration oneLake :

@fabric create an item called DataExplorer that:
- Browses OneLake files in the left panel
- Shows file preview in the center
- Saves user preferences and settings

Processus standard assisté par IA

L’approche assistée par l’IA suit ce modèle itératif :

1. Phase de planification initiale

  • L’IA analyse vos besoins
  • Suggère la structure des éléments et les composants
  • Crée un plan de développement avec des todos

2. Génération de composants

  • Crée le modèle de 4 fichiers (Définition, Éditeur, Vide, Ruban)
  • Implémente des interfaces TypeScript appropriées
  • Configurer des composants Fluent UI

3. Implémentation des fonctionnalités

  • Ajoute vos fonctionnalités spécifiques
  • S’intègre aux API Fabric
  • Implémente une gestion des erreurs appropriée

4. Test et affinement

  • Teste l’élément dans votre environnement de développement
  • Corrige les problèmes détectés
  • Optimise les performances et l’expérience utilisateur

Utilisation de l’Assistant IA

Commencez par les exigences claires :

I want to create a [ItemType] item that [primary purpose]. 
The item should have [list key features].
Users should be able to [list main actions].

Itérer et affiner :

The item looks good, but I need to add [specific feature]

How can I integrate this with OneLake storage?

Can you add error handling for when the API is unavailable?

Demandez des explications :

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Meilleures pratiques pour la collaboration IA

  • Être spécifique : fournir des exigences et un contexte clairs
  • Passer en revue chaque étape : comprendre le code généré avant de continuer
  • Poser des questions : Demander des explications pour les modèles que vous ne comprenez pas
  • Tester fréquemment : Exécuter et tester l’élément après chaque modification majeure
  • Suivi : Demander des affinements et des améliorations

Outils et environnement de développement IA

Ce référentiel fonctionne exceptionnellement bien avec les outils de programmation de paire IA. Que vous développez localement ou dans GitHub Codespaces, vous pouvez utiliser GitHub Copilot ou d’autres assistants IA pour accélérer les tâches telles que la modification des composants React, la mise à jour des itinéraires ou la génération d’une structure de test.

Conseil / Astuce

Le dépôt Starter-Kit est compatible avec l’IA et inclut des instructions GitHub Copilot qui vous guident tout au long de l’adaptation de l’élément Hello World à vos besoins. D’autres outils IA (par exemple, Anthropic Claude) peuvent suivre les mêmes instructions, mais doivent être configurés pour lire les fichiers d’aide ou les documents du référentiel.

Domaines d’assistance d’IA spécifiques :

  • Utilisez l’IA pour rédiger les composants de l’éditeur/vue d’élément, puis s’adapter aux modèles d’API hôtes utilisés dans le Starter-Kit
  • Demander à l’IA de résumer le manifeste de charge de travail et de proposer des ensembles d’autorisations minimal
  • Dans Codespaces, Copilot est disponible dans le navigateur ou le bureau VS Code ; maintenir le serveur de développement en cours d’exécution pour voir les modifications instantanément

Conseil / Astuce

Si vous souhaitez voir ce que les autres créent, ouvrez les exemples d’extensibilité et déployez-le dans votre environnement. Vous y trouverez des types d’éléments variés qui vous aideront à commencer.

Itération rapide et débogage

Le framework d’extensibilité est conçu pour un développement rapide lors de l’utilisation de l’assistance IA :

  • Avec le serveur de développement et DevGateway en cours d’exécution, les modifications de code dans votre application sont reflétées immédiatement lorsque vous ouvrez votre élément dans Fabric
  • Vous pouvez déboguer à l’aide des outils de développement de votre navigateur pendant que la charge de travail est hébergée dans l’iFrame Fabric
  • Itérer rapidement sur l’interface utilisateur, les itinéraires et la configuration du manifeste et valider le comportement de bout en bout dans votre espace de travail Fabric
  • Les outils IA peuvent aider à identifier et à résoudre les problèmes en temps réel à mesure que vous développez

Chronologie attendue

  • Élément simple : 30 à 60 minutes avec des conseils sur l’IA
  • Élément complexe : 1 à 3 heures avec plusieurs itérations
  • Élément avancé : Demi-journée avec une personnalisation étendue

🛠️ Approche scriptée manuelle

Utilisation du script CreateNewItem.ps1

L’approche manuelle utilise un script PowerShell automatisé qui copie le modèle d’élément HelloWorld et le configure pour votre nouvel élément.

Quick Start

  1. Accédez au répertoire de script :

    cd scripts\Setup

  2. Exécutez le script de création :

    .\CreateNewItem.ps1 -ItemName "MyCustomItem"

Ce que fait le script

Création de fichiers automatisée :

  • ✅ Copie tous les 4 fichiers de composants principaux à partir du modèle HelloWorld
  • ✅ Renomme les fichiers pour qu’ils correspondent à votre nom d’élément
  • ✅ Met à jour toutes les références et importations internes
  • ✅ Crée des fichiers manifestes (configurations XML et JSON)
  • ✅ Copie et renomme les ressources d’icône

Structure de fichiers générée :

Workload/app/items/MyCustomItemItem/
├── MyCustomItemDefinition.ts         # Data model and interfaces
├── MyCustomItemEditor.tsx            # Main editor component
├── MyCustomItemEditorEmpty.tsx       # First-time user experience
├── MyCustomItemEditorRibbon.tsx      # Action buttons and toolbar
└── MyCustomItem.scss                 # Styling

Workload/Manifest/items/MyCustomItem/
├── MyCustomItemItem.xml              # Item type definition
└── MyCustomItemItem.json             # Item configuration

Workload/Manifest/assets/images/
└── MyCustomItemItem-icon.png         # Item icon

Étapes manuelles requises

Après avoir exécuté le script, vous devez effectuer ces étapes de configuration manuelles :

1. Mettre à jour les fichiers 🚨 d’environnement CRITIQUES

Ajoutez votre nouvel élément à la ITEM_NAMES variable dans tous les fichiers d’environnement :

Fichiers à mettre à jour :

  • Workload\.env.dev
  • Workload\.env.test
  • Workload\.env.prod

Changez de :

ITEM_NAMES=HelloWorld

Passez à :

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ Sans cette étape, votre élément n’apparaît pas dans la charge de travail !

2. Mettre à jour la configuration Product.json

Ajoutez la configuration de votre élément à Workload\Manifest\Product.json:

{
  "items": [
    {
      "name": "HelloWorldItem",
      // ... existing config
    },
    {
      "name": "MyCustomItemItem",
      "displayName": "My Custom Item",
      "description": "Description of what your item does",
      "contentType": "MyCustomItem",
      "configurationSections": []
    }
  ]
}

3. Ajouter des chaînes de localisation

Mettre à jour les fichiers de traduction dans Workload\Manifest\assets\locales\:

Dans en-US.json (et d’autres fichiers régionaux) :

{
  "MyCustomItemItem": {
    "displayName": "My Custom Item",
    "description": "Description of your custom item"
  }
}

4. Ajouter une configuration de routage

Mettez à jour Workload\app\App.tsx pour inclure le routage de votre nouvel élément :

// Add import
import { MyCustomItemEditor } from "./items/MyCustomItemItem/MyCustomItemEditor";

// Add route in the Routes section
<Route path="/MyCustomItemItem-editor" element={<MyCustomItemEditor {...props} />} />

Étapes de vérification

Après avoir effectué toutes les étapes manuelles :

  1. Générez le projet :

    npm run build

  2. Redémarrez le serveur de développement :

    .\scripts\Run\StartDevServer.ps1

  3. Test dans Fabric :

    • Accédez à votre charge de travail dans Fabric
    • Vérifier que votre nouveau type d’élément apparaît dans la boîte de dialogue de création
    • Créer une instance et vérifier qu’elle se charge correctement

Bonnes pratiques et recommandations

Pourquoi ne pas renommer HelloWorld ?

L’élément HelloWorld sert de modèle de référence qui reçoit des mises à jour régulières de Microsoft. Principales raisons de la conserver inchangée :

  • Mises à jour et améliorations : Microsoft met régulièrement à jour HelloWorld avec de nouvelles fonctionnalités, des correctifs de bogues et des meilleures pratiques
  • Test d’intégration : HelloWorld garantit que votre environnement fonctionne correctement
  • Documentation de référence : elle sert de documentation dynamique pour les modèles d’implémentation
  • Compatibilité descendante : les mises à jour maintiennent la compatibilité avec les personnalisations existantes
  1. Conserver HelloWorld non touché : utilisez-le comme référence et élément de test
  2. Créer des éléments : utiliser le script ou l’assistance IA pour créer des éléments distincts
  3. Mises à jour régulières : extrayez régulièrement des mises à jour à partir du référentiel de base
  4. Modèles de fusion : appliquer de nouveaux modèles de HelloWorld mis à jour à vos éléments personnalisés

Meilleures pratiques en matière de développement d’éléments

Architecture des composants :

  • ✅ Suivez le modèle 4 composants (Définition, Éditeur, Vide, Ruban)
  • ✅ Utiliser le conteneur ItemEditor pour une disposition et un comportement cohérents
  • ✅ Implémenter les états de chargement appropriés et la gestion des erreurs
  • ✅ Suivez les modèles de conception Fluent UI

Gestion des données :

  • ✅ Utiliser saveWorkloadItem() pour les éléments avec des données complexes
  • ✅ Utilisez getWorkloadItem() pour le chargement avec les paramètres par défaut alternatifs
  • ✅ Implémenter des interfaces TypeScript appropriées dans le fichier définition
  • ✅ Gérer correctement les états non définis/vides

Expérience utilisateur :

  • ✅ Fournir des états vides clairs pour les utilisateurs à la première fois
  • ✅ Utiliser des indicateurs de chargement appropriés
  • ✅ Implémenter des messages d’erreur utiles
  • ✅ Suivez les modèles de conception Fabric et les instructions d’accessibilité

Considérations relatives aux performances

  • Chargement différé : chargez uniquement les données si nécessaire
  • Mises à jour efficaces : utiliser des modèles React pour réduire les réexécritures
  • Intégration de OneLake : Utilisez createItemWrapper() pour une portée correcte
  • Limites d’erreur : Implémenter une gestion des erreurs appropriée dans l’ensemble

Étapes suivantes

Une fois votre élément créé :

  1. Personnaliser le modèle de données : mettre à jour le fichier de définition avec vos interfaces spécifiques
  2. Implémenter les fonctionnalités principales : générer la fonctionnalité principale dans le composant Éditeur
  3. Concevoir un état vide : créer une expérience utilisateur attrayante pour la première fois
  4. Configurer des actions : configurer les actions de ruban appropriées pour votre flux de travail
  5. Tester soigneusement : vérifier toutes les fonctionnalités de votre environnement de développement
  6. Préparer la production : suivez le guide de publication lorsque vous êtes prêt

Résolution des problèmes

L’élément n’apparaît pas dans la charge de travail :

  • ✅ Vérifier ITEM_NAMES dans tous les fichiers .env
  • ✅ Vérifier la configuration de Product.json
  • ✅ Redémarrer le serveur de développement

Erreurs de build :

  • ✅ Vérifier les interfaces TypeScript dans le fichier définition
  • ✅ Vérifier que toutes les importations sont correctes
  • ✅ Vérifier que le routage est correctement configuré

Erreurs d’exécution :

  • ✅ Vérifier la console du navigateur pour obtenir des messages d’erreur détaillés
  • ✅ Vérifier l’intégration et l’authentification de l’API
  • ✅ Tester d’abord avec des données simplifiées

Ressources additionnelles

Bon codage ! 🚀

  • Last updated on