Étendre le serveur frontal Microsoft Fabric

Article
12/03/2024

Vous pouvez utiliser le kit de développement de charge de travail Microsoft Fabric pour créer des charges de travail et des fonctionnalités personnalisées qui étendent l’expérience Fabric. La plateforme Fabric est conçue pour être interopérable avec des fonctionnalités de fournisseur de logiciel indépendant (ISV). Par exemple, vous pouvez utiliser l’éditeur d’élément pour créer une expérience utilisateur native et cohérente en incorporant un front-end de fournisseur de logiciel indépendant dans le contexte d’un élément d’espace de travail Fabric.

Dans cet article, vous utilisez l’exemple de référentiel de développement de charge de travail Microsoft Fabric comme guide pour intégrer une application web de charge de travail d’expérience utilisateur personnalisée à Microsoft Fabric. Le projet et les exemples détaillés vous aident à intégrer en toute fluidité vos propres composants et actions d’interface utilisateur dans l’environnement d’exécution Fabric pour une expérimentation et une personnalisation efficaces.

L’exemple de serveur frontal de projet de charge de travail d’expérience utilisateur est une application web React standard qui intègre le SDK client de charge de travail, en tant que package npm standard, pour fournir des fonctionnalités.

L’éditeur de logiciels indépendant héberge et exécute le projet à l’intérieur d’un élément <iframe> en bac à sable dans le portail Fabric. Il présente des expériences d’IU propres au fournisseur de logiciel indépendant, dont un éditeur d’éléments.

Le SDK fournit toutes les interfaces, API et fonctions de démarrage nécessaires pour transformer une application web standard en application web micro front-end qui fonctionne en toute transparence dans le portail Fabric.

Le SDK fournit un exemple de projet de charge de travail d’expérience utilisateur. L'exemple :

Montre comment utiliser la plupart des appels du SDK disponibles.
Illustre un exemple du ruban extensible basé sur Fluent UI qui correspond visuellement à l’apparence de Fabric.
Permet une personnalisation facile
Vous permet d’observer les modifications dans Fabric en temps réel lorsque le mode développeur Fabric est activé.

Prérequis

Application web de charge de travail d’expérience utilisateur

Ce package est basé sur Fluent UI et est conçu pour React.
Manifeste du front-end de charge de travail d’expérience utilisateur

Le manifeste front-end de la charge de travail d’expérience utilisateur est une ressource JSON fournie par le fournisseur de logiciel indépendant. Le fichier contient des informations essentielles sur la charge de travail, dont l’URL de l’application web de charge de travail, ainsi que divers détails de l’IU, comme le nom d’affichage de l’élément du fournisseur de logiciel indépendant et les icônes associées. L’éditeur de logiciels indépendant peut utiliser le fichier manifeste pour personnaliser ce qui se passe lorsque les utilisateurs interagissent avec des éléments dans le portail Fabric.

Dans ce package, les fichiers manifeste front-end se trouvent dans le dossier du package. Le fichier manifeste contient une description détaillée du manifeste de charge de travail et de ses composants.

Activer la fonctionnalité de développement de charge de travail dans Fabric

L’administrateur client doit d’abord activer la fonctionnalité de développement de charge de travail dans le portail d’administration Microsoft Fabric. La fonctionnalité peut être activée pour l’ensemble de l’organisation ou pour des groupes spécifiques au sein de l’organisation. Pour un administrateur de locataire, pour activer la fonctionnalité de développement de charge de travail pour des groupes spécifiques, effectuez les étapes décrites dans Activer le paramètre de locataire de développement.

Capture d’écran du commutateur de client de développement des charges de travail.

Configurer le front-end

Pour configurer l’exemple de projet front-end :

Vérifiez que Node.js et npm sont installés. L’installation de npm doit être la version 9 ou ultérieure. Sinon, installez les dernières versions de Node.js et npm.
Clonez l’exemple de référentiel de développement de charge de travail Microsoft Fabric.

La liste suivante décrit la disposition, les composants et les ressources du répertoire de package :
- Package : emplacement du package de charge de travail. Le package contient des ressources front-end, y compris des manifestes et des ressources.
- src : code de charge de travail, qui inclut les ressources suivantes :
  - index.ts : fichier d’initialisation principal, dont bootstrap et les iFrames index.worker et index.ui (consultez les détails plus loin dans cet article).
  - App.tsx : ce fichier achemine les chemins d’accès à des pages. Par exemple, /sample-workload-editor est acheminé vers la fonction SampleWorkloadEditor sous components.
  - ressources : emplacement des images (.jpg, .jpeg et png) qui peuvent être référencées dans le manifeste et affichées dans l’interface utilisateur. Par exemple, assets/github.jpg est défini dans le manifeste comme icône du produit.
  - composants : emplacement du code de l’interface utilisateur, y compris l’affichage d’éditeur et autres affichages que l’exemple utilise (ruban, page d’authentification et panneaux).
  - contrôleur : le contrôleur appelle les API SDK.
  - modèles : les contrats et modèles utilisés par l’IU et pour la communication avec le back-end du texte réutilisable.
- outils: éléments que vous pouvez utiliser pour créer des paramètres et des configurations.
  - webpack.config.js : utilisez ce fichier pour configurer le serveur Node.js local.
  - Configuration Web et lecteur/processeur de manifeste.
- validation : l’exemple utilise validateSchema.js pour valider les schémas de fichier JSON de produit et d’élément. Il est configuré pour s’exécuter sur npm start.
Dans le dossier du référentiel, accédez au dossier Front-end pour installer les fichiers projet :
```
<repository folder>\Frontend> npm install
```
Démarrez le serveur en exécutant la commande suivante :
```
<repository folder>\Frontend> npm start
```
Cette commande démarre un serveur local Node.js (à l’aide de webpack) auquel Microsoft Fabric se connecte lorsqu’il est en mode développeur.

Pour plus d’informations sur les détails du port qui s’affichent après le démarrage du serveur, consultez les notes du serveur localhost.

Le type actuel est 60006.

Une fois le serveur localhost démarré, accédez à l’URL 127.0.0.1:60006/manifests pour ouvrir le manifeste agrégé créé dans le dossier Frontend/Package.

Si vous modifiez des fichiers à l’intérieur du dossier Frontend/Package, réexécutez npm start.

Ce paramètre est conservé dans le navigateur actuel.

Exemple « Hello World »

Pour exécuter un scénario de test « Hello World » :

Démarrez le serveur local (suivez les étapes décrites dans Prise en main pour exécuter les exemples de charge de travail front-end et back-end) et vérifiez que le mode développeur est activé.
Dans le menu de l’espace de travail, sélectionnez l’icône Créer un hub (parfois l’icône se trouve dans le les points de suspension Afficher plus).
Sélectionner Afficher tout.
Sous Exemple de charge de travail, sélectionnez la carte Exemple d’élément pour créer un élément.

Le nouvel élément se présente ainsi :

Capture d’écran de l’interface des images dans l’interface utilisateur de l’exemple principal.

Explorez les différents contrôles pour voir les fonctionnalités de l’API Fabric WorkloadClient (SDK de charge de travail) :

Ouvrir des notifications et des boîtes de dialogue
Accéder aux pages
Obtenir les paramètres de thème et de charge de travail
Exécuter des actions

La plupart des fonctionnalités du SDK disponibles sont configurées en tant qu’actions de bouton ou inscrites en tant que rappels. Les résultats sont généralement une notification ou une boîte de message qui indique qu’une API a été appelée.

Par exemple :

L’action Exécuter appelle l’API action.execute() avec un exemple nommé sample.Action. La fonctionnalité de l’action consiste à afficher une notification.
Sélectionnez Enregistrer sur le ruban pour appeler l’API dialog.open(). L’API ouvre une boîte de dialogue dans laquelle un utilisateur entre un nom et enregistre l’élément dans Fabric. Pour plus d’informations sur la boîte de dialogue, consultez la section CRUD.
Le bouton Obtenir les paramètres de thème affiche une liste des configurations de thème de Fabric (via l’API theme.get()).

L’exemple d’interface utilisateur de la charge de travail est hébergé dans un élément iframe en bac à sable Fabric qui est affiché en mode développeur pour la page web.

Capture d’écran de l’image d’incorporation iFrame.

Remarque

L’élément iframe en bac à sable prend en charge les attributs allow-same-origin et allow-scripts.

Pour plus d’informations sur le bac à sable et les attributs, consultez la documentation MDN Web.

Comprendre le code

Les sections suivantes décrivent les éléments de code et les considérations pertinentes.

bootstrap()

Avant d’amorcer, vérifiez si vous devez fermer la fenêtre en vérifiant le chemin d’accès. Cette étape est requise si vous utilisez l’API d’authentification.

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

Chaque application de charge de travail Fabric doit prendre en charge l’initialisation en deux modes :

Mode interface utilisateur : une application en mode interface utilisateur est chargée dans des iFrames visibles. Elle écoute ses propres modifications de routage pour afficher les composants d’interface utilisateur correspondants tels que les pages, les panneaux et les dialogues.
Mode Worker : une application en mode Worker s’exécute dans un iFrame invisible. L’iFrame invisible est principalement utilisé pour recevoir des commandes externes, puis pour y répondre.

L’API @ms-fabric/workload-client fournit une méthode bootstrap() pour simplifier les étapes d’initialisation. La méthode bootstrap() détecte en interne si l’application actuelle est chargée en mode d’interface utilisateur ou en mode Worker. Elle appelle ensuite la méthode d’initialisation appropriée (initializeUI ou initializeWorker). Une fois l’initialisation terminée, bootstrap() informe l’infrastructure microfront-end Fabric de la réussite ou de l’échec de l’initialisation.

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

index.worker

index.worker est l’inscription principale onAction. Il gère les événements envoyés par l’hôte Fabric, qui sont déclenchés par des actions exécutées.

Les actions peuvent être envoyées par la charge de travail à Fabric, puis appelées dans le gestionnaire onAction, ou elles peuvent être lancées par l’hôte Fabric. Par exemple, lorsque vous sélectionnez Créer un exemple d’élément – Frontend uniquement, Fabric déclenche l’action open.createSampleWorkloadFrontendOnly, et le gestionnaire onAction lance l’ouverture de la page principale de l’interface utilisateur de la charge de travail. La valeur d’espace de travail objectId actuelle est également passée à l’expérience front-end uniquement.

La séquence est illustrée dans l’exemple de code suivant :

   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 fonction initialize() restitue le DOM React dans lequel la fonction App est incorporée. Nous transmettons le descripteur du workloadClient kit de développement logiciel (SDK) utilisé dans tout le code pour appeler les appels d’API.

La classe FluentProvider est destinée à la cohérence de style entre les différents contrôles FluentUI en cours d’utilisation. Voici un exemple :

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

Flux de développement

La fonction App achemine le code vers SampleWorkloadEditor. La fonction retourne une valeur pour React.JSX.Element.
La fonction contient la structure de l’interface utilisateur. La structure de l’interface utilisateur contient le ruban et les contrôles de page tels que les boutons et les champs d’entrée.
Les informations collectées auprès de l’utilisateur sont stockées via le hook useState() React.
Les gestionnaires des contrôles d’IU appellent les fonctions SampleWorkloadController et passent les variables d’état appropriées.
Pour prendre en charge les opérations CRUD, l’état de l’élément créé/chargé est stocké dans artifactItem avec workspaceObjectId et un exemple d’implémentation de variables de charge utile.

Les exemples suivants utilisent l’API notification.open() :

État :

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

Interface utilisateur :

Ces exemples configurent des éléments d’interface utilisateur spécifiques :

Titre :

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

Bouton Envoyer :

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

Gestionnaire :

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

Contrôleur :

  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);
    }
}

Opérations CRUD

Bien qu’un scénario de développement du front-end uniquement soit facilement pris en charge, l’expérience complète des développeurs de bout en bout nécessite l’enregistrement, la lecture et la modification des éléments de charge de travail existants.

Le guide d’implémentation du back-end décrit en détail la procédure à suivre pour configurer et utiliser le back-end.

Lorsque le back-end opérationnel et le type Org.WorkloadSample.SampleWorkloadItem sont inscrit dans Fabric, vous pouvez effectuer des opérations CRUD sur ce type.

Ces opérations sont exposées via l’API ItemCrud.

CREATE

Pour effectuer un exemple d’appel à create, utilisez l’exemple suivant qui montre l’enregistrement de l’élément de charge de travail pour la première fois :

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

Notre exemple d’implémentation stocke l’élément créé à l’intérieur de artifactItem.

Notez que l’élément sera créé sous l’espace de travail actuellement sélectionné. L’espace de travail doit être affecté à la capacité définie dans la configuration back-end. Pour plus d’informations, consultez la documentation back-end.

Une tentative de création d’un élément sous un espace de travail non conforme échoue :

Le rappel onCreateFabricItem dans le serveur principal bloque l’appel CREATE. Un échec à ce stade entraîne l’échec de l’opération et aucun élément n’est créé dans Fabric. Pour plus d’informations, consultez la documentation sur le débogage et la résolution des problèmes du back-end.
Actuellement, un élément enregistré n’apparaît pas automatiquement dans l’espace de travail. Pour afficher un élément enregistré dans l’espace de travail, actualisez la page.

GET

Lorsque vous sélectionnez un exemple d’élément de charge de travail existant dans la vue de l’espace de travail, Fabric accède à l’itinéraire défini dans le manifeste front-end, sous artifacts>editor>path :

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

Lorsque vous appelez itemCrud.getItem, les données sont chargées à partir du back-end Fabric et du back-end de charge de travail. Les données des deux sources sont chargées dans l’objet artifactItem de l’interface graphique utilisateur ouverte.

Capture d’écran de l’ouverture d’éléments existants dans l’espace de travail.

UPDATE

Pour mettre à jour un élément existant itemCrud.updateItem. La charge utile de charge de travail est mise à jour par le serveur principal de charge de travail. Dans Fabric, seul le lastModifiedTime de l’élément change après une mise à jour.

DELETE

Vous pouvez appeler l’opération delete à partir de l’affichage Espace de travail de Fabric en tant qu’action générale disponible pour tous les éléments, ou via un appel explicite de la charge de travail vers itemCrud.deleteItem.

Les deux types d’appels finissent par passer par le rappel de onDeleteItem du back-end de charge de travail.

Afficher l’activité d’authentification

Dans l’exemple d’éditeur de charge de travail, vous pouvez afficher l’activité d’authentification.

Avant d’utiliser l’API d’authentification, configurez votre application pour l’authentification à l’aide de Microsoft Entra ID.

Vérifiez également que votre fichier env.dev est correctement configuré. Pour plus d’informations, consultez Configurer le manifeste local de la charge de travail et acquérir un jeton pour votre application.

Déboguer

Pour afficher les éléments Worker et Interface utilisateur iframe, dans le navigateur, sélectionnez F12 pour ouvrir les outils de développement du navigateur. Sélectionnez l'onglet Options.

Capture d’écran du débogage de fichiers dans Visual Studio Code.

Vous pouvez placer un point d’arrêt dans l’élément iframe Worker et voir le principal switch sur l’action entrante. Vous pouvez également déboguer l’élément iframe Interface utilisateur. Par exemple, vous pouvez déboguer le code à l’intérieur de SampleWorkloadEditor.

Contrôles Fluent UI

Les charges de travail d’expérience utilisateur utilisent des contrôles Fluent IU pour assurer la cohérence visuelle avec Fabric et faciliter le développement. L’exemple de projet de charge de travail fournit des exemples d’utilisation des contrôles les plus courants.

Pour en savoir plus, consultez Fluent UI.

Personnalisation du manifeste du front-end

Le manifeste front-end décrit les aspects front-end de la charge de travail : apparence du produit, noms, ressources visuelles et actions disponibles. Le manifeste front-end est le point de contact principal entre Fabric et la charge de travail.

Pour notre exemple de charge de travail, le manifeste est chargé dans Fabric en mode Développeur. Les sections de manifeste, les définitions et les exemples du manifeste sont affichées dans les fichiers manifeste front-end.

Les modifications apportées aux entrées, aux paramètres d’action et aux mises à jour du manifeste sont affichées en temps réel après l’actualisation de la page.

API prises en charge par le SDK client

Les API suivantes sont prises en charge :

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

Pour plus d’informations, consultez Package @ms-fabric/workload-client.

Partager via

Étendre le serveur frontal Microsoft Fabric

Prérequis

Activer la fonctionnalité de développement de charge de travail dans Fabric

Configurer le front-end

Exemple « Hello World »

Comprendre le code

bootstrap()

index.worker

index.ui

Flux de développement

Opérations CRUD

CREATE

GET

UPDATE

DELETE

Afficher l’activité d’authentification

Déboguer

Contrôles Fluent UI

Personnalisation du manifeste du front-end

API prises en charge par le SDK client

Commentaires

Ressources supplémentaires

Partager via

Étendre le serveur frontal Microsoft Fabric

Prérequis

Activer la fonctionnalité de développement de charge de travail dans Fabric

Configurer le front-end

Exemple « Hello World »

Comprendre le code

bootstrap()

index.worker

index.ui

Flux de développement

Opérations CRUD

CREATE

GET

UPDATE

DELETE

Afficher l’activité d’authentification

Déboguer

Contrôles Fluent UI

Personnalisation du manifeste du front-end

API prises en charge par le SDK client

Contenu connexe

Commentaires

Ressources supplémentaires