Estender o front-end do Microsoft Fabric

Você pode usar o Microsoft Fabric Workload Development Kit para criar cargas de trabalho e criar recursos personalizados que estendem a experiência do Fabric. A plataforma Fabric foi projetada para ser interoperável com recursos de ISV (fornecedor independente de software). Por exemplo, pode usar o editor de itens para criar uma experiência de utilizador nativa e consistente ao incorporar a interface de um ISV no contexto de um item de um espaço de trabalho do Fabric.

Neste artigo, utiliza o repositório de exemplos para desenvolvimento de cargas de trabalho do Microsoft Fabric como orientação para integrar uma aplicação Web de carga de trabalho de UX personalizada com o Microsoft Fabric. O projeto e os exemplos detalhados ajudam você a integrar perfeitamente seus próprios componentes e ações da interface do usuário no ambiente de tempo de execução do Fabric para experimentação e personalização eficientes.

O front-end do projeto de exemplo de carga de trabalho UX é uma aplicação Web padrão em React que incorpora o SDK do cliente de carga de trabalho, como um pacote npm padrão, para disponibilizar funcionalidades.

O ISV aloja e executa o projeto dentro de um elemento <iframe> isolado no portal do Fabric. Ele apresenta experiências de interface do usuário específicas do ISV, incluindo um editor de itens.

O SDK fornece todas as interfaces, APIs e funções de bootstrap necessárias para transformar um aplicativo Web regular em um micro aplicativo Web frontend que opera perfeitamente no portal Fabric.

O SDK fornece um projeto de carga de trabalho de UX de exemplo. A amostra:

• Mostra como usar a maioria das chamadas SDK disponíveis.
• Demonstra um exemplo do friso extensível baseado no Fluent UI que corresponde ao aspeto e comportamento do Fabric.
• Permite fácil personalização.
• Permite observar as alterações no Fabric em tempo real quando o modo de desenvolvedor do Fabric está ativado.

Pré-requisitos

• Aplicação web de carga de trabalho de UX

  Este pacote baseia-se em Fluent UI e foi concebido para React.

• Manifesto de front-end da carga de trabalho de UX

  O manifesto de front-end da carga de trabalho de UX é um recurso em JSON fornecido pelo ISV. O arquivo contém informações essenciais sobre a carga de trabalho, incluindo a URL do aplicativo Web de carga de trabalho e vários detalhes da interface do usuário, como o nome para exibição do item ISV e ícones associados. O ISV pode usar o arquivo de manifesto para personalizar o que acontece quando os usuários interagem com itens no portal de malha.

Neste pacote, os ficheiros de manifesto do frontend estão localizados na pasta package. O arquivo de manifesto contém uma descrição detalhada do manifesto da carga de trabalho e seus componentes.

Habilite o recurso de desenvolvimento de carga de trabalho no Fabric

O administrador de inquilinos deve primeiro ativar a funcionalidade de desenvolvimento de carga de trabalho nas configurações de inquilino. O recurso pode ser habilitado para toda a organização ou para grupos específicos dentro da organização. Para que um administrador do inquilino ative a funcionalidade de desenvolvimento de cargas de trabalho para grupos específicos, conclua os passos descritos em Ativar a definição de inquilino de desenvolvimento.

Configurar o frontend

Para configurar o frontend do projeto de exemplo:

1. Verifique se Node.js e npm estão instalados. A instalação do npm deve ser a versão 9 ou posterior. Caso contrário, instale as versões mais recentes do Node.js e npm.

2. Clone o repositório de exemplo para desenvolvimento de workloads do Microsoft Fabric.

   A lista a seguir descreve o layout do diretório de pacotes, componentes e recursos:

   • Pacote: O local do pacote de carga de trabalho. O pacote contém recursos de frontend, incluindo manifestos e ativos.
   • src: O código da carga de trabalho, que inclui estes recursos:
     • index.ts: O arquivo de inicialização principal, incluindo bootstrap e o index.worker e index.ui iFrames (consulte os detalhes mais adiante neste artigo).
     • App.tsx: Este arquivo roteia caminhos para páginas. Por exemplo, /sample-workload-editor é encaminhado para a função SampleWorkloadEditor em components.
     • assets: o local das imagens (.jpg, .jpeg e png) que podem ser referenciadas no manifesto e mostradas na interface do usuário. Por exemplo, assets/github.jpg é definido no manifesto como o ícone do produto.
     • componentes: o local do código da interface do usuário, incluindo a exibição do editor e outras exibições que o exemplo usa (a faixa de opções, a página de autenticação e os painéis).
     • controller: O controlador invoca as APIs do SDK.
     • models: Os contratos e modelos utilizados pela interface do utilizador e para a comunicação com o back-end do boilerplate.
   • ferramentas: elementos que você pode usar para criar definições e configurações.
     • webpack.config.js: Use este arquivo para configurar o servidor Node.js local.
     • Uma configuração web e um leitor/processador de manifesto.
   • validação: O exemplo utiliza validateSchema.js para validar os esquemas dos ficheiros JSON de produtos e itens. Está configurado para ser executado em npm start.

3. Dentro da pasta do repositório, vá para a pasta Frontend para instalar os arquivos do projeto:

   <repository folder>\Frontend> npm install
   

4. Inicie o servidor executando o seguinte comando:

   <repository folder>\Frontend> npm start
   

   Este comando inicia um servidor Node.js local (usando webpack) ao qual o Microsoft Fabric se conecta quando está no modo de desenvolvedor.

   Para obter informações sobre os detalhes da porta que aparecem depois que o servidor é iniciado, consulte as notas do servidor host local.

   A porta atual é 60006.

   Depois de o servidor localhost ser iniciado, aceda ao URL 127.0.0.1:60006/manifests para abrir o manifesto agregado que é criado na pasta Frontend/Package.

   Se você alterar arquivos dentro da pasta Frontend/Package , execute npm start novamente.

   Essa configuração é mantida no navegador atual.

   

Exemplo de "Olá mundo"

Para executar um cenário de teste "hello world":

1. Inicie o servidor local (siga as etapas em Introdução para executar os exemplos de carga de trabalho de front-end e back-end) e verifique se o modo de desenvolvedor está habilitado.

2. No menu do espaço de trabalho, selecione o ícone Criar hub (por vezes, o ícone encontra-se nas reticências Mostrar mais).

   

3. Selecione Ver tudo.

   

4. Em Carga de trabalho de exemplo, selecione o cartão Item de exemplo para criar um item.

   

O novo item é semelhante a este exemplo:

Explore os vários controles para ver os recursos da API Fabric WorkloadClient (o SDK da carga de trabalho):

• Abrir notificações e caixas de diálogo
• Ir para as páginas
• Obter configurações de tema e carga de trabalho
• Executar ações

A maioria das funcionalidades SDK disponíveis são configuradas como ações de botão ou registradas como retornos de chamada. Os resultados normalmente são uma notificação ou uma caixa de mensagem que mostra que uma API foi invocada.

Por exemplo:

• Executar uma ação chama a API action.execute() com uma ação chamada exemplo. Ação. A funcionalidade da ação é mostrar uma notificação.

• Selecione Salvar na faixa de opções para chamar a API dialog.open(). A API abre uma caixa de diálogo na qual um usuário insere um nome e salva o item na malha. Para obter mais informações sobre a caixa de diálogo, consulte a secção CRUD.

• O botão Obter definições do tema mostra uma lista de configurações de tema do Fabric (através da API theme.get()).

A interface de utilizador da carga de trabalho de exemplo está alojada num elemento Fabric isolado iframe que é apresentado no modo de programador da página Web.

Compreender o código

As seções a seguir descrevem os elementos de código e considerações relevantes.

bootstrap()

Antes da inicialização, verifique o caminho para confirmar se é necessário fechar a janela. Esta etapa é necessária se você usar a API de autenticação .

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

Cada aplicativo de carga de trabalho do Fabric deve oferecer suporte à inicialização em dois modos:

• Modo de interface do usuário: um aplicativo no modo de interface do usuário é carregado em iFrames visíveis. Ele escuta suas próprias alterações de rota para renderizar os componentes correspondentes da interface do usuário, como páginas, painéis e caixas de diálogo.

• Modo de trabalho: um aplicativo no modo de trabalho é executado em um iFrame invisível. O iFrame invisível é usado principalmente para receber comandos externos e, em seguida, responder a eles.

A @ms-fabric/workload-client API fornece um bootstrap() método para simplificar as etapas de inicialização. O bootstrap() método deteta internamente se o aplicativo atual é carregado no modo de interface do usuário ou no modo de trabalho. Em seguida, ele chama o método de inicialização apropriado (initializeUI ou initializeWorker). Quando a inicialização estiver concluída, bootstrap() notificará a estrutura de microfrontend da malha sobre o sucesso ou falha da inicialização.

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

index.trabalhador

index.worker é o registo principal onAction . Ele lida com eventos que o host da malha envia, que são acionados por ações executadas.

As ações podem ser enviadas pela carga de trabalho para o Fabric e, em seguida, chamadas de volta para o onAction manipulador, ou podem ser iniciadas pelo host do Fabric. Por exemplo, quando seleciona Criar Item de Exemplo - Apenas Frontend, o Fabric aciona a ação open.createSampleWorkloadFrontendOnly, e o processador onAction inicia a abertura da página principal da IU da carga de trabalho. O valor atual do espaço de trabalho objectId também é passado para a experiência somente frontend.

A sequência é mostrada no exemplo de código a seguir:

   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

A initialize() função renderiza o React DOM onde a App função está incorporada. Para invocar as chamadas de API, passe o workloadClient identificador SDK, que é usado em todo o código.

A FluentProvider classe garante consistência de estilo entre os vários controles FluentUI. Eis um exemplo:

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

Fluxo de desenvolvimento

• A App função roteia o código para SampleWorkloadEditor. A função retorna um valor para React.JSX.Element.
• A função contém a estrutura da interface do usuário. A estrutura da interface do utilizador contém o friso e os controlos da página, como botões e campos de entrada.
• As informações coletadas do usuário são armazenadas por meio do gancho React useState() .
• Os manipuladores dos controles da interface do usuário chamam as SampleWorkloadController funções e passam as variáveis de estado relevantes.
• Para suportar as operações CRUD, o estado do item criado/carregado é armazenado em artifactItem com workspaceObjectId e uma implementação de exemplo de variáveis de payload.

Os exemplos a seguir usam a API notification.open():

• Estado:

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

• Interface do usuário:

  Estes exemplos configuram elementos específicos da interface do usuário:

  • 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ão Enviar:

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

  • Manipulador:

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

• Responsável pelo tratamento:

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

Operações CRUD

Embora um cenário de desenvolvimento somente frontend seja facilmente suportado, a experiência completa do desenvolvedor de ponta a ponta requer salvar, ler e editar itens de carga de trabalho existentes.

O guia de implementação de back-end descreve em detalhes como configurar e usar o back-end.

Quando o back-end estiver em execução e o Org.WorkloadSample.SampleWorkloadItem tipo estiver registrado no Fabric, você poderá executar operações CRUD nesse tipo.

As operações a seguir são expostas usando a API ItemCrud.

CRIAR

Para efetuar uma chamada de exemplo para create, utilize o exemplo seguinte, que mostra como guardar o item da carga de trabalho pela primeira vez:

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

Nossa implementação de exemplo armazena o item criado no artifactItem.

O item é criado no espaço de trabalho selecionado no momento. O espaço de trabalho deve ser atribuído à capacidade definida na configuração de back-end. Para obter mais informações, consulte a documentação de back-end.

Uma tentativa de criar um item em um espaço de trabalho não compatível falha:

• O onCreateFabricItem callback no backend bloqueia a chamada CREATE. Uma falha nesse ponto faz com que a operação falhe e nenhum item é criado na malha. Para obter mais informações, consulte a documentação de depuração e solução de problemas do back-end.

• Atualmente, um item salvo não aparece automaticamente no espaço de trabalho. Para exibir um item salvo no espaço de trabalho, atualize a página.

GET

Quando seleciona um item de exemplo de carga de trabalho existente na vista do espaço de trabalho, o Fabric acede à rota definida no manifesto do front-end em artifacts>editor>path:

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

Ao invocar itemCrud.getItem, os dados são carregados a partir do back-end do Fabric e do back-end da carga de trabalho. Os dados de ambas as fontes são carregados no artifactItem objeto da GUI aberta.

ATUALIZAR

Para atualizar um item existente, use itemCrud.updateItem. O conteúdo da workload é atualizado pelo backend da workload. No Fabric, apenas o lastModifiedTime do item muda após uma atualização.

Eliminar

Pode invocar a operação delete quer na vista do espaço de trabalho do Fabric, como uma ação geral disponível para todos os itens, quer através de uma chamada explícita do workload para itemCrud.deleteItem.

Ambos os tipos de chamadas passam pela função onDeleteItem callback do back-end da carga de trabalho.

Exibir atividade de autenticação

No editor de carga de trabalho de exemplo, você pode exibir a atividade de autenticação.

Antes de usar a API de autenticação, configure seu aplicativo para autenticação usando a ID do Microsoft Entra.

Verifique também se o arquivo env.dev está configurado corretamente. Para obter mais informações, consulte Configurar o manifesto local da carga de trabalho e adquirir um token para seu aplicativo.

Depurar

Para ver os elementos worker e UI iframe, no navegador, selecione F12 para abrir as ferramentas de desenvolvedor do navegador. Selecione o separador Fontes.

Pode definir um ponto de interrupção no elemento iframe do worker e ver o switch principal na ação recebida. Você também pode depurar o elemento iframe da interface do usuário. Por exemplo, pode depurar o código dentro de SampleWorkloadEditor.

Controlos do Fluent UI

As cargas de trabalho de UX usam controles Fluent UI para consistência visual com o Fabric e para facilitar o desenvolvimento. O projeto de carga de trabalho de exemplo fornece exemplos de como usar os controles mais comuns.

Para obter mais informações, consulte Fluent UI.

Personalização do manifest do frontend

O manifesto de frontend descreve os aspetos de frontend da carga de trabalho, incluindo aparência do produto, nomes, ativos visuais e ações disponíveis. O manifesto de frontend é o principal ponto de contato entre o Fabric e a carga de trabalho.

Para o nosso workload de exemplo, o manifesto é carregado no Fabric em modo de Desenvolvedor. As secções, definições e exemplos do manifesto são apresentados nos ficheiros de manifesto de frontend.

As alterações nas entradas do manifesto, nas configurações de ação e nas atualizações dos ativos visuais são mostradas em tempo real após a atualização da página.

APIs suportadas pelo SDK do cliente

As seguintes APIs são suportadas:

• notificação.abrir
• notification.ocultar
• abrir.painel
• panel.fechar
• action.onAction
• action.execute
• navegação.navegar
• navigation.onNavegar
• navigation.onBeforeNavigateAway
• navigation.onAfterNavigateAway
• página.abrir
• dialog.openDialog
• dialog.openMessageBox
• diálogo.fechar
• theme.get
• theme.onChange
• configurações.get
• definições.onChange
• errorHandling.openErrorDialog
• errorHandling.handleRequestFailure
• itemCrud.createItem
• itemCrud.getItem
• itemCrud.updateItem
• itemCrud.deleteItem
• itemSchedule.runItemJob
• itemSchedule.cancelItemJob
• itemRecentRuns.open

Para obter mais informações, consulte @ms-fabric/workload-client package.

Conteúdos relacionados

• Visão geral do Kit de Desenvolvimento de Carga de Trabalho
• Guia de configuração de back-end