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

Táto ukážka pre vývojárov služby 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 UX Workload Frontend je štandardná webová aplikácia (React), ktorá zahŕňa naše rozšírenie klienta SDK, štandardného balíka npm, aby bolo možné zapnúť jeho funkcie. Nezávislý dodávateľ softvéru ho hosťuje a prevádzkuje v rámci portálu <iframe> 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 manifest nachádza v súbore Klientsky manifest a podrobný popis nájdete v klientskom súbore manifestu.

Krok č. 1: Povolenie rozšírení vyťaženia v službe Fabric

Správca nájomníka musí povoliť funkciu vývoja vyťaženia 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šieNode.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:

   • docs – dokumentácia K súprave SDK, obrázky
   • Manifesty – umiestnenie klientskeho súboru manifestu
   • node_modules – ukážka vyťaženia sa dodáva s predinštalovanými balíkmi SDK – v časti @trident , pretože ich balík npm ešte nie je verejne dostupný
   • src – kód vyťaženia:
     • index.ts – hlavný inicializačný súbor, boostrapindex.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 – miesto pre obrázky(svg, jpg, png, atď.), na ktoré sa dá odkazovať v manifeste a zobrazujú sa v používateľskom rozhraní. Napríklad assets/github.svg 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
     • manifest.reader.js - čítanie súboru manifestu

3. Nainštalujte. Všimnite si existujúce balíky v časti node_modules

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

   <repository folder>\Frontend> npm install
   

   Poznámka

   Odkladací priestor poskytuje balíky v časti node_modules/@trident. Tieto balíky ešte nie sú k dispozícii vo verejných informačných kanáloch npm, takže odstránením sa daný odkladací priestor vykreslí ako nepoužiteľný. Ak existujú problémy s inštaláciou npm (pri zlučovaní nezhodných verzií atď.), odstráňte všetko v časti node_modulesokrem @trident priečinka a pred opätovným spustením inštalácie npm odstráňte package-lock.json súbor.

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 obsah súboru manifestu localWorkloadManifest.json . 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úbor manifestu localWorkloadManifest.json , obnovte stránku služby Fabric a znova načítajte manifest.

5. Spustite službu In Fabric, povoľte nastavenie režimu klientskeho vývojára, 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 službe Fabric iframe , čo vidíme pri skúmaní rozhrania DOM stránky:

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. @trident/extension-client-3p 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.

   extensionClient.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 ArtifactCreateContext;
                return extensionClient.page.open({
                    extensionName: 'Fabric.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 extensionClient 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}
               extensionClient={extensionClient}
           />
       </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 zhromaždené od používateľa sa ukladajú prostredníctvom knižnice React useState()
• 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, extensionClient, setNotificationId);
      };
    

• Radič:

    export async function callNotificationOpen(
      title: string,
      message: string,
      type: NotificationType = NotificationType.Success,
      duration: NotificationToastDuration = NotificationToastDuration.Medium,
      extensionClient: ExtensionClientAPI,
      setNotificationId?: Dispatch<SetStateAction<string>>) {
  
      const result = await extensionClient.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 ArtifactCrud.

VYTVORIŤ

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

 const params: CreateArtifactParams = {
        workspaceObjectId,
        payload: { artifactType, displayName, description, workloadPayload: JSON.stringify(workloadPayload), payloadContentType: "InlineJson", }
    };
 const result: CreateArtifactResult = await extensionClient.artifactCrud.createArtifact(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": "Fabric.WorkloadSample",
    "path": "/sample-workload-editor"
   },

Keď vyvoláte artifactCrud.getArtifact, ú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 artifactCrud.updateArtifact. Ú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 artifactCrud.deleteArtifact. 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 Entra Microsoft Entra ID. V localWorkloadManifest.json nakonfigurujte konfiguráciu Entra v časti "rozšírenie":

   "devAADAppConfig": {
   "appId": your app id,
   "redirectUri": "http://localhost:60006/close" // you can change this to whatever path that suits you in index.ts
   "audience": your audience
  }

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 localWorkloadManifest.json sa manifest načíta do služby Fabric v režime pre vývojárov a jej rôzne sekcie, definície a príklady manifestu sú uvedené v klientskom manifeste. 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 súpravy SDK sa nachádza v sekcii Docs v ukážkovom odkladacom priestore pre vývojárov služby Fabric. Ak ho chcete zobraziť, stiahnuť alebo klonovať odkladací priestor, otvorte odkladací index.html priestor zo systému súborov. Otvorí sa dokumentácia rozhrania API, ktorá sa zobrazuje v každom súbore súpravy SDK.

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
• artefaktCrud.createArtifact
• artefaktCrud.getArtifact
• artefaktCrud.updateArtifact
• artefaktCrud.deleteArtifact
• artefaktSchedule.runArtifactJob
• artefaktSchedule.cancelArtifactJob
• artefaktRecentRuns.open

Súvisiaci obsah

• Prehľad vývojovej súpravy

• Sprievodca konfiguráciou serveru