Rozszerzanie frontonu usługi Microsoft Fabric

Za pomocą zestawu Microsoft Fabric Workload Development Kit możesz tworzyć rozwiązania i niestandardowe możliwości, które rozszerzają środowisko platformy Fabric. Platforma Fabric została zaprojektowana tak, aby była interoperacyjna z funkcjami niezależnych dostawców oprogramowania (ISV). Możesz na przykład użyć edytora elementów, aby zapewnić spójny, natywny interfejs użytkownika przez osadzenie interfejsu użytkownika niezależnego dostawcy oprogramowania (ISV) w kontekście elementu obszaru roboczego Fabric.

W tym artykule użyjesz przykładowego repozytorium programistycznego obciążeń usługi Microsoft Fabric jako wskazówki do zintegrowania niestandardowej aplikacji internetowej obciążenia UX z usługą Microsoft Fabric. Projekt i szczegółowe przykłady pomagają bezproblemowo integrować własne komponenty interfejsu użytkownika i akcje ze środowiskiem uruchomieniowym Fabric na potrzeby wydajnego eksperymentowania i dostosowywania.

Frontend przykładowego projektu obciążenia UX to standardowa aplikacja internetowa w React, która wykorzystuje zestaw SDK klienta obciążenia jako standardowy pakiet npm, aby zapewnić odpowiednią funkcjonalność.

Dostawca ISV hostuje i uruchamia projekt wewnątrz izolowanego elementu <iframe> w portalu Fabric. Udostępnia środowiska użytkownika specyficzne dla ISV, w tym edytor elementów.

Zestaw SDK udostępnia wszystkie niezbędne interfejsy, interfejsy API i funkcje inicjalizujące, które są wymagane do przekształcenia zwykłej aplikacji internetowej w aplikację typu mikrofrontend, działającą płynnie w portalu Fabric.

Zestaw SDK udostępnia przykładowy projekt obciążenia środowiska użytkownika. Przykład:

Pokazuje, jak używać większości dostępnych wywołań zestawu SDK.
Przedstawia przykład rozszerzalnej wstążki opartej na Fluent UI, która odpowiada wyglądowi i działaniu rozwiązania Fabric.
Umożliwia łatwe dostosowywanie.
Umożliwia obserwowanie zmian w sieci szkieletowej w czasie rzeczywistym po włączeniu trybu dewelopera sieci szkieletowej.

Wymagania wstępne

Aplikacja internetowa do analizy obciążenia UX

Ten pakiet bazuje na Fluent UI i został zaprojektowany dla React.
Manifest frontonu obciążenia środowiska użytkownika

Manifest frontendu obciążenia UX to zasób JSON dostarczany przez dostawcę ISV. Plik zawiera istotne informacje o obciążeniu roboczym, w tym adres URL aplikacji internetowej obciążenia roboczego oraz różne szczegóły interfejsu użytkownika, takie jak wyświetlana nazwa elementu dostawcy ISV i powiązane ikony. Dostawca ISV może użyć pliku manifestu, aby dostosować to, co dzieje się, gdy użytkownicy wchodzą w interakcję z elementami w portalu Fabric.

W tym pakiecie pliki manifestu frontendu znajdują się w folderze pakietu. Plik manifestu zawiera szczegółowy opis manifestu obciążenia i jego składników.

Włącz funkcję tworzenia obciążeń w usłudze Fabric

Administrator dzierżawy musi najpierw włączyć funkcję programowania obciążeń w ustawieniach dzierżawy. Tę funkcję można włączyć dla całej organizacji lub dla określonych grup w organizacji. Aby administrator dzierżawy mógł włączyć funkcję tworzenia obciążeń dla określonych grup, wykonaj czynności opisane w temacie Włącz ustawienie dzierżawy deweloperskiej.

Zrzut ekranu przedstawiający przełącznik dzierżawy deweloperskiej dla obciążeń.

Konfigurowanie frontonu

Aby skonfigurować przykładowy fronton projektu:

Sprawdź, czy Node.js i narzędzie npm są zainstalowane. Instalacja narzędzia npm musi być w wersji 9 lub nowszej. W przeciwnym razie zainstaluj najnowsze wersje Node.js i npm.
Sklonuj przykładowe repozytorium Microsoft Fabric do tworzenia obciążeń.

Poniższa lista zawiera opis układu katalogu pakietów, składników i zasobów:
- Pakiet: lokalizacja pakietu obciążenia. Pakiet zawiera zasoby frontonu, w tym manifesty i zasoby.
- src: kod obciążenia zawierający następujące zasoby:
  - index.ts: główny plik inicjalizacyjny, w tym bootstrap oraz ramki iFrame index.worker i index.ui (więcej szczegółów znajduje się w dalszej części tego artykułu).
  - App.tsx: ten plik kieruje ścieżki do stron. Na przykład /sample-workload-editor jest przekazywany do funkcji SampleWorkloadEditor w sekcji components.
  - Zasoby: lokalizacja obrazów (.jpg, .jpeg i png), do których można się odwoływać w manifeście i pokazana w interfejsie użytkownika. Na przykład assets/github.jpg parametr jest ustawiany w manifeście jako ikona produktu.
  - components: lokalizacja kodu interfejsu użytkownika, w tym widok edytora i inne widoki używane przez przykład (wstążka, strona uwierzytelniania i panele).
  - kontroler: kontroler wywołuje interfejsy API zestawu SDK.
  - modele: kontrakty i modele używane przez interfejs użytkownika oraz do komunikacji z backendem szablonu.
- tools: Elementy, których można użyć do tworzenia ustawień i konfiguracji.
  - webpack.config.js: użyj tego pliku, aby skonfigurować lokalny serwer Node.js.
  - Konfiguracja sieci Web i czytnik/procesor manifestu.
- walidacja: w przykładzie użyto validateSchema.js metody sprawdzania poprawności schematów plików JSON i produktu. Jest ona skonfigurowana do uruchamiania w systemie npm start.
W folderze repozytorium przejdź do folderu Frontend , aby zainstalować pliki projektu:
```
<repository folder>\Frontend> npm install
```
Uruchom serwer, uruchamiając następujące polecenie:
```
<repository folder>\Frontend> npm start
```
To polecenie uruchamia lokalny serwer Node.js (przy użyciu pakietu webpack), z którego usługa Microsoft Fabric nawiązuje połączenie, gdy jest w trybie dewelopera.

Aby uzyskać informacje na temat szczegółów portów wyświetlanych po uruchomieniu serwera, zobacz uwagi dotyczące lokalnego serwera hosta.

Bieżący port to 60006.

Po uruchomieniu serwera localhost przejdź do adresu URL 127.0.0.1:60006/manifests , aby otworzyć zagregowany manifest utworzony w folderze Frontend/Package .

Jeśli zmienisz pliki w folderze Frontend/Package , uruchom npm start go ponownie.

To ustawienie jest utrwalane w bieżącej przeglądarce.

Przykład "Hello world"

Aby uruchomić scenariusz testowy "hello world":

Uruchom serwer lokalny (wykonaj kroki opisane w temacie Wprowadzenie , aby uruchomić zarówno przykłady obciążeń frontonu, jak i zaplecza) i upewnij się, że tryb dewelopera jest włączony.
W menu obszaru roboczego wybierz ikonę Utwórz centrum (czasami ikona znajduje się w obszarze Pokaż więcej wielokropka).
Wybierz opcję Zobacz wszystko.
W obszarze Przykładowe obciążenie wybierz kartę Przykładowy element , aby utworzyć element.

Nowy element wygląda podobnie do tego przykładu:

Zrzut ekranu interfejsu użytkownika obrazu Main Sample.

Zapoznaj się z różnymi elementami sterującymi, aby poznać możliwości interfejsu API Fabric WorkloadClient (zestawu SDK obciążeń):

Otwieranie powiadomień i okien dialogowych
Przejdź do stron
Pobierz ustawienia motywu i obciążenia roboczego
Wykonywanie akcji

Większość dostępnych funkcji zestawu SDK jest skonfigurowana jako akcje przycisku lub zarejestrowana jako wywołania zwrotne. Wyniki zazwyczaj są powiadomieniem lub polem komunikatu, które pokazuje, że interfejs API został wywołany.

Na przykład:

Wykonaj akcję wywołuje interfejs API action.execute() dla akcji o nazwie sample.Action. Funkcja akcji polega na wyświetlaniu powiadomienia.
Wybierz Zapisz na wstążce, aby wywołać interfejs API dialog.open(). Interfejs API otwiera okno dialogowe, w którym użytkownik wprowadza nazwę i zapisuje element w Fabric. Aby uzyskać więcej informacji na temat okna dialogowego, zobacz sekcję CRUD.
Przycisk Pobierz ustawienia motywu wyświetla listę konfiguracji motywu Fabric (za pośrednictwem interfejsu API theme.get()).

Interfejs użytkownika przykładowego obciążenia jest hostowany w izolowanym elemencie Fabric iframe, który jest wyświetlany w trybie deweloperskim na stronie internetowej.

Zrzut ekranu przedstawiający obraz osadzania elementu iFrame.

Uwaga

Element iframe w trybie piaskownicy obsługuje atrybuty allow-same-origin i allow-scripts.

Aby uzyskać więcej informacji o sandbox i atrybutach, zobacz MDN Web Docs.

Zrozumienie kodu

W poniższych sekcjach opisano elementy kodu i istotne zagadnienia.

bootstrap()

Przed uruchomieniem sprawdź ścieżkę, aby sprawdzić, czy musisz zamknąć okno. Ten krok jest wymagany, jeśli używasz interfejsu API uwierzytelniania .

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

Każda aplikacja obciążenia roboczego Fabric musi obsługiwać inicjalizację w dwóch trybach:

Tryb UI: aplikacja działająca w trybie UI jest ładowana w widocznych ramkach iframe. Nasłuchuje ona własnych zmian trasy w celu renderowania odpowiednich składników interfejsu użytkownika, takich jak strony, panele i okna dialogowe.
Tryb roboczy: aplikacja w trybie roboczym działa w niewidocznym elemencie iFrame. Niewidoczny element iFrame jest używany głównie do odbierania poleceń zewnętrznych, a następnie odpowiadania na nie.

Interfejs @ms-fabric/workload-client API udostępnia metodę bootstrap() upraszczania kroków inicjowania. Metoda wewnętrznie wykrywa, czy bieżąca bootstrap() aplikacja jest ładowana w trybie interfejsu użytkownika, czy w trybie roboczym. Następnie wywołuje odpowiednią metodę inicjowania (initializeUI lub initializeWorker). Po zakończeniu inicjalizacji bootstrap() powiadamia platformę mikrofrontendową Fabric o powodzeniu lub niepowodzeniu inicjalizacji.

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

index.worker

index.worker jest głównym onAction rejestrem. Obsługuje zdarzenia wysyłane przez hosta sieci szkieletowej, które są wyzwalane przez wykonane akcje.

Akcje mogą być wysyłane przez obciążenie robocze do Fabric, a następnie zwrotnie wywoływane w procedurze obsługi onAction, lub mogą być inicjowane przez host Fabric. Na przykład po wybraniu pozycji Utwórz przykładowy element — tylko Frontend platforma Fabric wyzwala akcję open.createSampleWorkloadFrontendOnly, a procedura obsługi onAction inicjuje otwarcie głównej strony interfejsu użytkownika obciążenia. Bieżąca wartość obszaru roboczego objectId jest również przekazywana do środowiska działającego wyłącznie po stronie frontendu.

Sekwencja jest pokazana w poniższym przykładzie kodu:

   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

Funkcja initialize() renderuje strukturę DOM Reacta, w której osadzona jest funkcja App. Aby wywołać funkcje interfejsu API, przekaż uchwyt workloadClient SDK, który jest używany w całym kodzie.

Klasa FluentProvider zapewnia spójność stylu w różnych kontrolkach FluentUI. Oto przykład:

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

Proces tworzenia

Funkcja App kieruje kod do SampleWorkloadEditor. Funkcja zwraca wartość dla React.JSX.Element.
Funkcja zawiera strukturę interfejsu użytkownika. Struktura interfejsu użytkownika zawiera wstążkę oraz kontrolki strony, takie jak przyciski i pola wprowadzania.
Informacje zbierane od użytkownika są przechowywane za pośrednictwem punktu zaczepienia React useState() .
Procedury obsługi kontrolek interfejsu użytkownika wywołują funkcje SampleWorkloadController i przekazują odpowiednie zmienne stanu.
Aby zapewnić obsługę operacji CRUD, stan utworzonego/załadowanego elementu jest przechowywany w artifactItem wraz z workspaceObjectId oraz przykładową implementacją zmiennych payloadu.

W poniższych przykładach użyto interfejsu API notification.open():

Stan:

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

UI:

Te przykłady umożliwiają skonfigurowanie określonych elementów interfejsu użytkownika:

Tytuł:

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

Przycisk „Wyślij”:

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

Procedura obsługi:

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

Kontroler:

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

Operacje CRUD

Chociaż scenariusz obejmujący wyłącznie front-end można łatwo obsłużyć, pełne środowisko pracy dewelopera wymaga zapisywania, odczytywania i edytowania istniejących elementów obciążenia roboczego.

W przewodniku implementacji zaplecza opisano szczegółowo sposób konfigurowania zaplecza i korzystania z niego.

Gdy backend jest uruchomiony i działa, a typ Org.WorkloadSample.SampleWorkloadItem jest zarejestrowany w Fabric, możesz wykonywać operacje CRUD dla tego typu.

Następujące operacje są udostępniane za pomocą interfejsu ItemCrud API.

UTWÓRZ

Aby wykonać przykładowe wywołanie create, użyj poniższego przykładu, który pokazuje, jak po raz pierwszy zapisać element obciążenia roboczego:

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

Nasza przykładowa implementacja przechowuje utworzony element w pliku artifactItem.

Element jest tworzony w aktualnie wybranym obszarze roboczym. Obszar roboczy musi być przypisany do pojemności ustawionej w konfiguracji zaplecza. Aby uzyskać więcej informacji, zobacz dokumentację zaplecza.

Próba utworzenia elementu w niezgodnym obszarze roboczym kończy się niepowodzeniem:

Funkcja zwrotna onCreateFabricItem w backendzie blokuje wywołanie CREATE. Awaria w tym punkcie powoduje niepowodzenie operacji i żaden element nie zostanie utworzony w Fabric. Aby uzyskać więcej informacji, zobacz dokumentację debugowania i rozwiązywania problemów zaplecza.
Obecnie zapisany element nie jest automatycznie wyświetlany w obszarze roboczym. Aby wyświetlić zapisany element w obszarze roboczym, odśwież stronę.

GET

Po wybraniu istniejącego elementu przykładowego obciążenia w widoku obszaru roboczego Fabric przechodzi do ścieżki zdefiniowanej w manifeście frontendu w artifacts>editor>path:

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

Podczas wywoływania metody itemCrud.getItemdane są ładowane zarówno z zaplecza sieci szkieletowej, jak i z zaplecza obciążenia. Dane z obu źródeł są ładowane do artifactItem obiektu otwartego graficznego interfejsu użytkownika.

Zrzut ekranu przedstawiający otwieranie istniejących elementów w obszarze roboczym.

AKTUALIZACJA

Aby zaktualizować istniejący element, użyj polecenia itemCrud.updateItem. Ładunek obciążenia jest aktualizowany przez zaplecze obciążenia. W usłudze Fabric po aktualizacji zmienia się tylko element lastModifiedTime.

USUŃ

Operację delete można wywołać albo w widoku obszaru roboczego Fabric jako akcję ogólną dostępną dla wszystkich elementów, albo za pomocą jawnego wywołania z poziomu obciążenia do itemCrud.deleteItem.

Oba typy połączeń przechodzą przez funkcję wywołania zwrotnego onDeleteItem zaplecza obciążenia.

Wyświetlanie działań uwierzytelniania

W edytorze przykładowego obciążenia można wyświetlić działanie uwierzytelniania.

Przed użyciem interfejsu API uwierzytelniania skonfiguruj aplikację do uwierzytelniania przy użyciu identyfikatora Entra firmy Microsoft.

Upewnij się również, że plik env.dev jest poprawnie skonfigurowany. Aby uzyskać więcej informacji, zobacz Konfigurowanie manifestu lokalnego obciążenia i uzyskiwanie tokenu dla aplikacji.

Debugowanie

Aby wyświetlić elementy workera i ramki iframe interfejsu użytkownika, w przeglądarce naciśnij klawisz F12, aby otworzyć narzędzia deweloperskie przeglądarki. Wybierz kartę Źródła .

Zrzut ekranu przedstawiający debugowanie plików w programie Visual Studio Code.

Punkt przerwania można umieścić w elemencie iframe workera i zobaczyć główny switch dla przychodzącej akcji. Możesz również debugować element iframe interfejsu użytkownika. Możesz na przykład debugować kod wewnątrz SampleWorkloadEditorpliku .

Płynne kontrolki interfejsu użytkownika

Obciążenia interfejsu użytkownika korzystają z kontrolek Fluent UI, aby zapewnić spójność wizualną z usługą Fabric oraz ułatwić tworzenie. Przykładowy projekt obciążenia zawiera przykłady używania najbardziej typowych kontrolek.

Aby uzyskać więcej informacji, zobacz Fluent UI.

Dostosowywanie manifestu frontonu

Manifest frontendu opisuje aspekty interfejsu użytkownika obciążenia roboczego, w tym wygląd produktu, nazwy, zasoby wizualne i dostępne działania. Manifest frontendu jest głównym punktem kontaktu między Fabric a obciążeniem roboczym.

W przypadku naszego przykładowego obciążenia roboczego manifest jest ładowany do platformy Fabric w trybie deweloperskim. Sekcje manifestu, definicje i przykłady manifestu są przedstawione w plikach manifestu frontendu.

Zmiany wpisów manifestu, ustawień akcji i aktualizacji zasobów wizualnych są wyświetlane w czasie rzeczywistym po odświeżeniu strony.

Obsługiwane interfejsy API zestawu SDK klienta

Obsługiwane są następujące interfejsy API:

notification.open
notification.hide
panel.open
Zamknij panel
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

Aby uzyskać więcej informacji, zobacz pakiet @ms-fabric/workload-client.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-29