Estendere il front-end di Microsoft Fabric

È possibile usare il Microsoft Fabric Workload Development Kit per sviluppare carichi di lavoro e creare funzionalità personalizzate che estendono l'esperienza di Fabric. La piattaforma Fabric è progettata per essere interoperabile con funzionalità del fornitore di software indipendente (ISV). Ad esempio, è possibile usare l'editor di elementi per creare un'esperienza utente nativa e coerente incorporando il front-end di un ISV nel contesto di un elemento di un'area di lavoro Fabric.

In questo articolo, si utilizza il repository di esempio per lo sviluppo di carichi di lavoro di Microsoft Fabric come guida per integrare un'app Web di un carico di lavoro UX personalizzato con Microsoft Fabric. Il progetto e gli esempi dettagliati consentono di integrare facilmente i propri componenti e azioni dell'interfaccia utente nell'ambiente di runtime di Fabric per una sperimentazione e una personalizzazione efficienti.

Il frontend del progetto di esempio del carico di lavoro UX è una standard web app React che incorpora l'SDK client del carico di lavoro, sotto forma di pacchetto npm standard, per fornire funzionalità.

L'ISV ospita ed esegue il progetto all'interno di un elemento in <iframe> modalità sandbox nel portale di Fabric. Presenta esperienze di interfaccia utente specifiche dell'ISV, incluso un editor di elementi.

L'SDK fornisce tutte le interfacce, le API e le funzioni bootstrap necessarie per trasformare un'app Web normale in un'app Web micro front-end che funziona perfettamente nel portale di Fabric.

L'SDK fornisce un progetto di carico di lavoro dell'esperienza utente di esempio. L'esempio:

Illustra come usare la maggior parte delle chiamate SDK disponibili.
Illustra un esempio della barra multifunzione estendibile basata sull'interfaccia utente Fluent che corrisponde all'aspetto di Fabric.
Consente una semplice personalizzazione.
Consente di osservare le modifiche in Fabric in tempo reale quando la modalità sviluppatore di Fabric è attivata.

Prerequisiti

App Web del carico di lavoro dell'esperienza utente

Questo pacchetto è basato sull'interfaccia utente Fluent ed è progettato per React.
Manifesto front-end del carico di lavoro dell'esperienza utente

Il manifesto front-end del carico di lavoro dell'esperienza utente è una risorsa JSON fornita dall'ISV. Il file contiene informazioni essenziali sul carico di lavoro, inclusi l'URL dell'app Web del carico di lavoro e vari dettagli dell'interfaccia utente, ad esempio il nome visualizzato dell'elemento ISV e le icone associate. L'ISV può usare il file manifesto per personalizzare ciò che accade quando gli utenti interagiscono con gli elementi nel portale di Fabric.

In questo pacchetto, i file manifest del frontend si trovano nella cartella package. Il file manifesto contiene una descrizione dettagliata del manifesto del carico di lavoro e dei relativi componenti.

Abilitare la funzionalità di sviluppo del carico di lavoro in Fabric

L'amministratore del tenant deve prima abilitare la funzione di sviluppo del carico di lavoro nelle impostazioni del tenant. La funzionalità può essere abilitata per l'intera organizzazione o per gruppi specifici all'interno dell'organizzazione. Per un amministratore tenant, per abilitare la funzionalità di sviluppo del carico di lavoro per gruppi specifici, completare i passaggi descritti in Abilitare l'impostazione del tenant di sviluppo.

Schermata del selettore del tenant di sviluppo dei carichi di lavoro.

Configurare il front-end

Per configurare il front-end del progetto di esempio:

Verificare che Node.js e npm siano installati. L'installazione di npm deve essere la versione 9 o successiva. In caso contrario, installare le versioni più recenti di Node.js e npm.
Clonare il repository di esempio per lo sviluppo di workload Microsoft Fabric.

L'elenco seguente descrive il layout, i componenti e le risorse della directory del pacchetto:
- Pacchetto: la posizione del pacchetto del carico di lavoro. Il pacchetto contiene risorse front-end, inclusi manifesti e asset.
- src: il codice del carico di lavoro, che include queste risorse:
  - index.ts: file di inizializzazione principale, inclusi bootstrap e iFrame index.workerindex.ui (vedere i dettagli più avanti in questo articolo).
  - App.tsx: Questo file indirizza i percorsi alle pagine. Ad esempio, /sample-workload-editor viene instradato alla funzione SampleWorkloadEditor in components.
  - assets: posizione per le immagini (.jpg, .jpeg e png) a cui è possibile fare riferimento nel manifesto e visualizzate nell'interfaccia utente. Ad esempio, assets/github.jpg viene impostato nel manifesto come icona del prodotto.
  - components: posizione del codice dell'interfaccia utente, inclusa la visualizzazione dell'editor e altre visualizzazioni usate dall'esempio (la barra multifunzione, la pagina di autenticazione e i pannelli).
  - controller: il controller chiama le API SDK.
  - modelli: contratti e modelli usati dall'interfaccia utente e per la comunicazione con il back-end di boilerplate.
- strumenti: elementi che è possibile usare per creare impostazioni e configurazioni.
  - webpack.config.js: usare questo file per configurare il server Node.js locale.
  - Un lettore/elaboratore di configurazioni web e manifest.
- validation: l'esempio usa validateSchema.js per convalidare gli schemi di file JSON del prodotto e dell'elemento. È configurato per l'esecuzione in npm start.
All'interno della cartella del repository passare alla cartella Front-end per installare i file di progetto:
```
<repository folder>\Frontend> npm install
```
Avviare il server eseguendo il comando seguente:
```
<repository folder>\Frontend> npm start
```
Questo comando avvia un server Node.js locale (tramite webpack) a cui Si connette Microsoft Fabric quando è in modalità sviluppatore.

Per informazioni sui dettagli della porta visualizzati dopo l'avvio del server, vedere le note sul server host locale.

La porta corrente è 60006.

Dopo l'avvio del server localhost, passare all'URL 127.0.0.1:60006/manifests per aprire il manifesto aggregato creato nella cartella Frontend/Package .

Se si modificano i file all'interno della cartella Frontend/Package , eseguire npm start di nuovo.

Questa impostazione è persistente nel browser corrente.

Esempio di "Hello world"

Per eseguire uno scenario di test "hello world":

Avviare il server locale (seguire la procedura descritta in Introduzione all'esecuzione degli esempi del carico di lavoro front-end e back-end) e assicurarsi che la modalità sviluppatore sia abilitata.
Nel menu dell'area di lavoro, seleziona l'icona Crea hub (a volte l'icona si trova nei puntini di sospensione Mostra altro).
Seleziona Vedi tutto.
In Carico di lavoro di esempio, seleziona la scheda Elemento di esempio per creare un elemento.

Il nuovo elemento è simile a questo esempio:

Schermata dell'interfaccia immagine dell'interfaccia utente di esempio principale.

Esplora i vari controlli per vedere le funzionalità dell'API Fabric WorkloadClient (l'SDK del carico di lavoro):

Aprire notifiche e finestre di dialogo
Vai alle pagine
Ottenere le impostazioni del tema e del carico di lavoro
Eseguire azioni

La maggior parte delle funzionalità disponibili dell'SDK è configurata come azioni del pulsante o registrata come callback. I risultati sono in genere una notifica o una finestra di messaggio che mostra che è stata richiamata un'API.

Ad esempio:

Eseguire un'azione chiama l'API action.execute() con un'azione denominata sample. Azione. La funzionalità dell'azione consiste nel mostrare una notifica.
Selezionare Salva sulla barra multifunzione per chiamare l'API dialog.open(). L'API apre una finestra di dialogo in cui un utente immette un nome e salva l'elemento in Fabric. Per altre informazioni sulla finestra di dialogo, vedere la sezione CRUD.
Il pulsante Get Theme Settings (Ottieni impostazioni tema) mostra un elenco delle configurazioni dei temi di Fabric (tramite l'API theme.get().

L'interfaccia utente del carico di lavoro di esempio è ospitata in un elemento in iframe modalità sandbox di Fabric visualizzato in modalità sviluppatore per la pagina Web.

Screenshot dell'immagine incorporata di iFrame.

Nota

L'elemento iframe sottoposto a sandbox supporta gli attributi allow-same-origin e allow-scripts.

Per altre informazioni su sandbox e attributi, vedere MdN Web Docs.

Informazioni sul codice

Le sezioni seguenti descrivono gli elementi di codice e le considerazioni pertinenti.

bootstrap()

Prima dell'avvio, verificare il percorso per capire se è necessario chiudere la finestra. Questo passaggio è obbligatorio se si usa l'API di autenticazione .

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
    window.close();
}

Ogni app del carico di lavoro di Fabric deve supportare l'inizializzazione in due modalità:

Modalità UI: un'app in modalità UI viene caricata in iFrame visibili. Rimane in ascolto delle modifiche alle proprie route per renderizzare i componenti dell'interfaccia utente corrispondenti, come pagine, pannelli e finestre di dialogo.
Modalità di lavoro: un'app in modalità di lavoro viene eseguita in un iFrame invisibile. L'iFrame invisibile viene usato principalmente per ricevere comandi esterni e rispondere.

L'API @ms-fabric/workload-client fornisce un bootstrap() metodo per semplificare i passaggi di inizializzazione. Il bootstrap() metodo rileva internamente se l'app corrente viene caricata in modalità interfaccia utente o in modalità di lavoro. Chiama quindi il metodo di inizializzazione appropriato (initializeUI o initializeWorker). Al termine dell'inizializzazione, bootstrap() notifica al framework Fabric micro-frontend l'avvenuta inizializzazione oppure un errore di inizializzazione.

bootstrap({
    initializeWorker: (params) =>
        import('./index.worker').then(({ initialize }) => initialize(params)),
    initializeUI: (params) =>
        import('./index.ui').then(({ initialize }) => initialize(params)),
});

index.worker

index.worker è la registrazione onAction principale. Gestisce gli eventi inviati dall'host fabric, che vengono attivati da azioni eseguite.

Le azioni possono essere inviate dal carico di lavoro a Fabric e quindi richiamate nel gestore onAction, oppure possono essere avviate dall'host Fabric. Ad esempio, quando si seleziona Crea elemento di esempio - solo frontend, Fabric attiva l'azione open.createSampleWorkloadFrontendOnly e il gestore onAction apre la pagina principale dell'interfaccia utente del carico di lavoro. Anche il valore corrente dello spazio di lavoro objectId viene passato all'esperienza solo frontend.

La sequenza è illustrata nell'esempio di codice seguente:

   workloadClient.action.onAction((message) => {
        switch (message.action) {
            /**
             * This opens the frontend-only experience, so you can experiment with the UI without using CRUD operations.
             * You can still save the item if the backend is connected and registered.
             */
            case 'open.createSampleWorkloadFrontendOnly':
                const { workspaceObjectId: workspaceObjectId1 } = data as ItemCreateContext;
                return workloadClient.page.open({
                    workloadName: 'Org.WorkloadSample',
                    route: {
                        path: `/sample-workload-frontend-only/${workspaceObjectId1}`,
                    },
                });

                // . . . elided for brevity . . .
            default:
                throw new Error('Unknown action received');
        }
    });

index.ui

La funzione initialize() esegue il rendering del DOM React in cui la funzione App è incorporata. Per richiamare le chiamate API, passare l'handle SDK workloadClient, utilizzato in tutto il codice.

La classe FluentProvider garantisce la coerenza dello stile tra i vari controlli FluentUI. Ecco un esempio:

ReactDOM.render(
      <FluentProvider theme={fabricLightTheme}>
           <App
               history={history}
               workloadClient={workloadClient}
           />
       </FluentProvider>,
       document.querySelector("#root")
   );

Flusso di sviluppo

La App funzione indirizza il codice a SampleWorkloadEditor. La funzione restituisce un valore per React.JSX.Element.
La funzione contiene la struttura dell'interfaccia utente. La struttura dell'interfaccia utente contiene i controlli della barra multifunzione e della pagina, ad esempio pulsanti e campi di input.
Le informazioni raccolte dall'utente vengono archiviate tramite l'hook React useState() .
I gestori dei controlli dell'interfaccia utente chiamano le SampleWorkloadController funzioni e passano le variabili di stato pertinenti.
Per supportare le operazioni CRUD, lo stato dell'elemento creato/caricato viene archiviato in artifactItem con workspaceObjectId e un'implementazione di esempio di variabili di payload.

Gli esempi seguenti usano l'API notification.open():

Stato:

   const [apiNotificationTitle, setNotificationTitle] = useState<string>('');
   const [apiNotificationMessage, setNotificationMessage] = useState<string>('');

Interfaccia utente:

Questi esempi configurano elementi specifici dell'interfaccia utente:

Titolo:

<Field label="Title" validationMessage={notificationValidationMessage} orientation="horizontal" className="field">
    <Input size="small" placeholder="Notification Title" onChange={e => setNotificationTitle(e.target.value)} />
  </Field>

Pulsante Invia:

<Button icon={<AlertOn24Regular />} appearance="primary" onClick={() => onCallNotification()} > Send Notification </Button>

Gestore:

function onCallNotification() {
  ... elided for brevity
   callNotificationOpen(apiNotificationTitle, apiNotificationMessage, undefined, undefined, workloadClient, setNotificationId);
};

Controller:

  export async function callNotificationOpen(
    title: string,
    message: string,
    type: NotificationType = NotificationType.Success,
    duration: NotificationToastDuration = NotificationToastDuration.Medium,
    workloadClient: WorkloadClientAPI,
    setNotificationId?: Dispatch<SetStateAction<string>>) {

    const result = await workloadClient.notification.open({
        notificationType: type,
        title,
        duration,
        message
    });
    if (type == NotificationType.Success && setNotificationId) {
        setNotificationId(result?.notificationId);
    }
}

Operazioni CRUD

Anche se uno scenario di sviluppo front-end è facilmente supportato, l'esperienza di sviluppo end-to-end completa richiede il salvataggio, la lettura e la modifica di elementi del carico di lavoro esistenti.

La guida all'implementazione back-end descrive in dettaglio come configurare e usare il back-end.

Quando il back-end è operativo e il Org.WorkloadSample.SampleWorkloadItem tipo è registrato in Fabric, è possibile eseguire operazioni CRUD su questo tipo.

Le operazioni seguenti vengono esposte usando l'API ItemCrud.

CREA

Per effettuare una chiamata di esempio a create, usare l'esempio seguente che mostra il salvataggio dell'elemento del carico di lavoro per la prima volta:

 const params: CreateItemParams = {
        workspaceObjectId,
        payload: { itemType, displayName, description, workloadPayload: JSON.stringify(workloadPayload), payloadContentType: "InlineJson", }
    };
 const result: CreateItemResult = await workloadClient.ItemCrud.createItem(params);

L'implementazione di esempio archivia l'elemento creato in artifactItem.

L'elemento viene creato nell'area di lavoro attualmente selezionata. L'area di lavoro deve essere assegnata alla capacità impostata nella configurazione back-end. Per altre informazioni, vedere la documentazione del back-end.

Un tentativo di creare un elemento in un'area di lavoro non conforme ha esito negativo:

Il onCreateFabricItem callback nel back-end blocca la CREATE chiamata. Un errore a quel punto causa l'esito negativo dell'operazione e non viene creato alcun elemento in Fabric. Per altre informazioni, vedere la documentazione relativa al debug e alla risoluzione dei problemi del back-end.
Attualmente, un elemento salvato non viene visualizzato automaticamente nell'area di lavoro. Per visualizzare un elemento salvato nell'area di lavoro, aggiornare la pagina.

GET

Quando selezioni un elemento esistente del workload di esempio nella visualizzazione dell'area di lavoro, Fabric passa al percorso definito nel manifest del front-end in artifacts>editor>path:

"items": [
  {
   "name": "Org.WorkloadSample.SampleWorkloadItem",
   "editor": {
    "workload": "Org.WorkloadSample",
    "path": "/sample-workload-editor"
   },

Quando si invoca itemCrud.getItem, i dati vengono caricati sia dal back-end di Fabric sia dal back-end del carico di lavoro. I dati di entrambe le origini vengono caricati nell'oggetto dell'interfaccia artifactItem utente grafica aperta.

Schermata dell'apertura di elementi esistenti nell'area di lavoro.

AGGIORNA

Per aggiornare un elemento esistente, usare itemCrud.updateItem. Il payload del carico di lavoro viene aggiornato dal back-end del carico di lavoro. In Fabric, solo il lastModifiedTime dell'elemento cambia dopo un aggiornamento.

ELIMINA

È possibile richiamare l'operazione delete sia nella vista dell'area di lavoro di Fabric come azione generale disponibile per tutti gli elementi, sia tramite una chiamata esplicita dal workload a itemCrud.deleteItem.

Entrambi i tipi di chiamate passano tramite il callback onDeleteItem del backend del carico di lavoro.

Visualizzare l'attività di autenticazione

Nell'editor del carico di lavoro di esempio è possibile visualizzare l'attività di autenticazione.

Prima di usare l'API di autenticazione, configurare l'app per l'autenticazione usando Microsoft Entra ID.

Assicurarsi anche che il file di env.dev sia configurato correttamente. Per altre informazioni, vedere Configurare il manifesto locale del carico di lavoro e acquisire un token per l'applicazione.

Debug

Per visualizzare gli elementi iframe di lavoro e dell'interfaccia utente, nel browser selezionare F12 per aprire gli strumenti di sviluppo del browser. Fare clic sulla scheda Sorgenti.

Schermata dei file di debug in Visual Studio Code.

È possibile inserire un punto di interruzione nell'elemento iframe di lavoro e visualizzare il principale switch nell'azione in ingresso. È anche possibile eseguire il debug dell'elemento iframe dell'interfaccia utente. Ad esempio, è possibile eseguire il debug del codice all'interno di SampleWorkloadEditor.

Controlli dell'interfaccia utente di Fluent

I carichi di lavoro dell'esperienza utente usano controlli dell'interfaccia utente Fluent per coerenza visiva con Fabric e per semplificare lo sviluppo. Il progetto di carico di lavoro di esempio fornisce esempi di come usare i controlli più comuni.

Per altre informazioni, vedere Fluent UI.

Personalizzazione del file manifest del frontend

Il manifesto front-end descrive gli aspetti front-end del carico di lavoro, tra cui aspetto del prodotto, nomi, asset visivi e azioni disponibili. Il manifesto front-end è il punto di contatto principale tra Fabric e il carico di lavoro.

Per il nostro carico di lavoro di esempio, il file manifesto viene caricato in Fabric in modalità Developer. Le sezioni, le definizioni e gli esempi del manifest sono mostrate nei file manifest frontend.

Le modifiche apportate alle voci, alle impostazioni dell'azione e agli aggiornamenti degli asset visivi del manifesto vengono visualizzate in tempo reale dopo l'aggiornamento della pagina.

API supportate dall'SDK client

Le seguenti API sono supportate:

notification.open
notification.hide
panel.open
panel.close
action.onAction
action.execute
navigation.navigate
navigation.onNavigate
navigation.onBeforeNavigateAway
navigation.onAfterNavigateAway
page.open
dialog.openDialog
dialog.openMessageBox
dialog.close
theme.get
theme.onChange
settings.get
settings.onChange
errorHandling.openErrorDialog
errorHandling.handleRequestFailure
itemCrud.createItem
itemCrud.getItem
itemCrud.updateItem
itemCrud.deleteItem
itemSchedule.runItemJob
itemSchedule.cancelItemJob
itemRecentRuns.open

Per altre informazioni, vedere pacchetto @ms-fabric/workload-client.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-09-29