Erstellen eines neuen Fabric-Elements

Dieses umfassende Handbuch zeigt Ihnen, wie Sie benutzerdefinierte Elemente in Microsoft Fabric mithilfe des Extensibility Toolkits erstellen. Sie können zwischen zwei Ansätzen wählen, die auf Ihrer Einstellungs- und Erfahrungsebene basieren.

Voraussetzungen

Stellen Sie vor dem Erstellen eines benutzerdefinierten Elements folgendes sicher:

• ✅ Die Setup-Anleitung abgeschlossen und über eine funktionierende Entwicklungsumgebung verfügen.
• ✅ Ihre Workload wird lokal ausgeführt und kann in Fabric zugänglich sein
• ✅ Vertrautheit mit TypeScript und React (zur Anpassung)

Wählen Sie Ihren Ansatz aus

🤖 KI-unterstützte Methode (empfohlen für Einsteiger)

Verwenden Sie GitHub Copilot, um Sie interaktiv durch den gesamten Prozess zu führen. Perfekt für:

• Entwickler, die neu im Umgang mit dem Fabric Extensibility Toolkit sind
• Lernen der Plattformmuster und bewährten Methoden
• Erhalten von Erklärungen und Anleitungen während der Arbeit

🛠️ Manueller, skriptbasierter Ansatz (empfohlen für erfahrene Entwickler)

Verwenden Sie das automatisierte PowerShell-Skript für die schnelle Einrichtung. Perfekt für:

• Entwickler, die mit der Toolkitstruktur vertraut sind
• Effizientes Erstellen mehrerer Elemente
• Produktionsworkflows und Automatisierung

🤖 AI-gestützte Objekterstellung

Erste Schritte mit GitHub Copilot

GitHub Copilot kann Sie durch das Erstellen eines vollständigen benutzerdefinierten Fabric-Elements nach allen bewährten Methoden führen. Die KI versteht die Extensibility Toolkit-Muster und hilft Ihnen dabei, sie richtig zu implementieren.

Beispielaufforderungen, die funktionieren

Hier sind bewährte Eingabeaufforderungen, mit denen Sie mit der Erstellung von Elementen beginnen:

Grundlegende Elementerstellung:

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

Spezifische Anforderungen:

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

Komplexes Element mit OneLake-Integration:

@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

Typischer AI-Assisted-Prozess

Der KI-unterstützte Ansatz folgt diesem iterativen Muster:

1. Erste Planungsphase

• KI analysiert Ihre Anforderungen
• Schlägt Elementstruktur und -komponenten vor
• Erstellt einen Entwicklungsplan mit Todos

2. Komponentengenerierung

• Erstellt das 4-Datei-Muster (Definition, Editor, Leer, Ribbon-Menü)
• Implementiert die richtigen TypeScript-Schnittstellen
• Einrichten von Fluent UI-Komponenten

3. Featureimplementierung

• Fügt Ihre spezifische Funktionalität hinzu.
• Integriert sich mit Fabric-APIs
• Implementiert die richtige Fehlerbehandlung.

4. Tests und Verfeinerung

• Testet das Element in Ihrer Entwicklungsumgebung.
• Behebt alle gefundenen Probleme.
• Optimiert die Leistung und Benutzererfahrung.

Arbeiten mit dem KI-Assistenten

Beginnen Sie mit klaren Anforderungen:

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].

Iterieren und Verfeinern:

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?

Fragen Sie nach Erklärungen:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Bewährte Methoden für die KI-Zusammenarbeit

• Seien Sie spezifisch: Bereitstellen klarer Anforderungen und Kontext
• Überprüfen Sie jeden Schritt: Verstehen des generierten Codes, bevor Sie fortfahren
• Fragen stellen: Fordern Sie Erklärungen für Muster an, die Sie nicht verstehen
• Häufig testen: Ausführen und Testen des Elements nach jeder wichtigen Änderung
• Nachverfolgung: Bitte um Verfeinerungen und Verbesserungen

KI-Entwicklungstools und -umgebung

Dieses Repository arbeitet außergewöhnlich gut mit KI-Paarprogrammierungswerkzeugen. Unabhängig davon, ob Sie lokal oder in GitHub Codespaces entwickeln, können Sie GitHub Copilot oder andere KI-Assistenten verwenden, um Aufgaben wie das Bearbeiten von React-Komponenten, das Aktualisieren von Routen oder das Generieren von Testgerüsten zu beschleunigen.

Spezifische KI-Unterstützungsbereiche:

• Verwenden Sie KI zum Entwerfen von Element-Editor-/Anzeigekomponenten und passen Sie diese dann an die Host-API-Muster an, die im Starter-Kit verwendet werden.
• Künstliche Intelligenz bitten, das Workload-Manifest zusammenzufassen und minimale Berechtigungen vorzuschlagen
• In Codespaces ist Copilot im Browser oder VS Code-Desktop verfügbar; Lassen Sie den Entwicklungsserver laufen, um sofort Änderungen anzuzeigen.

Schnelle Iteration und Debugging

Das Erweiterbarkeitsframework wurde für eine schnelle Entwicklung entwickelt, wenn KI-Unterstützung verwendet wird:

• Wenn der Dev-Server und DevGateway ausgeführt wird, werden Codeänderungen in Ihrer App sofort angezeigt, wenn Sie das Element in Fabric öffnen.
• Sie können mithilfe der Entwicklertools Ihres Browsers debuggen, während die Workload im Fabric iFrame gehostet wird.
• Schnelles Iterieren bei der UI-, Routen- und Manifestkonfiguration sowie die Validierung des End-to-End-Verhaltens in Ihrem Fabric-Arbeitsbereich.
• KI-Tools können bei der Entwicklung in Echtzeit helfen, Probleme zu identifizieren und zu beheben.

Erwartete Zeitplanung

• Einfaches Element: 30-60 Minuten mit KI-Anleitung
• Komplexes Element: 1-3 Stunden mit mehreren Iterationen
• Erweitertes Element: Halber Tag mit umfangreicher Anpassung

🛠• Manueller scriptgesteuerter Ansatz

Verwenden des CreateNewItem.ps1-Skripts

Der manuelle Ansatz verwendet ein automatisiertes PowerShell-Skript, das die HelloWorld-Elementvorlage kopiert und für Ihr neues Element konfiguriert.

Quick Start

1. Navigieren Sie zum Skriptverzeichnis:

   cd scripts\Setup
   

2. Führen Sie das Erstellungsskript aus:

   .\CreateNewItem.ps1 -ItemName "MyCustomItem"
   

Funktionsweise des Skripts

Automatisierte Dateierstellung:

• ✅ Kopiert alle vier Kernkomponentendateien aus der HelloWorld-Vorlage.
• ✅ Benennt Dateien so um, dass sie ihrem Elementnamen entsprechen
• ✅ Aktualisiert alle internen Verweise und Importe
• ✅ Erstellt Manifestdateien (XML- und JSON-Konfigurationen)
• ✅ Kopiert und benennt Symbolressourcen um.

Generierte Dateistruktur:

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

Erforderliche manuelle Schritte

Nach dem Ausführen des Skripts müssen Sie die folgenden manuellen Konfigurationsschritte ausführen:

1. Aktualisierung von Umgebungsdateien – KRITISCH 🚨

Fügen Sie das neue Element der ITEM_NAMES Variablen in ALLEN Umgebungsdateien hinzu:

Zu aktualisierende Dateien:

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

Änderung von:

ITEM_NAMES=HelloWorld

Ändern in:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠– Ohne diesen Schritt wird Ihr Element nicht in der Workload angezeigt!

2. Aktualisieren Product.json Konfiguration

Fügen Sie Ihre Elementkonfiguration zu Workload\Manifest\Product.json hinzu:

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

3. Hinzufügen von Lokalisierungszeichenfolgen

Aktualisieren von Übersetzungsdateien in Workload\Manifest\assets\locales\:

Innerhalb von en-US.json (und anderen Spracheinstellungen):

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

4. Hinzufügen der Routingkonfiguration

Aktualisieren Sie Workload\app\App.tsx , um das Routing für Ihr neues Element einzuschließen:

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

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

Überprüfungsschritte

Nach Abschluss aller manuellen Schritte:

1. Erstellen Sie das Projekt:

   npm run build
   

2. Starten Sie den Entwicklungsserver neu:

   .\scripts\Run\StartDevServer.ps1
   

3. Testen in Fabric:

   • Navigieren Sie zu Ihrer Workload in Fabric
   • Überprüfen, ob der neue Elementtyp im Dialogfeld "Erstellen" angezeigt wird
   • Erstellen sie eine Instanz, und überprüfen Sie, ob sie ordnungsgemäß geladen wird.

Bewährte Methoden und Richtlinien

Warum helloWorld nicht umbenennen?

Das HelloWorld-Element dient als Referenzvorlage , die regelmäßige Updates von Microsoft empfängt. Wichtige Gründe für die unveränderte Aufbewahrung:

• Updates und Verbesserungen: Microsoft aktualisiert HelloWorld regelmäßig mit neuen Features, Fehlerbehebungen und bewährten Methoden.
• Integrationstests: HelloWorld stellt sicher, dass Ihre Umgebung ordnungsgemäß funktioniert
• Referenzdokumentation: Sie dient als Livedokumentation für Implementierungsmuster
• Abwärtskompatibilität: Updates behalten die Kompatibilität mit vorhandenen Anpassungen bei

Empfohlener Workflow

1. HelloWorld unberührt lassen: Verwenden Sie es als Referenz- und Testelement.
2. Neue Elemente erstellen: Verwenden des Skripts oder der KI-Unterstützung zum Erstellen separater Elemente
3. Regelmäßige Updates: Updates regelmäßig aus dem Basis-Repository abrufen
4. Zusammenführungsmuster: Anwenden neuer Muster von dem aktualisierten HelloWorld auf Ihre benutzerdefinierten Elemente

Bewährte Methoden für die Elemententwicklung

Komponentenarchitektur:

• ✅ Folgen Sie dem Muster mit vier Komponenten (Definition, Editor, Leer, Menüband)
• ✅ Verwenden des ItemEditor-Containers für konsistentes Layout und Verhalten
• ✅ Implementierung einer ordnungsgemäßen Ladezustandsanzeige und Fehlerbehandlung
• ✅ Befolgen der Fluent UI-Entwurfsmuster

Datenmanagement:

• ✅ Verwenden saveWorkloadItem() für Elemente mit komplexen Daten
• ✅Verwenden Sie getWorkloadItem() für das Laden mit Fallback-Standardeinstellungen
• ✅ Implementieren der richtigen TypeScript-Schnittstellen in der Definitionsdatei
• ✅ Nicht definierte/leere Zustände ordnungsgemäß behandeln

Benutzererfahrung:

• ✅ Bieten Sie klare Leerzustände für Erstanwender
• ✅ Verwenden Sie die richtigen Ladeindikatoren
• ✅ Hilfreiche Fehlermeldungen implementieren
• ✅ Befolgen Sie die Fabric-Entwurfsmuster und die Richtlinien für Barrierefreiheit

Überlegungen zur Leistung

• Lazy Loading: Nur Bei Bedarf Daten laden
• Effiziente Updates: Verwenden von React-Mustern zur Minimierung von Neurenderungen
• OneLake-Integration: Verwenden Sie createItemWrapper(), um den Anwendungsbereich korrekt festzulegen.
• Fehlergrenzen: Implementieren der richtigen Fehlerbehandlung während des gesamten Verlaufs

Nächste Schritte

Nachdem Ihr Element erstellt wurde:

1. Anpassen des Datenmodells: Aktualisieren der Definitionsdatei mit ihren spezifischen Schnittstellen
2. Implementieren von Kernfeatures: Erstellen der Hauptfunktionalität in der Editorkomponente
3. Design Leerer Zustand: Erstellen eines ansprechenden ersten Nutzererlebnisses
4. Konfigurieren von Aktionen: Einrichten geeigneter Menübandaktionen für Ihren Workflow
5. Gründlich testen: Überprüfen aller Funktionen in Ihrer Entwicklungsumgebung
6. Vorbereiten der Produktion: Befolgen Sie den Veröffentlichungsleitfaden , wenn Sie fertig sind.

Problembehandlung

Das Element wird nicht in Arbeitsauslastung angezeigt:

• ✅, Überprüfen Sie ITEM_NAMES in allen .env-Dateien
• ✅ Überprüfen Sie die Product.json-Konfiguration
• ✅ Neustarten des Entwicklungsservers

Buildfehler:

• ✅ Überprüfen von TypeScript-Schnittstellen in der Definitionsdatei
• ✅ Überprüfen, ob alle Importe korrekt sind
• ✅ Sicherstellen, dass Routing ordnungsgemäß konfiguriert ist

Laufzeitfehler:

• ✅ Überprüfen der Browserkonsole auf detaillierte Fehlermeldungen
• ✅ Überprüfen der API-Integration und -Authentifizierung
• ✅ Testen mit vereinfachten Daten zuerst

Zusätzliche Ressourcen

• Dokumentation zu ItemEditor-Steuerelementen
• OneLake-Integrationshandbuch
• Fabric-API-Verwendung
• Veröffentlichungsanforderungen

Glückliches Programmieren! 🚀