Microsoft Fabric -edustan laajentaminen

Microsoft Fabric Workload Development Kitin avulla voit luoda kuormituksia ja luoda Mukautettuja ominaisuuksia, jotka laajentavat Fabric-käyttökokemusta. Fabric-ympäristö on suunniteltu yhteentoimivaksi riippumattoman ohjelmistotoimittajan (ISV) ominaisuuksien kanssa. Kohdeeditorilla voit esimerkiksi luoda alkuperäisen ja yhtenäisen käyttökokemuksen upottamalla toimittajan edustan Fabric-työtilakohteen kontekstiin.

Tässä artikkelissa käytetään Microsoft Fabric -kuormituksen kehitysmallin säilöä oppaana mukautetun käyttökokemuksen verkkosovelluksen integroimisessa Microsoft Fabriciin. Projektin ja yksityiskohtaisten esimerkkien avulla voit integroida saumattomasti omat käyttöliittymäosasi ja toimintosi Fabric-suorituspalveluympäristöön tehokasta kokeilua ja mukauttamista varten.

UX-kuormitusprojektin edusta on vakiomuotoinen React-verkkosovellus , joka sisältää kuormituksen asiakas-SDK:n tavallisena npm-pakettina toiminnallisuuden tarjoamiseksi.

ISV isännöi ja suorittaa projektin Eristyneen <iframe> elementin sisällä Fabric-portaalissa. Se esittelee ISV-kohtaiset käyttöliittymäkokemukset, myös kohdeeditorin.

SDK tarjoaa kaikki tarvittavat käyttöliittymät, ohjelmointirajapinnat ja käynnistysfunktiot, joita tarvitaan tavallisen verkkosovelluksen muuntamiseen mikro-edustaverkkosovellukseksi, joka toimii saumattomasti Fabric-portaalissa.

SDK tarjoaa mallien käyttökokemuskuormitusprojektin. Malli:

• Näyttää, miten voit käyttää useimpia saatavilla olevia SDK-kutsuja.
• Esittelee esimerkin fluenttisesta käyttöliittymäpohjaisesta laajennettavasta nauhasta, joka vastaa Fabric-ulkoasua.
• Mahdollistaa helpon mukauttamisen.
• Tällä voit tarkkailla Fabric-kehittäjätilan reaaliaikaisesti tekemiä muutoksia.

Edellytykset

• KÄYTTÖKOKEMUS-verkkosovellus

  Tämä paketti on kehitetty Fluent UI:n pohjalta, ja se on suunniteltu Reactille.

• Käyttökokemuskuormituksen edustaluettelo

  Käyttökokemuskuormituksen edustan kokoonpanotiedot on JSON-resurssi, jonka ISV tarjoaa. Tiedosto sisältää työkuorman olennaisia tietoja, kuten kuormituksen verkkosovelluksen URL-osoitteen ja useita käyttöliittymätietoja, kuten ISV-kohteen näyttönimen ja siihen liittyvät kuvakkeet. ISV voi kokoonpanotiedoston avulla mukauttaa sitä, mitä tapahtuu, kun käyttäjät käsittelevät kohteita Fabric-portaalissa.

Tässä paketissa edustan luettelotiedostot sijaitsevat pakettikansiossa. Luettelotiedosto sisältää yksityiskohtaisen kuvauksen kuormituksen luettelotiedostosta ja sen osista.

Kuormituksen kehitysominaisuuden käyttöönotto Fabricissa

Vuokraajan järjestelmänvalvojan on ensin otettava kuormituksen kehitystoiminto käyttöön Microsoft Fabric -hallintaportaalissa. Ominaisuus voidaan ottaa käyttöön koko organisaatiolle tai tietyille organisaation ryhmille. Jos haluat ottaa kuormituksen kehitystoiminnon käyttöön tietyille ryhmille, suorita vuokraajan määrityksen käyttöönotto -kohdassa kuvatut vaiheet.

Määritä edusta

Malliprojektin edustan määrittäminen:

1. Varmista, että Node.js ja npm on asennettu. npm-asennuksen on oltava versio 9 tai uudempi. Muussa tapauksessa asenna Node.js ja npm:n uusimmat versiot.

2. Kloonaa Microsoft Fabric -kuormituksen kehitysmallin säilö.

   Seuraavassa luettelossa kuvataan paketin hakemiston asettelu, osat ja resurssit:

   • Paketti: Kuormituspaketin sijainti. Paketti sisältää edustaresursseja, mukaan lukien luetteloita ja resursseja.
   • src: Kuormituskoodi, joka sisältää nämä resurssit:
     • index.ts: Alustamistiedosto, mukaan lukien bootstrap ja - index.worker ja index.ui iFrame-kehykset (lisätietoja on jäljempänä tässä artikkelissa).
     • App.tsx: Tämä tiedosto reitittää polut sivuille. Esimerkiksi /sample-workload-editor reititetään funktioon SampleWorkloadEditor kohdassa components.
     • assets: Kuvien (.jpg, .jpeg ja png:n) sijainti, johon voidaan viitata luettelotiedostossa ja joka näytetään käyttöliittymässä. Esimerkiksi assets/github.jpg luettelotiedostossa on tuotekuvake.
     • -komponentit: Käyttöliittymäkoodin sijainti, mukaan lukien editorinäkymä ja muut mallin käyttämät näkymät (valintanauha, todennussivu ja paneelit).
     • controller: Rekisterinpitäjä kutsuu SDK-ohjelmointirajapintoja.
     • mallit: Käyttöliittymän käyttämät sopimukset ja mallit sekä viestintä kattilaalustan taustan kanssa.
   • tools: Elementit, joiden avulla voit luoda asetuksia ja määrityksiä.
     • webpack.config.js: Määritä paikallinen Node.js palvelin tämän tiedoston avulla.
     • Verkkomääritys ja luettelotiedoston lukija/suoritin.
   • validation: Malli tarkistaa tuotteen ja kohteen JSON-tiedostorakenteet -menetelmän avulla validateSchema.js . Se on määritetty suoritettavaksi toiminnossa npm start.

3. Asenna projektitiedostot siirtymällä säilön kansiossa Frontend-kansioon :

   <repository folder>\Frontend> npm install
   

4. Käynnistä palvelin suorittamalla seuraava komento:

   <repository folder>\Frontend> npm start
   

   Tämä komento käynnistää paikallisen Node.js palvelimen (webpackilla), johon Microsoft Fabric muodostaa yhteyden kehittäjätilassa.

   Lisätietoja portin tiedoista, jotka näkyvät palvelimen käynnistymisen jälkeen, on paikallisen isäntäpalvelimen huomautuksista.

   Nykyinen portti on 60006.

   Kun localhost-palvelin käynnistyy, avaa URL-osoitteeseen 127.0.0.1:60006/manifests koostettu luettelotiedosto, joka luodaan Edusta/paketti-kansioon .

   Jos muutat tiedostoja Frontend/Package-kansiossa , suorita npm start uudelleen.

   Tämä asetus säilyy nykyisessä selaimessa.

   

"Hei maailma" -esimerkki

Hello World -testiskenaarion suorittaminen:

1. Käynnistä paikallinen palvelin (suorita sekä edustan että taustan kuormituksen mallit Aloittaminen-kohdan ohjeiden mukaisesti) ja varmista, että kehittäjätila on käytössä.

2. Valitse työtilavalikosta Luo keskitin -kuvake (joskus kuvake sijaitsee Näytä lisää kolmea pistettä -kohdassa).

   

3. Valitse Näytä kaikki.

   

4. Luo kohde valitsemalla Mallikuormitus-kohdassa Mallikohde-kortti.

   

Uusi kohde näyttää tämän esimerkin kaltaiselta:

Tutustu eri ohjausobjekteihin ja tutustu Fabric WorkloadClient -ohjelmointirajapinnan (kuormituksen SDK) toimintoihin:

• Avaa ilmoitukset ja valintaikkunat
• Sivuille siirtyminen
• Teeman ja kuormituksen asetusten hakeminen
• Toimintojen suorittaminen

Useimmat käytettävissä olevista SDK-toiminnoista on joko määritetty painiketoimintoina tai rekisteröity takaisinkutsuina. Tulokset ovat yleensä ilmoitus tai sanomaruutu, jossa näkyy, että ohjelmointirajapinta on käynnistetty.

Esimerkkejä:

• Toiminnon suorittaminen kutsuu toimintoa.execute()-ohjelmointirajapinnan toiminnolla, jonka nimi on malli. Toiminto. Toiminnon toiminto on näyttää ilmoitus.

• Valitse valintanauhasta Tallenna ja kutsu valintaikkuna.open()-ohjelmointirajapinta. Ohjelmointirajapinta avaa valintaikkunan, jossa käyttäjä kirjoittaa nimen ja tallentaa kohteen Fabric-kohteeseen. Lisätietoja valintaikkunasta on OSIOssa CRUD.

• Hae teema -asetukset -painikkeessa näkyy luettelo Fabric-teemamäärityksistä (theme.get()-ohjelmointirajapinnan kautta).

Mallikuormituksen käyttöliittymää isännöiDään Fabric-eristetyssä iframe elementissä, joka näkyy verkkosivun kehittäjätilassa.

Muistiinpano

Eristetty iframe elementti tukee määritteitä allow-same-origin ja allow-scripts.

Lisätietoja eristyksessä ja määritteissä on kohdassa MDN Web Docs.

Tutustu koodiin

Seuraavissa osioissa kuvataan koodielementit ja olennaiset seikat.

bootstrap()

Tarkista ennen käynnistystä, onko ikkuna suljettava. Tämä vaihe vaaditaan, jos käytät todennuksen ohjelmointirajapintaa.

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

Jokaisen Fabric-kuormitussovelluksen on tuettava alustusta kahdessa tilassa:

• Käyttöliittymätila: Käyttöliittymätilassa oleva sovellus ladataan näkyviin iFrame-kehyksiin. Se kuuntelee omia reittimuutoksiaan, jotta se hahmontaa vastaavat käyttöliittymäkomponentit, kuten sivut, ruudut ja valintaikkunat.

• Työntekijätila: Työntekijätilassa oleva sovellus suoritetaan näkymättömässä iFramessa. Näkymätöntä iFramea käytetään ensisijaisesti ulkoisten komentojen vastaanottamiseen ja niiden vastaamiseen.

- @ms-fabric/workload-client ohjelmointirajapinta tarjoaa menetelmän bootstrap() alustusvaiheiden yksinkertaistamiseen. - bootstrap() menetelmä tunnistaa sisäisesti, onko nykyinen sovellus ladattu käyttöliittymätilaan vai työntekijätilaan. Sitten se kutsuu asianmukaista alustusmenetelmää (initializeUI tai initializeWorker). Kun alustaminen on valmis, bootstrap() fabric-mikro-edustakehys saa ilmoituksen alustamisen onnistumisesta tai epäonnistumisesta.

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

index.worker

index.worker on päärekisteröinti onAction . Se käsittelee Fabric-isännän lähettämät tapahtumat, jotka käynnistetään suoritettujen toimintojen avulla.

Kuormitus voi lähettää toiminnot Fabricille ja kutsua ne sitten takaisin käsittelijään onAction , tai Fabric-isäntä voi käynnistää ne. Kun esimerkiksi valitset Luo mallikohde – Vain edusta, Fabric käynnistää toiminnon open.createSampleWorkloadFrontendOnly, ja onAction käsittelijä aloittaa kuormituksen pääkäyttöliittymäsivun avaamisen. Nykyinen työtilan objectId arvo välitetään myös vain edusta -käyttökokemukseen.

Järjestys näkyy seuraavassa koodiesimerkissä:

   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

Funktio initialize() hahmontaa React DOMin, johon App funktio on upotettu. Voit kutsua API-kutsuja välittämällä workloadClient SDK-kahvan, jota käytetään koko koodissa.

- FluentProvider luokka varmistaa tyylin yhtenäisyyden eri FluentUI-ohjausobjekteissa. Esimerkki:

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

Kehitystyönkulku

• Funktio App reitittää koodin kohteeseen SampleWorkloadEditor. Funktio palauttaa arvon kohteelle React.JSX.Element.
• Funktio sisältää käyttöliittymärakenteen. Käyttöliittymärakenne sisältää valintanauhan ja sivun ohjausobjektit, kuten painikkeet ja syöttökentät.
• Käyttäjältä kerätyt tiedot tallennetaan React-koukkujen useState() kautta.
• Käyttöliittymän ohjausobjektien käsittelijät kutsuvat SampleWorkloadController funktioita ja ohittavat olennaiset tilamuuttujat.
• CRUD-toimintojen tukemiseksi luodun/ladatun kohteen tila tallennetaan kohteeseen artifactItem workspaceObjectId ja hyötykuorman muuttujien mallitoteutuksen.

Seuraavissa esimerkeissä käytetään notification.open()-ohjelmointirajapintaa:

• Tila:

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

• UI:

  Nämä esimerkit määrittävät tiettyjä käyttöliittymäelementtejä:

  • Title:

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

  • Lähetä-painike:

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

  • Käsittelijä:

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

• Ohjain:

    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-toiminnot

Vaikka vain edusta -kehitysskenaariota on helppo tukea, täydellinen kehittäjäkokemus edellyttää olemassa olevien kuormituskohteiden tallentamista, lukemista ja muokkaamista.

Taustan toteutusoppaassa kuvataan yksityiskohtaisesti, miten taustan voi määrittää ja käyttää.

Kun tausta on toiminnassa ja Org.WorkloadSample.SampleWorkloadItem tyyppi on rekisteröity Fabricissa, voit suorittaa CRUD-toimintoja tässä tyypissä.

Seuraavat toiminnot näytetään ItemCrud-ohjelmointirajapinnan avulla.

LUO

Jos haluat tehdä mallikutsun kohteeseen create, käytä seuraavaa esimerkkiä, joka näyttää kuormituskohteen tallentamisen ensimmäistä kertaa:

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

Malli toteutuksesta tallentaa luodun kohteen kohteeseen artifactItem.

Kohde luodaan valittuna olevassa työtilassa. Työtila on määritettävä kapasiteetille, joka on määritetty taustamäärityksessä. Katso lisätietoja taustadokumentaatiosta.

Yritys luoda kohde keskeneräisen työtilan alla epäonnistuu:

• Taustakutsu onCreateFabricItem estää CREATE kutsun. Tässä vaiheessa virhe aiheuttaa toiminnon epäonnistumisen, eikä Fabricissa luoda mitään kohdetta. Lisätietoja on taustatietojen virheenkorjauksen ja vianmäärityksen ohjeissa.

• Tallennettu kohde ei tällä hetkellä näy automaattisesti työtilassa. Jos haluat tarkastella tallennettua kohdetta työtilassa, päivitä sivu.

GET

Kun valitset aiemmin luodun mallikuormituksen kohteen työtilanäkymässä, Fabric siirtyy reitille, joka on määritetty edustan luettelotiedostossa kohdassa artifactspath>editor>:

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

Kun käynnistät itemCrud.getItem-kutsun, tiedot ladataan sekä Fabric-taustasta että kuormituksen taustasta. Molempien lähteiden tiedot ladataan artifactItem avoimen GUI-käyttöliittymän objektiin.

UPDATE

Jos haluat päivittää olemassa olevan kohteen, käytä kohdetta itemCrud.updateItem. Kuormituksen hyötykuorma päivittyy kuormituksen taustan mukaan. Fabric-versiossa vain kohteen lastModifiedTime muutokset ovat päivittyneet.

DEL

Voit kutsua toimintoa joko Fabric-työtilanäkymässä delete yleiseksi toiminnoksi, joka on kaikkien kohteiden käytettävissä, tai eksplisiittisen kutsun kautta työkuormituksesta kohteeseen itemCrud.deleteItem.

Kummankin puhelutyypin tulee käydä läpi kuormituksen taustan onDeleteItem vastakutsu.

Todentamisaktiviteetin tarkasteleminen

Voit tarkastella todentamistoimintoja mallikuormituseditorissa.

Ennen kuin käytät todentamisen ohjelmointirajapintaa, määritä sovelluksesi todennukseen Microsoft Entra -tunnuksen avulla.

Varmista myös, että env.dev-tiedostosi on määritetty oikein. Lisätietoja on kohdassa Kuormituksen paikallisen luettelotiedoston määrittäminen ja tunnuksen hankinta sovellukselle.

Virheenkorjaus

Jos haluat nähdä työntekijä- ja käyttöliittymän iframe-elementit, avaa selaimen kehittäjätyökalut valitsemalla selaimessa F12. Valitse Lähteet-välilehti .

Voit sijoittaa keskeytyskohdan työntekijän iframe-elementtiin ja tarkastella saapuvan toiminnon pääkohtaa switch . Voit myös korjata käyttöliittymän iframe-elementin virheenkorjauksen. Voit esimerkiksi korjata koodin virheenkorjauksen :n sisällä SampleWorkloadEditor.

Sujuvan käyttöliittymän ohjausobjektit

Käyttökokemuskuormitukset käyttävät Fluent UI -ohjausobjekteja Fabric-käyttöliittymän visuaaliseen yhdenmukaisuuden ja kehityksen helpottamiseksi. Mallikuormitusprojekti sisältää esimerkkejä yleisimpien ohjausobjektien käyttämisestä.

Lisätietoja on kohdassa Sujuva käyttöliittymä.

Edustan kokoonpanon mukauttaminen

Edustan luettelotiedosto kuvaa kuormituksen edustan ominaisuuksia, kuten tuotteen ulkoasua, nimiä, visualisointiresursseja ja käytettävissä olevia toimintoja. Edustaluettelo on Fabricin ja kuormituksen välinen tärkein yhteyspiste.

Näytekuormitusta varten luettelotiedosto ladataan Fabric-tiedostoon kehittäjätilassa. Luettelotiedoston osat, määritelmät ja esimerkit näkyvät luettelotiedostojen edustalla.

Luettelotiedoston merkintöjen, toimintoasetusten ja visualisointiresurssien päivitysten muutokset näkyvät reaaliaikaisesti sivun päivittämisen jälkeen.

Asiakkaan SDK:n tukemat ohjelmointirajapinnat

Seuraavia ohjelmointirajapintoja tuetaan:

• 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

Lisätietoja on artikkelissa @ms-fabric/workload-client-paketti.

Liittyvä sisältö

• Kuormituksen kehityspaketin yleiskatsaus
• Taustan määritysopas