Creare un nuovo elemento del fabric

Questa guida completa illustra come creare elementi personalizzati in Microsoft Fabric usando Extensibility Toolkit. È possibile scegliere tra due approcci in base al livello di preferenza e esperienza.

Prerequisiti

Prima di creare un elemento personalizzato, assicurarsi di disporre di:

✅ Completata la Guida all'installazione e si dispone di un ambiente di sviluppo funzionante
✅ Il workload è in esecuzione localmente ed è accessibile in Fabric
✅ Familiarità con TypeScript e React (per la personalizzazione)

Scegliere l'approccio

🤖 approccio AI-Assisted (consigliato per i nuovi sviluppatori)

Usare GitHub Copilot per guidare l'intero processo in modo interattivo. Perfetto per:

Sviluppatori nuovi di Fabric Extensibility Toolkit
Apprendimento dei modelli e delle procedure consigliate per la piattaforma
Ottenere spiegazioni e indicazioni durante il lavoro

🛠️ Approccio con script manuale (consigliato per sviluppatori esperti)

Usare lo script di PowerShell automatizzato per la configurazione rapida. Perfetto per:

Sviluppatori che hanno familiarità con la struttura del toolkit
Creazione efficiente di più elementi
Flussi di lavoro di produzione e automazione

🤖 Creazione di elementi assistita dall'IA

Introduzione a GitHub Copilot

GitHub Copilot può guidarti nella creazione di un elemento completo e personalizzato di Fabric seguendo le best practice. L'intelligenza artificiale comprende i modelli dell'Extensibility Toolkit e vi aiuterà a implementarli correttamente.

Suggerimenti di esempio funzionanti

Ecco alcuni prompt comprovati che consentono di iniziare a creare elementi:

Creazione di elementi di base:

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

Requisiti specifici:

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

Elemento complesso con integrazione di 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

Processo tipico assistito dall'IA

L'approccio assistito dall'intelligenza artificiale segue questo modello iterativo:

1. Fase iniziale di pianificazione

L'intelligenza artificiale analizza i requisiti
Suggerisce la struttura e i componenti degli elementi
Crea un piano di sviluppo con todos

2. Generazione di componenti

Crea il modello a 4 file (Definizione, Editor, Vuoto, Barra multifunzione)
Implementa interfacce appropriate di TypeScript
Configura i componenti dell'interfaccia utente Fluent

3. Implementazione delle funzionalità

Aggiunge funzionalità specifiche
Si integra con le API di infrastruttura
Implementa una corretta gestione degli errori

4. Test e perfezionamento

Testa l'elemento nel tuo ambiente di sviluppo
Risolve eventuali problemi rilevati
Ottimizza le prestazioni e l'esperienza utente

Lavorare con l'Assistente di intelligenza artificiale

Iniziare con requisiti chiari:

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

Eseguire l'iterazione e perfezionare:

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?

Chiedi spiegazioni:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Procedure consigliate per la collaborazione con intelligenza artificiale

Specificare: fornire requisiti e contesto chiari
Esaminare ogni passaggio: comprendere il codice generato prima di procedere
Domande: richiedere spiegazioni per i modelli non comprensibili
Test frequenti: eseguire e testare l'elemento dopo ogni modifica principale
Completamento: Chiedere perfezionamenti e miglioramenti

Strumenti e ambiente per lo sviluppo di intelligenza artificiale

Questo repository funziona in modo eccezionale con gli strumenti di intelligenza artificiale per la programmazione in coppia. Sia che si sviluppino localmente o in GitHub Codespaces, è possibile usare GitHub Copilot o altri assistenti di intelligenza artificiale per accelerare le attività come la modifica di componenti React, l'aggiornamento delle route o la generazione di scaffolding di test.

Suggerimento

Il repository Starter-Kit è abilitato per l'intelligenza artificiale e include istruzioni di GitHub Copilot che consentono di adattare l'elemento Hello World alle proprie esigenze. Altri strumenti di intelligenza artificiale (ad esempio, Anthropic Claude) possono seguire le stesse indicazioni, ma devono essere configurati per leggere i file di indicazioni o la documentazione del repository.

Aree di assistenza di intelligenza artificiale specifiche:

Usare l'intelligenza artificiale per creare bozze di componenti dell'editor/visualizzazione degli elementi e quindi adattarsi ai modelli api host usati nella Starter-Kit
Chiedere all'intelligenza artificiale di riepilogare il manifesto del carico di lavoro e proporre set di autorizzazioni minimi
In Codespaces, Copilot è disponibile nel browser o nel desktop di VS Code; mantenere il server di sviluppo in esecuzione per visualizzare immediatamente le modifiche

Suggerimento

Se sei interessato a vedere ciò che realizzano gli altri, apri gli esempi di estendibilità e distribuiscili nel tuo ambiente. È possibile trovare tipi di elementi avanzati che consentono di iniziare.

Iterazione e debug rapidi

Il framework di estendibilità è progettato per lo sviluppo rapido quando si usa l'assistenza per l'intelligenza artificiale:

Con il server di sviluppo e DevGateway in esecuzione, le modifiche al codice nell'app vengono riflesse immediatamente quando si apre l'elemento all'interno di Fabric
È possibile eseguire il debug usando gli strumenti di sviluppo del browser mentre il carico di lavoro è ospitato nell'iFrame dell'infrastruttura
Iterare rapidamente sull'interfaccia utente, i percorsi e la configurazione del manifest e convalidare il comportamento end-to-end nella tua area di lavoro Fabric.
Gli strumenti di intelligenza artificiale consentono di identificare e risolvere i problemi in tempo reale durante lo sviluppo

Sequenza temporale prevista

Elemento semplice: 30-60 minuti con indicazioni sull'intelligenza artificiale
Elemento complesso: 1-3 ore con più iterazioni
Elemento avanzato: mezza giornata con ampia personalizzazione

🛠️ Approccio con script manuale

Uso dello script CreateNewItem.ps1

L'approccio manuale usa uno script di PowerShell automatizzato che copia il modello di elemento HelloWorld e lo configura per il nuovo elemento.

Avvio rapido

Passare alla directory degli script:
```
cd scripts\Setup
```

Eseguire lo script di creazione:

.\CreateNewItem.ps1 -ItemName "MyCustomItem"

Operazioni dello script

Creazione automatica di file:

✅ Copia tutti i 4 file di componenti principali dal modello HelloWorld
✅ Rinomina i file in modo che corrispondano al nome dell'elemento
✅ Aggiorna tutti i riferimenti interni e le importazioni
✅ Crea file manifesto (configurazioni XML e JSON)
✅ Copia e rinomina le risorse delle icone

Struttura di file generata:

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

Passaggi manuali obbligatori

Dopo aver eseguito lo script, è necessario completare questi passaggi di configurazione manuale:

1. Aggiornare i file di ambiente 🚨 CRITICO

Aggiungere il nuovo elemento alla ITEM_NAMES variabile in TUTTI i file di ambiente:

File da aggiornare:

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

Cambia da:

ITEM_NAMES=HelloWorld

Passare a:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ Senza questo passaggio, l'elemento non verrà visualizzato nel carico di lavoro.

2. Aggiornare la configurazione di Product.json

Aggiungi la configurazione dell'elemento a 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. Aggiungere stringhe di localizzazione

Aggiornare i file di traduzione in Workload\Manifest\assets\locales\:

In en-US.json (e altri file delle impostazioni locali):

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

4. Aggiungere la configurazione di routing

Aggiornare Workload\app\App.tsx per includere il routing per il nuovo elemento:

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

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

Passaggi di verifica

Dopo aver completato tutti i passaggi manuali:

Compilare il progetto:
```
npm run build
```
Riavviare il server di sviluppo:
```
.\scripts\Run\StartDevServer.ps1
```
Test in Fabric:
- Naviga al tuo carico di lavoro in Fabric
- Verificare che il nuovo tipo di elemento venga visualizzato nella finestra di dialogo di creazione
- Creare un'istanza e verificarne il caricamento corretto

Procedure consigliate e linee guida

Perché non rinominare HelloWorld?

L'elemento HelloWorld funge da modello di riferimento che riceve aggiornamenti regolari da Microsoft. Motivi chiave per mantenerlo invariato:

Aggiornamenti e miglioramenti: Microsoft aggiorna regolarmente HelloWorld con nuove funzionalità, correzioni di bug e procedure consigliate
Test di integrazione: HelloWorld garantisce che l'ambiente funzioni correttamente
Documentazione di riferimento: funge da documentazione dinamica per i modelli di implementazione
Compatibilità con le versioni precedenti: gli aggiornamenti mantengono la compatibilità con le personalizzazioni esistenti

Flusso di lavoro consigliato

Mantieni HelloWorld non toccato: usarlo come elemento di riferimento e test
Creare nuovi elementi: usare lo script o l'assistenza per intelligenza artificiale per creare elementi separati
Aggiornamenti regolari: eseguire periodicamente il pull degli aggiornamenti dal repository di base
Modelli di fusione: Applicare nuovi modelli da HelloWorld aggiornato agli elementi personalizzati

Migliori pratiche per lo sviluppo di articoli

Architettura dei componenti:

✅ Seguire il modello a 4 componenti (Definizione, Editor, Vuoto, Barra multifunzione)
✅ Usare il contenitore ItemEditor per un layout e un comportamento coerenti
✅ Implementare stati di caricamento e gestione degli errori appropriati
✅ Seguire i modelli di progettazione dell'interfaccia utente Fluent

Gestione dati:

✅ Usare saveWorkloadItem() per gli elementi con dati complessi
✅ Usare getWorkloadItem() per il caricamento con valori predefiniti di fallback
✅ Implementare interfacce TypeScript appropriate nel file di definizione
✅ Gestire gli stati non definiti/vuoti in modo elegante

Esperienza utente:

✅ Fornire chiari stati vuoti per gli utenti che accedono per la prima volta
✅ Usare indicatori di caricamento appropriati
✅ Implementare messaggi di errore utili
✅ Seguire i modelli di design di Fabric e le linee guida per l'accessibilità

Considerazioni sulle prestazioni

Caricamento Differito: carica solo i dati quando necessario
Aggiornamenti efficienti: usare i modelli React per ridurre al minimo il rendering
Integrazione di OneLake: usare createItemWrapper() per definire l'ambito appropriato
Limiti di errore: implementare una corretta gestione degli errori in tutta la durata

Passaggi successivi

Dopo aver creato l'elemento:

Personalizzare il modello di dati: aggiornare il file di definizione con le interfacce specifiche
Implementare le funzionalità principali: creare le funzionalità principali nel componente editor
Progettare uno stato vuoto: creare un'esperienza utente coinvolgente per la prima volta
Configurare azioni: configurare le azioni della barra multifunzione appropriate per il flusso di lavoro
Test approfondito: verificare tutte le funzionalità nell'ambiente di sviluppo
Prepararsi per la produzione: seguire la guida alla pubblicazione quando si è pronti

Risoluzione dei problemi

L'elemento non viene visualizzato nel carico di lavoro:

✅ Controllare ITEM_NAMES in tutti i file .env
✅ Verificare la configurazione di Product.json
✅ Riavviare il server di sviluppo

Errori di compilazione:

✅ Controllare le interfacce TypeScript nel file di definizione
✅ Verificare che tutte le importazioni siano corrette
✅ Verificare che il routing sia configurato correttamente

Errori di runtime:

✅ Controllare la console del browser per i messaggi di errore dettagliati
✅ Verificare l'integrazione e l'autenticazione dell'API
✅ Eseguire prima il test con dati semplificati

Risorse aggiuntive

Buon codice! 🚀

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-12-03

Condividi tramite

Creare un nuovo elemento del fabric

Prerequisiti

Scegliere l'approccio

🤖 approccio AI-Assisted (consigliato per i nuovi sviluppatori)

🛠️ Approccio con script manuale (consigliato per sviluppatori esperti)

🤖 Creazione di elementi assistita dall'IA

Introduzione a GitHub Copilot

Suggerimenti di esempio funzionanti

Processo tipico assistito dall'IA

Lavorare con l'Assistente di intelligenza artificiale

Procedure consigliate per la collaborazione con intelligenza artificiale

Strumenti e ambiente per lo sviluppo di intelligenza artificiale

Iterazione e debug rapidi

Sequenza temporale prevista

🛠️ Approccio con script manuale

Uso dello script CreateNewItem.ps1

Avvio rapido

Operazioni dello script

Passaggi manuali obbligatori

1. Aggiornare i file di ambiente 🚨 CRITICO

2. Aggiornare la configurazione di Product.json

3. Aggiungere stringhe di localizzazione

4. Aggiungere la configurazione di routing

Passaggi di verifica

Procedure consigliate e linee guida

Perché non rinominare HelloWorld?

Flusso di lavoro consigliato

Migliori pratiche per lo sviluppo di articoli

Considerazioni sulle prestazioni

Passaggi successivi

Risoluzione dei problemi

Risorse aggiuntive

Commenti e suggerimenti

Risorse aggiuntive