Extensión del front-end de Microsoft Fabric

Artículo
12/03/2024

Puede usar el Kit de desarrollo de cargas de trabajo de Microsoft Fabric para crear cargas de trabajo y crear funcionalidades personalizadas que amplíen la experiencia de Fabric. La plataforma de Fabric está diseñada para ser interoperable con funcionalidades de proveedor de software independiente (ISV). Por ejemplo, puede usar el editor de elementos para crear una experiencia de usuario nativa y coherente mediante la inserción del front-end de un ISV en el contexto de un elemento de área de trabajo de Fabric.

En este artículo, usará el repositorio de ejemplo de desarrollo de cargas de trabajo de Microsoft Fabric como guía para integrar una aplicación web de carga de trabajo de experiencia de usuario personalizada con Microsoft Fabric. El proyecto y los ejemplos detallados le ayudan a integrar sin problemas sus propios componentes y acciones de la interfaz de usuario en el entorno en tiempo de ejecución de Fabric para una experimentación y personalización eficaces.

El front-end del proyecto de carga de trabajo de la experiencia del usuario de ejemplo es una aplicación web estándar de React que incorpora el SDK de cliente de carga de trabajo (como un paquete npm estándar) para proporcionar funcionalidad.

El ISV hospeda y ejecuta el proyecto dentro de un elemento <iframe> en espacio aislado en el portal de Fabric. Presenta experiencias de interfaz de usuario específicas del ISV, incluido un editor de elementos.

El SDK proporciona todas las interfaces, API y funciones de arranque que se necesitan para transformar una aplicación web normal en una microaplicación web de front-end que funciona sin problemas en el portal de Fabric.

El SDK proporciona un proyecto de carga de trabajo de experiencia de usuario de ejemplo. El ejemplo :

Muestra cómo usar la mayoría de las llamadas del SDK disponibles.
Muestra un ejemplo de la cinta extensible basada en la UI de Fluent que coincide visualmente con el aspecto y comportamiento de Fabric.
Permite una personalización sencilla.
Permite observar los cambios en Fabric en tiempo real cuando está activado el modo para desarrolladores de Fabric.

Requisitos previos

Aplicación web de carga de trabajo de experiencia de usuario

Este paquete se basa en la interfaz de usuario de Fluent y está diseñado para React.
Manifiesto del front-end de carga de trabajo de experiencia de usuario

El manifiesto del front-end de carga de trabajo de experiencia de usuario es un recurso JSON que proporciona el ISV. El archivo contiene información esencial sobre la carga de trabajo, incluida la dirección URL de la aplicación web de carga de trabajo y varios detalles de la interfaz de usuario, como el nombre para mostrar del elemento de ISV y los iconos asociados. El ISV puede usar el archivo de manifiesto para personalizar lo que sucede cuando los usuarios interactúan con los elementos en el portal de Fabric.

En este paquete, los archivos de manifiesto del front-end se encuentran en la carpeta package. El archivo de manifiesto contiene una descripción detallada del manifiesto de la carga de trabajo y sus componentes.

Habilitación de la característica de desarrollo de cargas de trabajo en Fabric

En primer lugar, el administrador de inquilinos debe habilitar la característica de desarrollo de cargas de trabajo en el portal de administración de Microsoft Fabric. La característica se puede habilitar para toda la organización o para grupos específicos de la organización. En el caso de un administrador de inquilinos, para habilitar la característica de desarrollo de cargas de trabajo para grupos específicos, complete los pasos descritos en Habilitación de la configuración de inquilino de desarrollo.

Captura de pantalla del conmutador del inquilino de desarrollo de cargas de trabajo.

Configuración del front-end

Para configurar el front-end del proyecto de ejemplo:

Compruebe que estén instalados Node.js y npm. La instalación de npm debe ser la versión 9 o posterior. De lo contrario, instale las versiones más recientes de Node.js y npm.
Clone el repositorio de ejemplo de desarrollo de cargas de trabajo de Microsoft Fabric.

En la lista siguiente, se describen el diseño de directorios del paquete, los componentes y los recursos:
- Package: ubicación del paquete de carga de trabajo. El paquete contiene los recursos de front-end, incluidos manifiestos y recursos.
- src: código de la carga de trabajo, que incluye estos recursos:
  - index.ts: archivo de inicialización principal, incluidos bootstrap y los iFrames de index.worker e index.ui (consulte los detalles más adelante en este artículo).
  - App.tsx: este archivo enruta las rutas de acceso a las páginas. Por ejemplo, /sample-workload-editor se enruta a la función SampleWorkloadEditor en components.
  - assets: ubicación para imágenes (.jpg, .jpeg y png) a la que se puede hacer referencia en el manifiesto y mostrarse en la interfaz de usuario. Por ejemplo, assets/github.jpg se establece en el manifiesto como el icono del producto.
  - components: ubicación del código de la interfaz de usuario, incluida la vista del editor y otras vistas que se usan en el ejemplo (la cinta de opciones, la página de autenticación y los paneles).
  - controller: el controlador llama a las API del SDK.
  - models: contratos y modelos que usa la UI y también para la comunicación con el back-end reutilizable.
- tools: elementos que puede utilizar para crear ajustes y configuraciones.
  - webpack.config.js: use este archivo para configurar el servidor local de Node.js.
  - Configuración web y lector/procesador de manifiestos.
- validation: el ejemplo usa validateSchema.js para validar los esquemas de archivo JSON de producto y elementos. Se ha configurado para ejecutarse en npm start.
Dentro de la carpeta del repositorio, vaya a la carpeta Frontend para instalar los archivos del proyecto:
```
<repository folder>\Frontend> npm install
```
Ejecute el comando siguiente para iniciar el servidor:
```
<repository folder>\Frontend> npm start
```
Este comando inicia un servidor local de Node.js (mediante webpack) al que se conecta Microsoft Fabric cuando está en modo para desarrolladores.

Para obtener información sobre los detalles de los puertos que aparecen tras el inicio del servidor, consulte las notas del servidor host local.

El puerto actual es 60006.

Una vez iniciado el servidor localhost, vaya a la dirección URL 127.0.0.1:60006/manifests para abrir el manifiesto agregado que se crea en la carpeta Frontend/Package.

Si cambia los archivos que hay dentro de la carpeta Frontend/Package, ejecute de nuevo npm start.

Esta configuración se mantiene en el navegador actual.

Ejemplo de "Hola mundo"

Para ejecutar un escenario de prueba de "Hola mundo":

Inicie el servidor local (siga los pasos descritos en Introducción para ejecutar los ejemplos de carga de trabajo de front-end y back-end) y asegúrese de que esté habilitado el modo para desarrolladores.
En el menú del área de trabajo, seleccione el icono Crear centro (a veces el icono se encuentra en los puntos suspensivos Mostrar más).
Seleccionar Ver todo.
En Carga de trabajo de ejemplo, seleccione la tarjeta Elemento de ejemplo para crear un elemento.

El nuevo elemento tiene un aspecto similar al de este ejemplo:

Captura de pantalla de la imagen de la interfaz de usuario de ejemplo principal.

Explore los distintos controles para ver las funcionalidades de la API WorkloadClient de Fabric (el SDK de carga de trabajo):

Abrir notificaciones y cuadros de diálogo
Ir a páginas
Obtener la configuración del tema y la carga de trabajo
Ejecutar acciones

La mayoría de las funcionalidades disponibles en el SDK se configuran como acciones de botón o se registran como devoluciones de llamada. Los resultados suelen ser una notificación o un cuadro de mensaje que muestra que se ha invocado una API.

Por ejemplo:

Ejecutar una acción llama a la API action.execute() con una acción llamada sample.Action. La funcionalidad de la acción es mostrar una notificación.
Seleccione Guardar en la cinta de opciones para llamar a la API dialog.open(). La API abre un cuadro de diálogo en el que un usuario escribe un nombre y guarda el elemento en Fabric. Para obtener más información sobre el cuadro de diálogo, consulte la sección sobre CRUD.
El botón Obtener configuración del tema muestra una lista de configuraciones de temas de Fabric (mediante la API theme.get()).

La interfaz de usuario de la carga de trabajo de ejemplo se hospeda en un elemento iframe en espacio aislado de Fabric que se muestra en el modo para desarrolladores de la página web.

Captura de pantalla de la imagen insertada de IFrame.

Nota:

El elemento iframe en espacio aislado admite los atributos allow-same-origin y allow-scripts.

Para obtener más información sobre el espacio aislado y los atributos, consulte la documentación web de MDN.

Comprendiendo el código

En las secciones siguientes, se describen los elementos de código y las consideraciones pertinentes.

bootstrap()

Antes de arrancar, consulte la ruta de acceso para comprobar si tiene que cerrar la ventana. Este paso es obligatorio si usa la API de autenticación.

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

Todas las aplicaciones de carga de trabajo de Fabric deben admitir la inicialización en dos modos:

Modo de interfaz de usuario: una aplicación en modo de interfaz de usuario se carga en iFrames visibles. La aplicación escucha sus propios cambios de ruta para representar los componentes de interfaz de usuario correspondientes, como páginas, paneles y cuadros de diálogo.
Modo de trabajo: una aplicación en modo de trabajo se ejecuta en un iFrame invisible. El iFrame invisible se utiliza principalmente para recibir comandos externos y responder a ellos.

La API @ms-fabric/workload-client proporciona el método bootstrap() para simplificar los pasos de inicialización. El método bootstrap() detecta internamente si la aplicación actual se ha cargado en modo de interfaz de usuario o en modo de trabajo. A continuación, llama al método de inicialización adecuado (initializeUI o initializeWorker). Una vez completada la inicialización, bootstrap() notifica al marco de microfront-end de Fabric si la inicialización ha sido correcta o con errores.

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

index.worker

index.worker es el registro principal de onAction. Controla los eventos que envía el host de Fabric, que se desencadenan mediante las acciones ejecutadas.

La carga de trabajo puede enviar las acciones a Fabric y, a continuación, volver a llamar al controlador onAction, o bien el host de Fabric las puede iniciar. Por ejemplo, al seleccionar Crear elemento de ejemplo: solo front-end, Fabric desencadena la acción open.createSampleWorkloadFrontendOnly y el controlador onAction inicia la apertura de la página principal de la interfaz de usuario de la carga de trabajo. El valor de objectId del área de trabajo actual también se pasa a la experiencia de solo front-end.

La secuencia se muestra en el ejemplo de código siguiente:

   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 función initialize() representa el DOM de React donde se inserta la función App. Para invocar las llamadas API, pasamos el controlador del SDK workloadClient que se usa en todo el código.

La clase FluentProvider es garantiza la coherencia de estilo en los distintos controles de FluentUI. Este es un ejemplo:

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

Flujo de desarrollo

La función App enruta el código a SampleWorkloadEditor. La función devuelve un valor para React.JSX.Element.
La función contiene la estructura de la interfaz de usuario. La estructura de la interfaz de usuario contiene los controles de la cinta de opciones y la página, como botones y campos de entrada.
La información que se recopila del usuario se almacena mediante el enlace useState() de React.
Los controladores de los controles de la interfaz de usuario llaman a las funciones de SampleWorkloadController y pasan las variables de estado pertinentes.
Para admitir las operaciones CRUD, el estado del elemento creado o cargado se almacena en artifactItem con workspaceObjectId y una implementación de ejemplo de las variables de la carga útil.

En los ejemplos siguientes, se usa la API notification.open():

Estado:

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

IU:

Estos ejemplos configuran elementos específicos de la interfaz de usuario:

Título:

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

Botón Enviar:

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

Controlador:

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

Controlador:

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

Operaciones CRUD

Aunque se admite fácilmente un escenario de desarrollo de solo front-end, la experiencia completa para desarrolladores de un extremo a otro requiere guardar, leer y editar elementos de carga de trabajo existentes.

En la guía de implementación del back-end, se describe detalladamente cómo configurar y usar el back-end.

Cuando el back-end está en funcionamiento y el tipo Org.WorkloadSample.SampleWorkloadItem está registrado en Fabric, puede realizar operaciones CRUD en este tipo.

Las siguientes operaciones se exponen mediante la API ItemCrud.

CREATE

Para realizar una llamada de ejemplo a create, utilice el siguiente ejemplo que muestra cómo guardar el elemento de carga de trabajo por primera vez:

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

Nuestra implementación de ejemplo almacena el elemento creado en artifactItem.

El elemento se crea en el área de trabajo seleccionada actualmente. El área de trabajo se debe asignar a la capacidad establecida en la configuración del back-end. Para obtener más información, consulte la documentación del back-end.

Se produce un error en el intento de crear un elemento en un área de trabajo no compatible:

La devolución de llamada a onCreateFabricItem en el back-end bloquea la llamada a CREATE. Un error en ese momento hace que se produzca un error en la operación y no se crea ningún elemento en Fabric. Para obtener más información, consulte la documentación sobre depuración y solución de problemas del back-end.
Actualmente, los elementos guardados no aparecen automáticamente en el área de trabajo. Para ver un elemento guardado en el área de trabajo, actualice la página.

GET

Al seleccionar un elemento de carga de trabajo de ejemplo existente en la vista del área de trabajo, Fabric va a la ruta definida en el manifiesto del front-end, en artifacts>editor>path:

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

Al invocar a itemCrud.getItem, los datos se cargan tanto desde el back-end de Fabric como desde el back-end de la carga de trabajo. Los datos de ambos orígenes se cargan en el objeto artifactItem de la GUI abierta.

Captura de pantalla de la apertura de elementos existentes en el área de trabajo.

UPDATE

Para actualizar un elemento existente, use itemCrud.updateItem. El back-end de la carga de trabajo actualiza la carga útil de la carga de trabajo. En Fabric, después de una actualización, solo cambia el valor de lastModifiedTime del elemento.

Delete

Puede llamar a la operación delete en la vista de área de trabajo de Fabric como una acción general disponible para todos los elementos o mediante una llamada explícita desde la carga de trabajo a itemCrud.deleteItem.

Ambos tipos de llamadas pasan por la devolución de llamada onDeleteItem del back-end de carga de trabajo.

Visualización de la actividad de autenticación

En el editor de la carga de trabajo de ejemplo, puede ver la actividad de autenticación.

Antes de usar la API de autenticación, configure la aplicación para que se autentique mediante Microsoft Entra ID.

Asegúrese también de que el archivo env.dev esté configurado correctamente. Para obtener más información, consulte Configuración del manifiesto local de carga de trabajo y adquisición de un token para la aplicación.

Depurar

Para ver los elementos del iframe de la interfaz de usuario y de trabajo, en el explorador, seleccione F12 para abrir las Herramientas de desarrollo del explorador. Seleccione la pestaña Orígenes .

Recorte de pantalla de los archivos de depuración en Visual Studio Code.

Puede colocar un punto de interrupción en el elemento iFrame de trabajo y ver el switch principal en la acción entrante. También puede depurar el elemento iframe de la interfaz de usuario. Por ejemplo, puede depurar el código que hay dentro de SampleWorkloadEditor.

Controles de la interfaz de usuario de Fluent

Las cargas de trabajo de experiencia del usuario usan controles de la UI de Fluent para proporcionar coherencia visual con Fabric y para facilitar el desarrollo. El proyecto de carga de trabajo de ejemplo proporciona ejemplos de cómo usar los controles más comunes.

Para obtener más información, consulte Fluent UI.

Personalización del manifiesto del front-end

El manifiesto del front-end describe los aspectos de front-end de la carga de trabajo, como la apariencia del producto, los nombres, los recursos visuales y las acciones disponibles. El manifiesto del front-end es el punto de contacto principal entre Fabric y la carga de trabajo.

En el caso de nuestra carga de trabajo de ejemplo, el manifiesto se carga en Fabric en modo para desarrolladores. Las secciones, definiciones y ejemplos del manifiesto se muestran en los archivos de manifiesto de front-end.

Los cambios en las entradas, la configuración de las acciones y las actualizaciones de los recursos visuales del manifiesto se muestran en tiempo real después de actualizar la página.

API compatibles con el SDK de cliente

Se admiten las siguientes API:

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

Para obtener más información, consulte el paquete @ms-fabric/workload-client.

Compartir a través de

Extensión del front-end de Microsoft Fabric

Requisitos previos

Habilitación de la característica de desarrollo de cargas de trabajo en Fabric

Configuración del front-end

Ejemplo de "Hola mundo"

Comprendiendo el código

bootstrap()

index.worker

index.ui

Flujo de desarrollo

Operaciones CRUD

CREATE

GET

UPDATE

Delete

Visualización de la actividad de autenticación

Depurar

Controles de la interfaz de usuario de Fluent

Personalización del manifiesto del front-end

API compatibles con el SDK de cliente

Comentarios

Recursos adicionales

Compartir a través de

Extensión del front-end de Microsoft Fabric

Requisitos previos

Habilitación de la característica de desarrollo de cargas de trabajo en Fabric

Configuración del front-end

Ejemplo de "Hola mundo"

Comprendiendo el código

bootstrap()

index.worker

index.ui

Flujo de desarrollo

Operaciones CRUD

CREATE

GET

UPDATE

Delete

Visualización de la actividad de autenticación

Depurar

Controles de la interfaz de usuario de Fluent

Personalización del manifiesto del front-end

API compatibles con el SDK de cliente

Contenido relacionado

Comentarios

Recursos adicionales