Súprava na vývoj vyťaženia tkaniny klientske (Preview)

Tento odkladací priestor ukážky vyťaženia služby Microsoft Fabric slúži ako sprievodca integráciou vlastného vyťaženia UX so službou Microsoft Fabric. Tento projekt umožňuje vývojárom bezproblémovo integrovať svoje vlastné komponenty a správanie používateľského rozhrania do prostredia runtime služby Fabric, čo umožňuje rýchle experimentovanie a prispôsobenie. Vývojári môžu použiť architektúru vývojovej súpravy služby Fabric na vytváranie vyťažení a vytváranie vlastných možností, ktoré rozširujú prostredie služby Fabric. Platforma Fabric je navrhnutá tak, aby bola interoperabilná s možnosťami nezávislých dodávateľov softvéru (ISV). Editor položiek napríklad umožňuje vytvoriť natívne a konzistentné používateľské prostredie vložením klientskej položky nezávislého dodávateľa softvéru do kontextu položky pracovného priestoru služby Fabric.

Rozhranie vyťaženia UX je štandardná webová aplikácia (React), ktorá zahŕňa našu súpravu SDK pre vyťaženie, štandardný balík npm, ktorý umožňuje jeho funkcie. Nezávislý dodávateľ softvéru ho hosťuje a prevádzkuje v rámci testovacieho prostredia (sandboxed) <iframe> na portáli služby Fabric. Predstavuje prostredie používateľského rozhrania špecifické pre nezávislých dodávateľov softvéru, napríklad editor položiek. Súprava SDK poskytuje všetky potrebné rozhrania, rozhrania API a funkcie bootstrap potrebné na transformáciu bežnej webovej aplikácie na webovú aplikáciu Micro Frontend, ktorá bezproblémovo funguje na portáli služby Fabric.

Súprava SDK poskytuje ukážkové používateľské rozhranie s nasledujúcimi funkciami:

• Vitríny využíva väčšinu dostupných volaní súpravy SDK
• Ukazuje príklad rozšíriteľného pásu s nástrojmi založeným na používateľskom rozhraní na základe fluent, ktorý zodpovedá vzhľadu a vzhľadu služby Fabric
• Umožňuje jednoduché prispôsobenie
• Umožňuje sledovať zmeny v službe Fabric v reálnom čase, zatiaľ čo v režime vývoja služby Fabric

Požiadavky

• Webová aplikácia UX Workload

  Tento balík je vytvorený na základe používateľského rozhrania Fluent a je určený pre knižnicu React.

• Klientsky manifest vyťaženia UX

  Klientsky manifest vyťaženia používateľského rozhrania je zdroj JSON, ktorý poskytuje nezávislý dodávateľ softvéru. Obsahuje základné informácie o vyťažení, ako je napríklad URL adresa webovej aplikácie pre vyťaženie a rôzne podrobnosti používateľského rozhrania, ako napríklad zobrazovaný názov položky ISV a príslušné ikony. Nezávislým dodávateľom softvéru tiež umožňuje prispôsobiť, čo sa stane, keď používatelia interagujú so svojimi položkami na portáli služby Fabric.

V tomto balíku sa súbory manifestu nachádzajú tu v priečinku Package ( Balík): Klientske súbory manifestu a podrobný popis nájdete v klientskych súboroch manifestu.

Krok 1: Povolenie vývojovej funkcie vyťaženia v službe Fabric

Správca nájomníka musí povoliť funkciu vývoja vyťažení na portáli na správu. Je možné ju povoliť v celej organizácii alebo pre konkrétne skupiny v rámci organizácie tým, že povolíte, aby správcovia kapacity prepli nájomníka, aby mohli vyvinúť ďalšie vyťaženia.

Krok č. 2: Nastavenie klientskej zostavy

Ak chcete nastaviť predný koniec ukážkového projektu, postupujte podľa týchto krokov:

1. Overte, či sú nainštalované a npm či npm je verzia aspoň 9 (Ak nie, nainštalujte najnovšie Node.js a npm)Node.js

2. Klonovanie odkladacieho priestoru: Klonujte odkladací priestor, ktorý sa nachádza tu: https://go.microsoft.com/fwlink/?linkid=2272254

   Toto je rozloženie adresára balíka s popisom základných súčastí a zdrojov:

   • Package – umiestnenie balíka vyťaženia: klientske zdroje vrátane manifestov a položiek.
   • src – kód vyťaženia:
     • index.ts – hlavný inicializačný súbor, bootstrap index.worker iFrames a index.ui – sú podrobne popísané nižšie
     • App.tsx – smerovanie ciest k stranám, napríklad – /sample-workload-editor je smerované do funkcie v SampleWorkloadEditor časti components
     • assets - location for images(jpg, jpeg, png), ktoré je možné odkazovať v manifeste a môžu sa zobrazovať v používateľskom rozhraní. Napríklad assets/github.jpg sa v manifeste nastaví ako ikona produktu.
     • súčasti – umiestnenie skutočného kódu používateľského rozhrania – zobrazenie editora a iné zobrazenia, ktoré používa ukážka (pás s nástrojmi, stránka overenia, panel atď.)
     • controller (prevádzkovateľ ) – prevádzkovateľ, ktorý volá rozhrania API súpravy SDK.
     • modely - zmluvy a modely používané samotným používateľského rozhrania a na komunikáciu s koncovým serverom brány
   • náradie -
     • webpack.config.js - konfigurácia lokálneho servera Node.js
     • Webová konfigurácia a manifest čítačka/procesor
   • validácia -
     • validateSchema.js – overenie schémy súborov product a item json. Je nakonfigurovaná tak, aby sa spúšťala na npm start.

3. Inštalovať

   V priečinku odkladacieho priestoru prejdite na Frontend a spustite inštaláciu npm

   <repository folder>\Frontend> npm install
   

4. Start Server

   <repository folder>\Frontend> npm start
   

   Tento príkaz spustí lokálny server Node.js (pomocou webpackpríkazu ), ku ktorému sa microsoft Fabric pripája v režime vývoja.

   Podrobnosti o porte, ktoré sa zobrazia po spustení, nájdete v poznámkach k serveru localhost. Aktuálny port je 60006. Po spustení servera localhost sa otvorí URL adresa: 127.0.0.1:60006/manifests načíta agregovaný manifest vytvorený z priečinka Frontend/Package. Otvorte ho a overte, či je server v prevádzke.

   Úpravou zdrojových súborov sa spustí opätovné načítanie obsahu v službe Fabric prostredníctvom webpack, ak už je pripojený. Zvyčajne však bude potrebné stranu aj naďalej obnovovať.

   Ak zmeníte súbory v priečinku Frontend/Package, mali by ste znova spustiť npm.

5. Spustite službu In Fabric, povoľte nastavenie režimu vývojára služby Fabric, aby mohla službe Fabric získať prístup k lokálnemu serveru. Prejdite do časti Nastavenia pre vývojárov -->Fabric Developer Mode a obnovte stránku. Toto nastavenie pretrváva v aktuálnom prehliadači.

   

Príklad použitia

Spustenie typického testovacieho scenára hello world :

1. Spustite lokálny server a povoľte funkciu Dev Mode. V ponuke v ľavom dolnom rohu by sa mala zobraziť nová vzorová vyťaženie:

   

2. Vyberte položku Vzorové vyťaženie a používateľa prejdite na domovskú stránku vzorového vyťaženia. Horná časť predstavuje prostredie na vytváranie :

   

3. Vyberte kartu Ukážka vyťaženia a otvorte používateľské rozhranie vzorového vyťaženia v rámci služby Fabric:

   

Preskúmajte rôzne ovládacie prvky a pozrite si možnosti rozhrania API (SDK) služby Fabric:

• Otvorenie oznámení a dialógových okien
• Prechod na stránky
• Získanie nastavení motívu a vyťaženia
• Vykonanie akcií

Väčšina dostupných funkcií súpravy SDK je buď napojená na akcie tlačidla, alebo sa zaregistruje ako spätné volania. Výsledky sú zvyčajne oznámením alebo poľom hlásenia, ktoré zobrazuje, že rozhranie API bolo vyvolané.

Napríklad:

• Akcia Vykonať vyvolá action.execute() rozhranie API s akciou s názvom ukážka. Akcia. Funkciou akcie je zobraziť oznámenie.
• Výberom položky Uložiť na páse s nástrojmi zavoláte dialog.open() rozhranie API, ktoré otvorí dialógové okno, v ktorom používateľ poskytne meno a uloží položku v službe Fabric (toto dialógové okno sa podrobnejšie skúma v časti CRUD).
• Tlačidlo Získať nastavenia motívu zobrazí zoznam konfigurácií motívov služby Fabric (cez rozhranie theme.get() API).

Ukážka používateľského rozhrania vyťaženia sa hosťuje v sandboxe iframe služby Fabric, kde môžeme vidieť, keď preskúmame dom stránky:

Poznámka

Izolovaný iframe povoľuje nasledujúce atribúty: allow-same-origin, allow-scripts. Ďalšie informácie o význame testovacieho prostredia (sandbox) a rôznych atribútoch nájdete v webových dokumentoch MDN.

Krok č. 3: Ponorte sa do kódu

bootstrap()

Pred spustením systému skontrolujte cestu, či nie je potrebné okno zatvoriť. Tento krok je potrebný pre rozhranie API na overenie .

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

Každá aplikácia fabric workload musí podporovať načítanie v dvoch režimoch:

• Režim používateľského rozhrania: Am app in UI mode is loaded in visible iFrames and listens for its own route changes to render corresponding UI components, including pages, panely, dialogs a tak ďalej.
• Režim pracovníka: Aplikácia v pracovnom režime sa spustí v neviditeľnom prvku iFrame, ktorý sa primárne používa na prijímanie príkazov odoslaných z vonkajšieho sveta a ich reagovanie. @ms-fabric/workload-client Poskytuje metódu bootstrap() na zjednodušenie krokov inicializácie. Metóda bootstrap() interne zistí, či sa aktuálna aplikácia načíta v režime používateľského rozhrania alebo pracovnom režime, a potom zavolá príslušnú metódu inicializácie (initializeUI alebo initializeWorker). Po dokončení inicializácie systém bootstrap() upozorní micro-klientsky rámec služby Fabric o úspešnej alebo neúspešnej inicializácii.

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

index.worker

Ide o hlavnú onAction registráciu. Spracováva udalosti odoslané od hostiteľa služby Fabric, ktoré sa samy o sebe spúšťajú vykonanými akciami. Tieto akcie môže byť odoslané buď samotným vyťažením do služby Fabric a následným spätného vyťaženia do onAction obslužného programu, alebo ich môže iniciovať hostiteľ služby Fabric. Napríklad po kliknutí na položku Vytvoriť vzorovú položku – iba na klientskom paneli spustí fabric akciu open.createSampleWorkloadFrontendOnly a obslužný program aplikácie spustí otvorenie hlavnej stránky používateľského rozhrania vyťaženia, ako je to znázornené v nasledujúcom kóde. Aktuálny pracovný priestor objectId sa odovzdáva aj do prostredia iba na klientskej úrovni.

   workloadClient.action.onAction((message) => {
        switch (message.action) {
            /**
             * This opens the Frontend-only experience, allowing to experiment with the UI without the need for CRUD operations.
             * This experience still allows saving the item, if the Backend is connected and registered
             */
            case 'open.createSampleWorkloadFrontendOnly':
                const { workspaceObjectId: workspaceObjectId1 } = data as ItemCreateContext;
                return workloadClient.page.open({
                    extensionName: 'Org.WorkloadSample',
                    route: {
                        path: `/sample-workload-frontend-only/${workspaceObjectId1}`,
                    },
                });

                // ... elided for brevity...
            default:
                throw new Error('Unknown action received');
        }
    });

index.ui

Funkcia vykreslí initialize() knižnicu React DOM, do ktorej App je funkcia vložená. Ak chcete vyvolať volania rozhrania API, odovzdajte rukoväť súpravy workloadClient SDK, ktorá sa používa v celom kóde. Trieda FluentProvider zaručuje konzistenciu štýlu v rôznych ovládacích prvkoch FluentUI.

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

Vývojový postup

• App smeruje kód do SampleWorkloadEditor, čo je funkcia vracajúca React.JSX.Element.
• Funkcia obsahuje štruktúru používateľského rozhrania (pás s nástrojmi a ovládacie prvky na stránke – tlačidlá, vstupné polia atď.).
• Informácie získané od používateľa sa ukladajú cez nástroj React's useState() hook.
• Obslužné programy ovládacích prvkov používateľského rozhrania zavolajú funkcie SampleWorkloadController a odovzdajú príslušné premenné stavu.
• Na podporu operácií CRUD je stav vytvorenej/načítanej položky uložený v artifactItem spolu s workspaceObjectId a vzorovou implementáciou premenných údajovej časti.

Príklad s rozhraním notification.open() API:

• štát:

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

• UI:

  • Názov:

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

  • Tlačidlo Odoslať:

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

  • Handler:

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

• Radič:

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

Operácie CRUD

Zatiaľ čo vývojový scenár len na fronte je jednoducho podporovaný, úplné možnosti pre vývojárov vyžadujú uloženie, čítanie a úpravu existujúcich položiek vyťaženia. Príručka serverovej implementácie podrobne popisuje, ako nastaviť a používať serverovú stranu.

Keď je koncový server spustený a Org.WorkloadSample.SampleWorkloadItem typ je zaregistrovaný v službe Fabric, môžete v tomto type vykonávať operácie CRUD. Nasledujúce operácie sa zobrazujú prostredníctvom rozhrania API ItemCrud.

VYTVORIŤ

Vzorové volanie na , ako sa createvykonáva pri prvom ukladaní položky vyťaženia:

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

Naša vzorová implementácia ukladá vytvorenú položku v rámci artifactItemslužby . Položka sa vytvorí v aktuálne vybratom pracovnom priestore. Je preto potrebné priradiť pracovný priestor ku kapacite, ktorá je nakonfigurovaná servernou konfiguráciou, ako je to podrobne popísané v serverových dokumentoch. Akýkoľvek pokus o vytvorenie položky v nekompatibilnom pracovnom priestore zlyhá.

• Spätné onCreateFabricItem volanie na backende blokuje volanie CREATE – zlyhanie spôsobuje zlyhanie operácie a v službe Fabric sa nevytvorí žiadna položka. Pozrite si dokumentáciu koncového serveru ladenie/TSG.

• V súčasnosti sa uložená položka v pracovnom priestore automaticky nezobrazí. Je potrebné vykonať obnovenie strany.

GET

Keď v zobrazení pracovného priestoru vyberiete existujúcu položku ukážky vyťaženia, služba Fabric prejde na trasu, ktorá je definovaná v klientskom manifeste v časti artifacts-->editor-->path:

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

Keď vyvoláte itemCrud.getItem, údaje sa načítajú zo serverového serveru služby Fabric spolu s údajmi z koncového serveru služby Workload a načítajú sa do artifactItem objektu otvoreného rozhrania GUI.

AKTUALIZOVAŤ

Aktualizácia existujúcej položky reťazcom itemCrud.updateItem. Údajová časť vyťaženia sa aktualizuje koncovým serverom vyťaženia, zatiaľ čo v službe Fabric sa zmení iba vyťaženie položky lastModifiedTime .

Odstrániť…

Vyvolajte operáciu odstránenia zo zobrazenia Pracovného priestoru služby Fabric (ako všeobecná akcia, ktorá je k dispozícii pre všetky položky), alebo prostredníctvom explicitného volania zo služby Workload do itemCrud.deleteItem. Oba volania prechádzajú spätným volaním pracovného zaťaženia onDeleteItem .

Overovanie

V ukážkovom editore vyťaženia je k dispozícii časť, ktorá vám umožní prejsť na časť overovania. Pred použitím overovacieho rozhrania API nakonfigurujte aplikáciu Microsoft Entra ID microsoft Entra. Okrem toho sa uistite, že váš súbor env.dev je nakonfigurovaný presne. Ďalšie podrobnosti nájdete v téme: Konfigurácia lokálneho manifestu vyťaženia a získanie tokenu pre vašu aplikáciu

Krok č. 4: Ladenie

Ak chcete zobraziť prvky Worker a UI iFrames, otvorte kartu Source v prehliadači DevTools (F12).

Bod prerušenia môžete umiestniť do prvku iFrame pre workerov a zobraziť hlavné switch informácie o prichádzajúcej akcii. Môžete tiež ladiť UI iFrame, napríklad kód v rámci SampleWorkloadEditor.

Plynulé ovládacie prvky používateľského rozhrania

Vyťaženie používateľského rozhrania UX používa ovládacie prvky fluent UI na vizuálnu konzistentnosť so službou Fabric a zjednodušenie vývoja. Vzorové vyťaženie obsahuje príklady toho, ako používať najbežnejšie ovládacie prvky. Ďalšie informácie nájdete na stránke Fluent UI.

Prispôsobenie klientskeho manifestu

Klientsky manifest popisuje klientske aspekty vyťaženia – vzhľad produktu, názvy, vizuálne položky, dostupné akcie a ďalšie. Ide o hlavný kontakt medzi službou Fabric a vyťažením. Pre naše vzorové vyťaženie sa manifest načíta do služby Fabric v režime vývojára a jeho rôzne časti, definície a príklady manifestu sa zobrazujú v klientskych súboroch manifestov. Zmeny položiek manifestu, vedenie rôznych akcií a aktualizácia vizuálnych prostriedkov sa zobrazujú v reálnom čase po obnovení strany.

Súprava SDK klienta – podporované rozhrania API

Dokumentácia k súprave SDK klienta sa nachádza tu: @ms-fabric/workload-client package.

Podporované sú nasledujúce rozhrania 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

Súvisiaci obsah

• Prehľad vývojovej súpravy

• Sprievodca konfiguráciou serveru