Del via

Opret et nyt Fabric Item

Denne omfattende guide viser dig, hvordan du opretter brugerdefinerede elementer i Microsoft Fabric ved hjælp af Extensibility Toolkit. Du kan vælge mellem to tilgange baseret på din præference og erfaringsniveau.

Forudsætninger

Før du laver et specialprodukt, skal du sikre dig, at du har:

  • ✅ Har gennemført Setup Guide og har et fungerende udviklingsmiljø
  • ✅ Din arbejdsbyrde kører lokalt og er tilgængelig i Fabric
  • ✅ Fortrolighed med TypeScript og React (til tilpasning)

Vælg din tilgang

🤖 AI-Assisted tilgang (Anbefales til nye udviklere)

Brug GitHub Copilot til at guide dig gennem hele processen interaktivt. Perfekt til:

  • Udviklere, der er nye til Fabric Extensibility Toolkit
  • At lære platformmønstre og bedste praksis
  • At få forklaringer og vejledning, mens du arbejder

🛠️ Manuel scriptet tilgang (Anbefales til erfarne udviklere)

Brug det automatiserede PowerShell-script til hurtig opsætning. Perfekt til:

  • Udviklere, der kender toolkit-strukturen
  • At skabe flere elementer effektivt
  • Produktionsarbejdsgange og automatisering

🤖 AI-Assisted Oprettelse af genstande

At komme i gang med GitHub Copilot

GitHub Copilot kan guide dig gennem at skabe et komplet tilpasset Fabric-produkt efter alle bedste praksisser. AI'en forstår Extensibility Toolkit-mønstrene og vil hjælpe dig med at implementere dem korrekt.

Eksempler på prompts, der virker

Her er gennemprøvede prompts, der vil hjælpe dig i gang med at lave genstande:

Grundlæggende genstandsskabelse:

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

Specifikke krav:

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

Kompleks enhed med 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

Typisk AI-Assisted proces

Den AI-assisterede tilgang følger dette iterative mønster:

1. Indledende planlægningsfase

  • AI analyserer dine behov
  • Foreslår itemstruktur og komponenter
  • Opretter en udviklingsplan med opgaver

2. Komponentgenerering

  • Opretter 4-fil-mønsteret (Definition, Editor, Tom, Bånd)
  • Implementerer korrekte TypeScript-grænseflader
  • Opsætter Fluent UI-komponenter

3. Implementering af funktioner

  • Tilføjer din specifikke funktionalitet
  • Integreres med Fabric API'er
  • Implementerer korrekt fejlhåndtering

4. Testning og forfinelse

  • Tester genstanden i dit udviklingsmiljø
  • Løser eventuelle problemer, der findes
  • Optimerer ydeevne og brugeroplevelse

Samarbejde med AI-assistenten

Start med klare krav:

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

Iterer og forfin:

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?

Bed om forklaringer:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Bedste praksis for AI-samarbejde

  • Vær specifik: Giv klare krav og kontekst
  • Gennemgå hvert trin: Forstå den genererede kode, før du går videre
  • Stil spørgsmål: Bed om forklaringer på mønstre, du ikke forstår
  • Test ofte: Kør og test genstanden efter hver større ændring
  • Opfølgning: Bed om forbedringer og forbedringer

AI-udviklingsværktøjer og -miljø

Dette repository fungerer exceptionelt godt med AI-parprogrammeringsværktøjer. Uanset om du udvikler lokalt eller i GitHub Codespaces, kan du bruge GitHub Copilot eller andre AI-assistenter til at accelerere opgaver som at redigere React-komponenter, opdatere ruter eller generere teststøttel.

Tips

Det Starter-Kit lager er AI-aktiveret og indeholder GitHub Copilot-instruktioner, der guider dig gennem tilpasning af Hello World-elementet til dine behov. Andre AI-værktøjer (for eksempel Anthropic Claude) kan følge samme vejledning, men skal konfigureres til at læse arkivets vejledningsfiler eller dokumentation.

Specifikke AI-støtteområder:

  • Brug AI til at udarbejde item editor/view komponenter og derefter tilpasse dig de host-API-mønstre, der bruges i Starter-Kit
  • Bed AI om at opsummere arbejdsbelastningsmanifestet og foreslå minimale tilladelsessæt
  • I Codespaces er Copilot tilgængelig i browseren eller på VS Code-skrivebordet; Hold udviklerserveren kørende for at se ændringer øjeblikkeligt

Tips

Hvis du er interesseret i at se, hvad andre bygger, så åbn Extensibility Samples og deploy dem til dit miljø. Der kan du finde detaljerede varetyper, der hjælper dig med at komme i gang.

Hurtig iteration og fejlfinding

Udvidelsesrammen er designet til hurtig udvikling ved brug af AI-assistance:

  • Med dev-serveren og DevGateway kørende vises kodeændringer i din app straks, når du åbner dit item inde i Fabric
  • Du kan fejlfinde ved hjælp af din browsers udviklingsværktøjer, mens arbejdsbelastningen er hostet i Fabric iFrame
  • Iterer hurtigt på UI, ruter og manifest-konfiguration, og valider end-to-end adfærd i dit Fabric-arbejdsområde
  • AI-værktøjer kan hjælpe med at identificere og løse problemer i realtid, mens du udvikler dig

Forventet tidslinje

  • Simpel opgave: 30-60 minutter med AI-vejledning
  • Kompleks opgave: 1-3 timer med flere iterationer
  • Avanceret item: Halv dag med omfattende tilpasning

🛠️ Manuel scriptet tilgang

Brug af CreateNewItem.ps1-scriptet

Den manuelle tilgang bruger et automatiseret PowerShell-script, der kopierer HelloWorld-itemskabelonen og konfigurerer den til dit nye item.

Hurtig start

  1. Navigér til script-mappen:

    cd scripts\Setup

  2. Kør oprettelsesscriptet:

    .\CreateNewItem.ps1 -ItemName "MyCustomItem"

Hvad manuskriptet gør

Automatiseret filoprettelse:

  • ✅ Kopierer alle 4 kernekomponentfiler fra HelloWorld-skabelonen
  • ✅ Omdøb filer, så de matcher dit varenavn
  • ✅ Opdaterer alle interne referencer og importer
  • ✅ Opretter manifestfiler (XML- og JSON-konfigurationer)
  • ✅ Kopierer og omdøber ikonaktiver

Genereret filstruktur:

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

Påkrævede manuelle trin

Efter at have kørt scriptet skal du gennemføre disse manuelle konfigurationstrin:

1. Opdater miljøfiler KRITISKE 🚨

Tilføj dit nye element til variablen ITEM_NAMES i ALLE miljøfiler:

Filer der skal opdateres:

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

Ændring fra:

ITEM_NAMES=HelloWorld

Skift til:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ Uden dette trin vil dit item IKKE dukke op i arbejdsbyrden!

2. Opdater Product.json konfiguration

Tilføj din varekonfiguration til 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. Tilføj lokaliseringsstrenge

Opdater oversættelsesfiler i Workload\Manifest\assets\locales\:

I en-US.json (og andre lokalfiler):

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

4. Tilføj routingkonfiguration

Opdater Workload\app\App.tsx for at inkludere routing for din nye vare:

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

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

Verifikationstrin

Efter at have gennemført alle manuelle trin:

  1. Byg projektet:

    npm run build

  2. Genstart udviklingsserveren:

    .\scripts\Run\StartDevServer.ps1

  3. Test i stof:

    • Naviger til din arbejdsbyrde i Fabric
    • Tjek at din nye genstandstype vises i oprettelsesdialogen
    • Opret en instans og verificér, at den indlæses korrekt

Bedste praksis og retningslinjer

Hvorfor ikke omdøbe HelloWorld?

HelloWorld-elementet fungerer som referenceskabelonen , der modtager regelmæssige opdateringer fra Microsoft. Vigtige grunde til at bevare den uændret:

  • Opdateringer og forbedringer: Microsoft opdaterer regelmæssigt HelloWorld med nye funktioner, fejlrettelser og bedste praksis
  • Integrationstest: HelloWorld sikrer, at dit miljø fungerer korrekt
  • Referencedokumentation: Den fungerer som live-dokumentation for implementeringsmønstre
  • Bagudkompatibilitet: Opdateringer bevarer kompatibilitet med eksisterende tilpasninger
  1. Hold HelloWorld uberørt: Brug det som reference og testobjekt
  2. Opret nye elementer: Brug scriptet eller AI-assistance til at skabe separate elementer
  3. Regelmæssige opdateringer: Træk periodisk opdateringer fra basisarkivet
  4. Merge Patterns: Påfør nye mønstre fra opdateret HelloWorld på dine brugerdefinerede genstande

Bedste praksis for produktudvikling

Komponentarkitektur:

  • ✅ Følg 4-komponent mønsteret (Definition, Editor, Tom, Bånd)
  • ✅ Brug ItemEditor-beholderen for ensartet layout og adfærd
  • ✅ Implementer korrekt belastningstilstande og fejlhåndtering
  • ✅ Følg Fluent UI-designmønstre

Datastyring:

  • ✅ Brug saveWorkloadItem() for elementer med komplekse data
  • ✅ Brug getWorkloadItem() til indlæsning med fallback-standardindstillinger
  • ✅ Implementer korrekte TypeScript-grænseflader i definitionsfilen
  • ✅ Håndter udefinerede/tomme tilstande elegant

Brugeroplevelse:

  • ✅ Giv klare tomme tilstande til førstegangsbrugere
  • ✅ Brug korrekte belastningsindikatorer
  • ✅ Implementer nyttige fejlmeddelelser
  • ✅ Følg tekstildesignmønstre og tilgængelighedsretningslinjer

Ydelsesovervejelser

  • Lazy Loading: Indlæs kun data, når det er nødvendigt.
  • Effektive opdateringer: Brug React-mønstre for at minimere genrenderinger
  • OneLake-integration: Brug createItemWrapper() til korrekt afgrænsning
  • Fejlgrænser: Implementer korrekt fejlhåndtering gennem hele processen

Næste trin

Når din genstand er oprettet:

  1. Tilpas datamodellen: Opdater definitionsfilen med dine specifikke grænseflader
  2. Implementér kernefunktioner: Byg hovedfunktionaliteten ud i editor-komponenten
  3. Design Empty State: Skab en engagerende førstegangsbrugeroplevelse
  4. Konfigurér handlinger: Opsæt passende båndhandlinger til din arbejdsgang
  5. Test grundigt: Verificér al funktionalitet i dit udviklingsmiljø
  6. Forbered dig til produktion: Følg udgivelsesguiden , når du er klar

Fejlfinding

Elementet vises ikke i arbejdsmængden:

  • ✅ Tjek ITEM_NAMES i alle .env-filer
  • ✅ Bekræft Product.json konfiguration
  • ✅ Genstart udviklingsserveren

Byggefejl:

  • ✅ Tjek TypeScript-grænseflader i definitionsfilen
  • ✅ Kontroller alle importer korrekte.
  • ✅ Sørg for, at routing er korrekt konfigureret

Runtime-fejl:

  • ✅ Tjek browserens konsol for detaljerede fejlmeddelelser
  • ✅ Verificér API-integration og autentificering
  • ✅ Test først med forenklede data

Ekstra ressourcer

God fornøjelse med kodningen! 🚀

  • Last updated on