Extensión del front-end de Microsoft Fabric

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 aloja y ejecuta el proyecto dentro de un elemento <iframe> 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

El administrador de inquilinos debe primero activar la función de desarrollo de carga de trabajo en los entornos de inquilinos. 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 selector del tenant 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 para el 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 dirige 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: Los contratos y modelos que utiliza la interfaz de usuario y para la comunicación con el backend de la plantilla.
- 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 "Hello World":

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 invocar 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 workload de ejemplo está alojada en un elemento aislado de Fabric iframe que se muestra en el modo de desarrollador 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 inicializar, compruebe la ruta para ver si debe 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.

Las acciones pueden ser enviadas por la carga de trabajo a Fabric y, a continuación, devolver la llamada al controlador onAction, o bien puede iniciarlas el host de Fabric. 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 actual de objectId del área de trabajo también se transmite a la experiencia exclusiva del frontend.

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 a la API, pase el identificador del SDK workloadClient, que se utiliza 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 la cinta de opciones y los controles de 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 la interfaz de usuario llaman a las funciones 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>

Manejador:

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 servidor back-end está operativo y el tipo Org.WorkloadSample.SampleWorkloadItem está registrado en Fabric, se pueden realizar operaciones CRUD con este tipo.

Las siguientes operaciones se exponen mediante la API ItemCrud.

CREAR

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.

ACTUALIZAR

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

ELIMINAR

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

Ambos tipos de llamadas se procesan a través de la función de devolución de llamada onDeleteItem del backend de la 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 .

Captura 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 frontend es el principal punto de contacto 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.

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-04-29