A Microsoft Fabric előtér kiterjesztése

A Microsoft Fabric számítási feladatok fejlesztői készletével számítási feladatokat hozhat létre, és egyéni képességeket hozhat létre, amelyek kibővítik a Fabric-élményt. A Fabric platform úgy lett kialakítva, hogy együttműködjön a független szoftvergyártók (ISV) képességeivel. Az elemszerkesztővel például natív, konzisztens felhasználói élményt hozhat létre úgy, hogy beágyazza az ISV előtérrendszerét egy Háló-munkaterület elem környezetében.

Ebben a cikkben a Microsoft Fabric számítási feladatok fejlesztési mintaadattárát használja útmutatóként egy egyéni UX számítási feladatok webalkalmazásának a Microsoft Fabricbe való integrálásához. A projekt és a részletes példák segítségével zökkenőmentesen integrálhatja saját felhasználói felületi összetevőit és műveleteit a Fabric futtatókörnyezetbe a hatékony kísérletezés és testreszabás érdekében.

A minta UX számítási feladat projekt előtere egy szabványos React webalkalmazás, amely a számítási feladat ügyféloldali SDK-t standard npm-csomagként tartalmazza a funkciók biztosításához.

Az ISV üzemelteti és futtatja a projektet egy tesztkörnyezeti <iframe> elemen belül a Háló portálon. Az ISV-specifikus felhasználói felületi élményeket mutatja be, beleértve az elemszerkesztőt is.

Az SDK biztosítja az összes szükséges felületet, API-t és bootstrap-függvényt, amelyek szükségesek ahhoz, hogy egy normál webalkalmazást mikro előtér-webalkalmazássá alakítsa, amely zökkenőmentesen működik a Fabric portálon.

Az SDK egy minta UX számítási feladatprojektet biztosít. A minta:

Bemutatja, hogyan használhatja a legtöbb elérhető SDK-hívást.
A Fluent UI-alapú bővíthető menüszalag példáját mutatja be, amely megfelel a Fabric megjelenésének és megjelenésének.
Egyszerű testreszabást tesz lehetővé.
Lehetővé teszi a fabricbeli változások valós idejű megfigyelését, amikor a Fabric fejlesztői üzemmódja be van kapcsolva.

Előfeltételek

UX számítási feladatok webalkalmazása

Ez a csomag a Fluent felhasználói felületére épül, és a Reacthez készült.
UX-alapú számítási feladatok előtérjegyzéke

Az UX számítási feladatok előtérjegyzéke az ISV által biztosított JSON-erőforrás. A fájl alapvető információkat tartalmaz a számítási feladatról, beleértve a számítási feladat webalkalmazásÁNAK URL-címét és a felhasználói felület különböző részleteit, például az ISV-elem megjelenítendő nevét és a kapcsolódó ikonokat. Az ISV a jegyzékfájl használatával testre szabhatja, hogy mi történik, ha a felhasználók a Háló portálon használják az elemeket.

Ebben a csomagban az előtérbeli jegyzékfájlok a csomagmappában találhatók. A jegyzékfájl részletes leírást tartalmaz a számítási feladatjegyzékről és annak összetevőiről.

A számítási feladatok fejlesztési funkciójának engedélyezése a Hálóban

A bérlői rendszergazdának először engedélyeznie kell a számítási feladat fejlesztési funkcióját a Microsoft Fabric felügyeleti portálján. A funkció a teljes szervezet vagy a szervezet adott csoportjai számára engedélyezhető. A bérlői rendszergazda számára a számítási feladatok fejlesztési funkciójának adott csoportokhoz való engedélyezéséhez hajtsa végre a fejlesztési bérlő beállítás engedélyezésével kapcsolatos lépéseket.

Képernyőkép a számítási feladatok fejlesztési bérlői kapcsolóról.

Az előtér beállítása

A mintaprojekt előtérjének beállítása:

Ellenőrizze, hogy a Node.js és az npm telepítve van-e. Az npm telepítésének 9-es vagy újabb verziónak kell lennie. Ellenkező esetben telepítse a Node.js és az npm legújabb verzióit.
Klónozza a Microsoft Fabric számítási feladatok fejlesztési mintaadattárát.

Az alábbi lista a csomagkönyvtár elrendezését, összetevőit és erőforrásait ismerteti:
- Csomag: A számítási feladatcsomag helye. A csomag előtér-erőforrásokat tartalmaz, beleértve a jegyzékeket és az eszközöket.
- src: A számítási feladat kódja, amely az alábbi erőforrásokat tartalmazza:
  - index.ts: A fő inicializálási fájl, beleértve bootstrap az és az index.ui index.worker iFrame-eket is (részletek a cikk későbbi részében).
  - App.tsx: Ez a fájl a lapok elérési útját irányítja. Például /sample-workload-editor a rendszer átirányítja a függvényt a SampleWorkloadEditor következő alá components: .
  - objektumok: A jegyzékben hivatkozott és a felhasználói felületen látható képek (.jpg, .jpeg és png) helye. Például assets/github.jpg a jegyzékben termékikonként van beállítva.
  - összetevők: A felhasználói felület kódjának helye, beleértve a szerkesztőnézetet és a minta által használt egyéb nézeteket (a menüszalagot, a hitelesítési lapot és a paneleket).
  - vezérlő: A vezérlő meghívja az SDK API-kat.
  - modellek: A felhasználói felület által használt és a kazánlemez háttérrendszerével való kommunikációhoz használt szerződések és modellek.
- eszközök: Beállítások és konfigurációk létrehozásához használható elemek.
  - webpack.config.js: Ezzel a fájllal konfigurálhatja a helyi Node.js kiszolgálót.
  - Webes konfiguráció és jegyzékolvasó/feldolgozó.
- ellenőrzés: A minta a termék- és elem JSON-fájlsémainak ellenőrzésére használható validateSchema.js . Úgy van konfigurálva, hogy futtassa a következőt npm start: .
Az adattár mappájában lépjen a Frontend mappába a projektfájlok telepítéséhez:
```
<repository folder>\Frontend> npm install
```
Indítsa el a kiszolgálót a következő parancs futtatásával:
```
<repository folder>\Frontend> npm start
```
Ez a parancs elindít egy helyi Node.js kiszolgálót (webpack használatával), amelyhez a Microsoft Fabric fejlesztői módban csatlakozik.

A kiszolgáló indítása után megjelenő portadatokkal kapcsolatos információkért tekintse meg a helyi gazdagépkiszolgáló megjegyzéseit.

Az aktuális port a következő 60006.

A localhost-kiszolgáló elindítása után lépjen az URL-címre 127.0.0.1:60006/manifests a Frontend/Package mappában létrehozott összesített jegyzék megnyitásához.

Ha a Frontend/Package mappában módosít fájlokat, futtassa npm start újra.

Ez a beállítás megmarad az aktuális böngészőben.

"Hello world" példa

"Hello World" tesztforgatókönyv futtatása:

Indítsa el a helyi kiszolgálót (kövesse az első lépések lépéseit az előtérbeli és a háttérbeli számítási feladatok mintáinak futtatásához), és győződjön meg arról, hogy a fejlesztői mód engedélyezve van.
A munkaterület menüjében válassza a Hub létrehozása ikont (néha az ikon a További három pont megjelenítése területen található).
Válassza az Összes megjelenítése lehetőséget.
A Mintaterhelés csoportban válassza ki a Mintaelem kártyát egy elem létrehozásához.

Az új elem az alábbi példához hasonlóan néz ki:

Képernyőkép a fő minta felhasználói felület képi felületéről.

A Fabric WorkloadClient API (a számítási feladat SDK) funkcióinak megtekintéséhez tekintse meg a különböző vezérlőket:

Értesítések és párbeszédpanelek megnyitása
Ugrás a lapokra
Téma- és számítási feladatok beállításainak lekérése
Műveletek végrehajtása

Az elérhető SDK-funkciók többsége gombműveletként van konfigurálva, vagy visszahívásként van regisztrálva. Az eredmények általában egy értesítés vagy egy üzenetmező, amely azt jelzi, hogy egy API-t meghívtak.

Példa:

Egy művelet végrehajtása meghívja az action.execute() API-t egy minta nevű művelettel. Művelet. A művelet funkciója egy értesítés megjelenítése.
A párbeszédpanel.open() API meghívásához válassza a menüszalag Mentés gombját. Az API megnyitja a párbeszédpanelt, amelyen egy felhasználó nevet ad meg, és menti az elemet a Fabricben. A párbeszédpanelről további információt a CRUD szakaszban talál.
A Témabeállítások lekérése gomb megjeleníti a Fabric-témakonfigurációk listáját (a theme.get() API-n keresztül).

A minta számítási feladat felhasználói felülete egy hálós tesztkörnyezeti iframe elemben található, amely a weblap fejlesztői módban jelenik meg.

Képernyőkép az iFrame beágyazási képéről.

Feljegyzés

A tesztkörnyezeti iframe elem támogatja az attribútumokat allow-same-origin és allow-scriptsa .

További információ a tesztkörnyezetről és az attribútumokról: MDN Web Docs.

A kód értelmezése

A következő szakaszok a kódelemeket és a kapcsolódó szempontokat ismertetik.

bootstrap()

A rendszerindítás előtt ellenőrizze az elérési utat, hogy be kell-e zárnia az ablakot. Erre a lépésre a hitelesítési API használata esetén van szükség.

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

Minden Háló számítási feladat alkalmazásnak két módban kell támogatnia az inicializálást:

Felhasználói felületi mód: A felhasználói felületi módban lévő alkalmazások látható iFrame-ekben töltődnek be. Figyeli a saját útvonalmódosításait, hogy megjelenítse a megfelelő felhasználói felületi összetevőket, például lapokat, paneleket és párbeszédpaneleket.
Feldolgozó mód: Egy munkavégző módban lévő alkalmazás láthatatlan iFrame-ben fut. A láthatatlan iFrame-et elsősorban külső parancsok fogadására és azok megválaszolására használják.

Az @ms-fabric/workload-client API egy bootstrap() módszert biztosít az inicializálási lépések egyszerűsítésére. A bootstrap() metódus belsőleg észleli, hogy az aktuális alkalmazás felhasználói felületi módban vagy feldolgozó módban van-e betöltve. Ezután meghívja a megfelelő inicializálási módszert (initializeUI vagy initializeWorker). Ha az inicializálás befejeződött, bootstrap() értesíti a Fabric mikro-előtérbeli keretrendszerét az inicializálás sikerességéről vagy sikertelenségéről.

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

index.worker

index.worker a fő onAction regisztráció. Kezeli a Háló gazdagép által küldött eseményeket, amelyeket végrehajtott műveletek aktiválnak.

A műveleteket a számítási feladat elküldheti a Fabricnek, majd visszahívhatja őket a onAction kezelőbe, vagy a Háló gazdagép kezdeményezheti őket. Ha például a Mintaelem létrehozása – Csak előtérbeli elem lehetőséget választja, a Háló aktiválja a műveletetopen.createSampleWorkloadFrontendOnly, és a onAction kezelő kezdeményezi a számítási feladat fő felhasználói felületének megnyitását. Az aktuális munkaterület objectId értékét a rendszer a csak előtérbeli felületre is továbbítja.

A sorozat a következő kód példában látható:

   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() függvény megjeleníti a React DOM-et, ahol a App függvény beágyazva van. Az API-hívások meghívásához adja át a workloadClient kódban használt SDK-leírót.

Az FluentProvider osztály biztosítja a stíluskonzisztenciát a különböző FluentUI-vezérlők között. Példa:

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

Fejlesztési folyamat

A App függvény a kódot a következőre SampleWorkloadEditorirányítja: . A függvény egy értéket ad vissza a következőhöz React.JSX.Element: .
A függvény tartalmazza a felhasználói felület struktúráját. A felhasználói felület struktúrája tartalmazza a menüszalag- és oldalvezérlőket, például a gombokat és a beviteli mezőket.
A felhasználótól gyűjtött információk a React-horogon useState() keresztül lesznek tárolva.
A felhasználói felület vezérlői meghívják a SampleWorkloadController függvényeket, és átadják a megfelelő állapotváltozókat.
A CRUD-műveletek támogatásához a rendszer a létrehozott/betöltött elem állapotát tárolja artifactItem a hasznos adatváltozók mintaalkalmazásával workspaceObjectId együtt.

A következő példák a notification.open() API-t használják:

Állapot:

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

UI:

Az alábbi példák adott felhasználói felületi elemeket konfigurálnak:

Title:

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

Küldés gomb:

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

Edzőtárs:

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

Ellenőr:

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

CRUD-műveletek

Bár a csak előtérbeli fejlesztési forgatókönyvek egyszerűen támogatottak, a teljes körű fejlesztői élményhez menteni, olvasni és szerkeszteni kell a meglévő számítási feladatelemeket.

A háttérrendszer implementálási útmutatója részletesen ismerteti a háttérrendszer beállítását és használatát.

Ha a háttérrendszer működik, és a típus regisztrálva van a Org.WorkloadSample.SampleWorkloadItem Fabricben, a CRUD-műveleteket ezen a típuson hajthatja végre.

A következő műveletek az ItemCrud API használatával érhetők el.

CREATE

Ha mintahívást szeretne kezdeményezni create, használja az alábbi példát, amely a számítási feladatelem első mentését mutatja be:

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

A minta implementáció a létrehozott elemet a következő helyen artifactItemtárolja: .

Az elem az aktuálisan kijelölt munkaterületen jön létre. A munkaterületet hozzá kell rendelni a háttérkonfigurációban beállított kapacitáshoz. További információkért tekintse meg a háttérrendszer dokumentációját.

Egy nem kompatibilis munkaterületen lévő elem létrehozására tett kísérlet meghiúsul:

A onCreateFabricItem háttérrendszer visszahívása letiltja a CREATE hívást. Az adott időpontban bekövetkező hiba miatt a művelet sikertelen lesz, és a Hálóban nem jön létre elem. További információkért tekintse meg a háttérrendszer hibakeresési és hibaelhárítási dokumentációját.
A mentett elemek jelenleg nem jelennek meg automatikusan a munkaterületen. Ha meg szeretne tekinteni egy mentett elemet a munkaterületen, frissítse a lapot.

KAP

Ha kijelöl egy meglévő számítási feladatmintát a munkaterület nézetben, a Háló a következő előtérjegyzékben artifacts>>editorpathdefiniált útvonalra lép:

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

A meghíváskor itemCrud.getItema rendszer betölti az adatokat a Fabric háttérrendszerből és a számítási feladatok háttérrendszeréből is. A rendszer mindkét forrásból származó adatokat betölti a artifactItem megnyitott grafikus felhasználói felület objektumába.

Képernyőkép a munkaterület meglévő elemeinek megnyitásáról.

UPDATE

Meglévő elem frissítéséhez használja itemCrud.updateItema következőt: . A számítási feladat hasznos adatait a számítási feladat háttérrendszere frissíti. A Hálóban csak az elem lastModifiedTime módosításai módosulnak a frissítés után.

Törlés...

A műveletet a Háló munkaterület nézetben általános műveletként hívhatja delete meg, amely az összes elemhez elérhető, vagy a számítási feladat explicit hívásával.itemCrud.deleteItem

Mindkét hívástípus a számítási feladat háttérrendszerének visszahívásán onDeleteItem megy keresztül.

Hitelesítési tevékenység megtekintése

A minta számítási feladatok szerkesztőjében megtekintheti a hitelesítési tevékenységet.

A hitelesítési API használata előtt konfigurálja az alkalmazást hitelesítésre a Microsoft Entra ID használatával.

Győződjön meg arról is, hogy a env.dev fájl megfelelően van konfigurálva. További információ: A számítási feladat helyi jegyzékének konfigurálása és jogkivonat beszerzése az alkalmazáshoz.

Hibakeresés

A feldolgozó és a felhasználói felület iframe elemeinek megtekintéséhez a böngészőben válassza az F12 lehetőséget a böngésző fejlesztői eszközeinek megnyitásához. Válassza a Források lapot.

Képernyőkép a Visual Studio Code-ban található fájlok hibakereséséről.

Elhelyezhet egy töréspontot a feldolgozó iframe elemében, és megtekintheti a bejövő művelet fő switch elemét. A felhasználói felület iframe elemét is hibakeresésre használhatja. Például hibakeresést végezhet a kódon belül SampleWorkloadEditor.

Fluent felhasználói felület vezérlői

Az UX számítási feladatok Fluent felhasználói felületi vezérlőket használnak a Fabric vizuális konzisztenciájához és a könnyű fejlesztéshez. A számítási feladat mintaprojektje példákat mutat be a leggyakoribb vezérlők használatára.

További információ: Fluent felhasználói felület.

Előtérjegyzék testreszabása

Az előtérbeli jegyzék a számítási feladat előtérbeli aspektusait ismerteti, beleértve a termék megjelenését, a neveket, a vizualizációs eszközöket és az elérhető műveleteket. Az előtérbeli jegyzék a Háló és a számítási feladat közötti kapcsolat fő pontja.

A mintafeladat esetében a jegyzékfájl fejlesztői módban van betöltve a Fabricbe. A jegyzék szakaszai, definíciói és példái az előtérbeli jegyzékfájlokban jelennek meg.

A jegyzék bejegyzéseinek, a műveletbeállításoknak és a vizualizációelemek frissítésének módosításai valós időben jelennek meg a lap frissítése után.

Ügyféloldali SDK által támogatott API-k

A következő API-k támogatottak:

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

További információ: @ms-fabric/workload-client csomag.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2024-11-24