Estendere il front-end di Microsoft Fabric

È possibile usare Microsoft Fabric Workload Development Kit per creare carichi di lavoro e creare funzionalità personalizzate che estendono l'esperienza infrastruttura. 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 dell'area di lavoro Infrastruttura.

In questo articolo si usa il repository di esempio di sviluppo del carico di lavoro di Microsoft Fabric come guida per integrare un'app Web del carico di lavoro dell'esperienza utente personalizzata 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 front-end del progetto di carico di lavoro dell'esperienza utente di esempio è un'app Web React standard che incorpora l'SDK client del carico di lavoro, come 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 manifesto front-end si trovano nella cartella del pacchetto . 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 tenant deve prima abilitare la funzionalità di sviluppo del carico di lavoro nel portale di amministrazione di Microsoft Fabric. 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.

Configurare il front-end

Per configurare il front-end del progetto di esempio:

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

2. Clonare il repository di esempio di sviluppo del carico di lavoro di Microsoft Fabric.

   L'elenco seguente descrive il layout, i componenti e le risorse della directory del pacchetto:

   • Pacchetto: percorso 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.worker index.ui (vedere i dettagli più avanti in questo articolo).
     • App.tsx: questo file instrada i percorsi alle pagine. Ad esempio, /sample-workload-editor viene instradato alla SampleWorkloadEditor funzione 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.
     • Configurazione Web e lettore/processore manifesto.
   • 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.

3. All'interno della cartella del repository passare alla cartella Front-end per installare i file di progetto:

   <repository folder>\Frontend> npm install
   

4. 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 pagina 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":

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

2. Nel menu dell'area di lavoro selezionare l'icona Crea hub (a volte l'icona si trova nell'icona Mostra altri puntini di sospensione).

   

3. Seleziona Vedi tutto.

   

4. In Carico di lavoro di esempio selezionare la scheda Elemento di esempio per creare un elemento.

   

Il nuovo elemento è simile a questo esempio:

Esplorare i vari controlli per visualizzare le funzionalità dell'API WorkloadClient dell'infrastruttura (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.

Informazioni sul codice

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

bootstrap()

Prima del bootstrap, controllare il percorso per verificare 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 infrastruttura deve supportare l'inizializzazione in due modalità:

• Modalità interfaccia utente: un'app in modalità interfaccia utente viene caricata in iFrame visibili. Rimane in ascolto delle modifiche di route per eseguire il rendering dei componenti dell'interfaccia utente corrispondenti, ad esempio pagine, pannelli e dialoghi.

• 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() invia una notifica al framework micro-front-end fabric di inizializzazione riuscita o di errore.

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 principale onAction . 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 onAction gestore oppure possono essere avviate dall'host fabric. Ad esempio, quando si seleziona Crea elemento di esempio - Solo front-end, Fabric attiva l'azione open.createSampleWorkloadFrontendOnlye il gestore avvia l'apertura onAction della pagina principale dell'interfaccia utente del carico di lavoro. Il valore dell'area di lavoro objectId corrente viene passato anche all'esperienza di solo front-end.

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, che viene usato 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.

CREATE

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 si seleziona un elemento del carico di lavoro di esempio esistente nella visualizzazione dell'area di lavoro, Fabric passa alla route definita nel manifesto front-end in artifactspath>editor>:

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

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

UPDATE

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 le modifiche dell'elemento lastModifiedTime dopo un aggiornamento.

DELETE

È possibile chiamare l'operazione delete nella visualizzazione dell'area di lavoro Infrastruttura come azione generale disponibile per tutti gli elementi o tramite una chiamata esplicita dal carico di lavoro a itemCrud.deleteItem.

Entrambi i tipi di chiamate passano attraverso il callback del back-end del carico di onDeleteItem 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 Opzioni.

È 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 SampleWorkloadEditordi .

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 manifesto front-end

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 carico di lavoro di esempio, il manifesto viene caricato in Infrastruttura in modalità sviluppatore. Le sezioni del manifesto, le definizioni e gli esempi del manifesto vengono visualizzati nei file manifesto front-end.

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 API seguenti non 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.

Contenuto correlato

• Panoramica di Workload Development Kit
• Guida alla configurazione back-end