Microsoft Fabric ön ucu genişletme

İş yükleri oluşturmak ve Doku deneyimini genişleten özel özellikler oluşturmak için Microsoft Fabric İş Yükü Geliştirme Seti'ni kullanabilirsiniz. Doku platformu, bağımsız yazılım satıcısı (ISV) özellikleriyle birlikte çalışabilecek şekilde tasarlanmıştır. Örneğin, bir ISV'nin ön ucuna Doku çalışma alanı öğesi bağlamında ekleyerek yerel ve tutarlı bir kullanıcı deneyimi oluşturmak için öğe düzenleyicisini kullanabilirsiniz.

Bu makalede, özel bir UX iş yükü web uygulamasını Microsoft Fabric ile tümleştirmek için kılavuz olarak Microsoft Fabric iş yükü geliştirme örnek deposunu kullanacaksınız. Proje ve ayrıntılı örnekler, verimli deneme ve özelleştirme için kendi kullanıcı arabirimi bileşenlerinizi ve eylemlerinizi Doku çalışma zamanı ortamıyla sorunsuz bir şekilde tümleştirmenize yardımcı olur.

Örnek UX iş yükü projesi ön ucu, işlevsellik sağlamak için iş yükü istemci SDK'sını standart bir npm paketi olarak içeren standart bir React web uygulamasıdır.

ISV, projeyi Yapı portalındaki korumalı <iframe> bir öğenin içinde barındırıp çalıştırır. Bir öğe düzenleyicisi de dahil olmak üzere ISV'ye özgü kullanıcı arabirimi deneyimleri sunar.

SDK, normal bir web uygulamasını Doku portalında sorunsuz çalışan bir mikro ön uç web uygulamasına dönüştürmek için gereken tüm gerekli arabirimleri, API'leri ve bootstrap işlevlerini sağlar.

SDK örnek bir UX iş yükü projesi sağlar. Örnek:

Kullanılabilir SDK çağrılarının çoğunun nasıl kullanılacağını gösterir.
Doku'nun genel görünümüyle eşleşen Fluent UI tabanlı genişletilebilir şeridin bir örneğini gösterir.
Kolay özelleştirmeye olanak tanır.
Doku geliştirici modu açıkken Doku'daki değişiklikleri gerçek zamanlı olarak gözlemlemenizi sağlar.

Önkoşullar

UX iş yükü web uygulaması

Bu paket Fluent kullanıcı arabiriminin üzerine kurulmuştur ve React için tasarlanmıştır.
UX iş yükü ön uç bildirimi

UX iş yükü ön uç bildirimi, ISV'nin sağladığı bir JSON kaynağıdır. Dosya, iş yükü web uygulamasının URL'si ve ISV öğesinin görünen adı ve ilişkili simgeler gibi çeşitli kullanıcı arabirimi ayrıntıları dahil olmak üzere iş yüküyle ilgili temel bilgileri içerir. ISV, kullanıcılar Doku portalındaki öğelerle etkileşime geçtiğinde ne olacağını özelleştirmek için bildirim dosyasını kullanabilir.

Bu pakette ön uç bildirim dosyaları paket klasöründe bulunur. Bildirim dosyası, iş yükü bildiriminin ve bileşenlerinin ayrıntılı bir açıklamasını içerir.

Doku'da iş yükü geliştirme özelliğini etkinleştirme

Kiracı yöneticisinin önce Microsoft Fabric yönetici portalında iş yükü geliştirme özelliğini etkinleştirmesi gerekir. Özellik, kuruluşun tamamı veya kuruluş içindeki belirli gruplar için etkinleştirilebilir. Kiracı yöneticisi için, belirli gruplar için iş yükü geliştirme özelliğini etkinleştirmek için Geliştirme kiracısı ayarını etkinleştirme başlığı altında açıklanan adımları tamamlayın.

İş yükleri geliştirme kiracı anahtarının ekran görüntüsü.

Ön ucu ayarlama

Örnek proje ön ucu ayarlamak için:

Node.js ve npm'nin yüklendiğini doğrulayın. npm yüklemesi sürüm 9 veya üzeri olmalıdır. Aksi takdirde, Node.js ve npm'nin en son sürümlerini yükleyin.
Microsoft Fabric iş yükü geliştirme örnek deposunu kopyalayın.

Aşağıdaki listede paket dizini düzeni, bileşenleri ve kaynakları açıklanmaktadır:
- Paket: İş yükü paketinin konumu. Paket, bildirimler ve varlıklar da dahil olmak üzere ön uç kaynaklarını içerir.
- src: Bu kaynakları içeren iş yükü kodu:
  - index.ts: ve ve index.ui iFrame'ler de dahil olmak üzere bootstrap ana başlatma dosyası (bu makalenin index.worker devamında yer alan ayrıntılara bakın).
  - App.tsx: Bu dosya yolları sayfalara yönlendirir. Örneğin, /sample-workload-editor altında componentsişlevine SampleWorkloadEditor yönlendirilir.
  - varlıklar: Bildirimde başvurulabilen ve kullanıcı arabiriminde gösterilebilen görüntülerin (.jpg, .jpeg ve png) konumu. Örneğin, assets/github.jpg bildirimde ürün simgesi olarak ayarlanır.
  - bileşenler: Düzenleyici görünümü ve örneğin kullandığı diğer görünümler (şerit, kimlik doğrulama sayfası ve paneller) dahil olmak üzere kullanıcı arabirimi kodunun konumu.
  - denetleyici: Denetleyici SDK API'lerini çağırır.
  - modeller: Kullanıcı arabirimi tarafından ve ortak ağın arka ucuyla iletişim için kullanılan sözleşmeler ve modeller.
- araçlar: Ayarlar ve yapılandırmalar oluşturmak için kullanabileceğiniz öğeler.
  - webpack.config.js: Yerel Node.js sunucusunu yapılandırmak için bu dosyayı kullanın.
  - Web yapılandırması ve bildirim okuyucu/işlemci.
- doğrulama: Örnek, ürün ve öğe JSON dosya şemalarını doğrulamak için kullanır validateSchema.js . üzerinde npm startçalışacak şekilde yapılandırılmıştır.
Depo klasörünün içinde, proje dosyalarını yüklemek için Ön Uç klasörüne gidin:
```
<repository folder>\Frontend> npm install
```
Aşağıdaki komutu çalıştırarak sunucuyu başlatın:
```
<repository folder>\Frontend> npm start
```
Bu komut, Microsoft Fabric'in geliştirici modundayken bağlandığı bir yerel Node.js sunucusu (webpack kullanarak) başlatır.

Sunucu başlatıldıktan sonra görüntülenen bağlantı noktası ayrıntıları hakkında bilgi için yerel konak sunucu notlarına bakın.

Geçerli bağlantı noktası şeklindedir 60006.

Localhost sunucusu başlatıldıktan sonra, Ön Uç/Paket klasöründe oluşturulan toplu bildirimi açmak için URL'ye 127.0.0.1:60006/manifests gidin.

Ön Uç/Paket klasörünün içindeki dosyaları değiştirirseniz yeniden çalıştırınnpm start.

Bu ayar geçerli tarayıcıda kalıcıdır.

"Merhaba dünya" örneği

"Merhaba dünya" test senaryosunu çalıştırmak için:

Yerel sunucuyu başlatın (Hem ön uç hem de arka uç iş yükü örneklerini çalıştırmaya başlama'daki adımları izleyin) ve geliştirici modunun etkinleştirildiğinden emin olun.
Çalışma alanı menüsünde Hub oluştur simgesini seçin (bazen simge Daha fazla üç nokta göster bölümünde bulunur).
Tümünü gör'ü seçin.
Örnek İş Yükü'nin altında Örnek Öğe kartını seçerek bir öğe oluşturun.

Yeni öğe şu örneğe benzer:

Ana Örnek Kullanıcı Arabirimi görüntü arabiriminin ekran görüntüsü.

Doku WorkloadClient API'sinin (iş yükü SDK'sı) özelliklerini görmek için çeşitli denetimleri keşfedin:

Bildirimleri ve iletişim kutularını açma
Sayfalara git
Tema ve iş yükü ayarlarını alma
Yürütme eylemleri

Kullanılabilir SDK işlevlerinin çoğu düğme eylemleri olarak yapılandırılır veya geri arama olarak kaydedilir. Sonuçlar genellikle bir API'nin çağrıldığını gösteren bir bildirim veya ileti kutusu olur.

Örneğin:

Bir Eylem Yürüt, sample adlı bir eylemle action.execute() API'sini çağırır. Eylem. Eylemin işlevi bir bildirim göstermektir.
Dialog.open() API'sini çağırmak için şeritte Kaydet'i seçin. API, kullanıcının bir ad girdiği ve öğeyi Doku'ya kaydettiği bir iletişim kutusu açar. İletişim kutusu hakkında daha fazla bilgi için CRUD bölümüne bakın.
Tema Ayarlarını Al düğmesi, Doku tema yapılandırmalarının listesini gösterir (theme.get() API'sini kullanarak).

Örnek iş yükü kullanıcı arabirimi, web sayfası için geliştirici modunda gösterilen bir Doku korumalı iframe öğesinde barındırılır.

iFrame ekleme görüntüsünün ekran görüntüsü.

Not

Korumalı iframe öğe ve allow-scriptsözniteliklerini allow-same-origin destekler.

Korumalı alan ve öznitelikler hakkında daha fazla bilgi için bkz. MDN Web Docs.

Kodu anlama

Aşağıdaki bölümlerde kod öğeleri ve ilgili konular açıklanmaktadır.

bootstrap()

Önyüklemeden önce, pencereyi kapatmanız gerekip gerekmediğini görmek için yolu denetleyin. Kimlik doğrulama API'sini kullanıyorsanız bu adım gereklidir.

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

Her Doku iş yükü uygulaması iki modda başlatmayı desteklemelidir:

UI modu: Ui modundaki bir uygulama görünür iFrame'lerde yüklenir. Sayfalar, paneller ve iletişim kutuları gibi ilgili kullanıcı arabirimi bileşenlerini işlemek için kendi yol değişikliklerini dinler.
Çalışan modu: Çalışan modundaki bir uygulama görünmez bir iFrame'de çalışır. Görünmez iFrame öncelikli olarak dış komutları almak ve bunlara yanıt vermek için kullanılır.

API, @ms-fabric/workload-client başlatma adımlarını basitleştirmek için bir bootstrap() yöntem sağlar. yöntemi, bootstrap() geçerli uygulamanın kullanıcı arabirimi modunda mı yoksa çalışan modunda mı yüklendiğini dahili olarak algılar. Ardından uygun başlatma yöntemini (initializeUI veya initializeWorker) çağırır. Başlatma tamamlandığında, bootstrap() Yapı mikro ön uç çerçevesine başlatma başarılı veya başarısız olduğunu bildirir.

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

index.worker

index.worker ana onAction kayıttır. Yürütülen eylemler tarafından tetiklenen Doku ana bilgisayarının gönderdiği olayları işler.

Eylemler iş yükü tarafından Doku'ya gönderilip işleyiciye onAction geri çağrılabilir veya Doku konağı tarafından başlatılabilir. Örneğin, Örnek Öğe Oluştur - Yalnızca Ön Uç'u seçtiğinizde, Doku eylemini open.createSampleWorkloadFrontendOnlytetikler ve onAction işleyici iş yükü ana kullanıcı arabirimi sayfasını açmayı başlatır. Geçerli çalışma alanı objectId değeri de yalnızca ön uç deneyimine geçirilir.

Sıra aşağıdaki kod örneğinde gösterilmiştir:

   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

işlevi, initialize() işlevin eklendiği React DOM'sini App işler. API çağrılarını çağırmak için kod boyunca kullanılan SDK tanıtıcısını geçirin workloadClient .

sınıfı, FluentProvider çeşitli FluentUI denetimleri arasında stil tutarlılığı sağlar. Bir örnek aşağıda verilmiştir:

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

Geliştirme akışı

App işlevi kodu adresine SampleWorkloadEditoryönlendirir. işlevi için React.JSX.Elementbir değer döndürür.
İşlev, kullanıcı arabirimi yapısını içerir. Ui yapısı şerit ve düğmeler ve giriş alanları gibi sayfa denetimlerini içerir.
Kullanıcıdan toplanan bilgiler React useState() kancası aracılığıyla depolanır.
Ui denetimlerinin işleyicileri işlevleri çağırır SampleWorkloadController ve ilgili durum değişkenlerini geçirir.
CRUD işlemlerini desteklemek için, oluşturulan/yüklenen öğenin durumu ve yük değişkenlerinin örnek uygulaması ile workspaceObjectId depolanırartifactItem.

Aşağıdaki örnekler notification.open() API'sini kullanır:

Durum:

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

UI:

Bu örneklerde belirli kullanıcı arabirimi öğeleri yapılandırılır:

Başlık:

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

Gönder düğmesi:

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

Işleyicisi:

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

Denetleyici:

  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 işlemleri

Yalnızca ön uç geliştirme senaryosu kolayca destekleniyor olsa da, tam uçtan uca geliştirici deneyimi mevcut iş yükü öğelerini kaydetmeyi, okumayı ve düzenlemeyi gerektirir.

Arka uç uygulama kılavuzunda arka ucun nasıl ayarlanacağı ve kullanılacağı ayrıntılı olarak açıklanmaktadır.

Arka uç çalışır durumdayken ve Org.WorkloadSample.SampleWorkloadItem tür Doku'ya kaydedildiğinde, bu tür üzerinde CRUD işlemleri gerçekleştirebilirsiniz.

Aşağıdaki işlemler ItemCrud API'sini kullanarak kullanıma sunulur.

CREATE

için örnek bir çağrı yapmak için create, iş yükü öğesini ilk kez kaydetmeyi gösteren aşağıdaki örneği kullanın:

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

Örnek uygulamamız, oluşturulan öğeyi içinde artifactItemdepolar.

Öğe, seçili durumdaki çalışma alanında oluşturulur. Çalışma alanı, arka uç yapılandırmasında ayarlanan kapasiteye atanmalıdır. Daha fazla bilgi için arka uç belgelerine bakın.

Uyumsuz bir çalışma alanı altında öğe oluşturma girişimi başarısız oluyor:

onCreateFabricItem Arka uçtaki geri çağırma, çağrıyı CREATE engeller. Bu noktadaki bir hata işlemin başarısız olmasına neden olur ve Doku'da hiçbir öğe oluşturulmaz. Daha fazla bilgi için arka ucun hata ayıklama ve sorun giderme belgelerine bakın.
Şu anda, kaydedilmiş bir öğe çalışma alanında otomatik olarak görüntülenmez. Çalışma alanında kaydedilmiş bir öğeyi görüntülemek için sayfayı yenileyin.

GET

Çalışma alanı görünümünde mevcut bir örnek iş yükü öğesini seçtiğinizde, Doku içindeki ön uç bildiriminde artifacts>>editorpathtanımlanan yola gider:

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

çağırdığınızda itemCrud.getItemveriler hem Doku arka uçtan hem de iş yükü arka uçtan yüklenir. Her iki kaynaktan veriler açık GUI nesnesine artifactItem yüklenir.

Çalışma alanında var olan öğeleri açma işleminin ekran görüntüsü.

UPDATE

Mevcut bir öğeyi güncelleştirmek için kullanın itemCrud.updateItem. İş yükü yükü, iş yükü arka ucu tarafından güncelleştirilir. Doku'da, yalnızca bir güncelleştirmeden sonra öğenin lastModifiedTime değişiklikleri değişir.

SİL

İşlemi Doku çalışma alanı görünümünde tüm öğeler için genel bir eylem olarak veya iş yükünden itemCrud.deleteItemöğesine yapılan açık bir çağrıyla çağırabilirsinizdelete.

Her iki çağrı türü de iş yükü arka ucun onDeleteItem geri çağırması üzerinden geçer.

Kimlik doğrulama etkinliğini görüntüleme

Örnek iş yükü düzenleyicisinde kimlik doğrulama etkinliğini görüntüleyebilirsiniz.

Kimlik doğrulama API'sini kullanmadan önce, uygulamanızı Microsoft Entra Id kullanarak kimlik doğrulaması yapmak üzere yapılandırın.

Ayrıca env.dev dosyanızın doğru yapılandırıldığından emin olun. Daha fazla bilgi için bkz . İş yükü yerel bildirimini yapılandırma ve uygulamanız için belirteç alma.

Hata Ayıklama

Çalışan ve kullanıcı arabirimi iframe öğelerini görmek için tarayıcıda F12'yi seçerek tarayıcı geliştirici araçlarını açın. Kaynaklar sekmesini seçin.

Visual Studio Code'da hata ayıklama dosyalarının ekran görüntüsü.

Çalışan iframe öğesine bir kesme noktası yerleştirebilir ve gelen eylemde ana switch öğeyi görebilirsiniz. Kullanıcı arabirimi iframe öğesinde de hata ayıklayabilirsiniz. Örneğin, içindeki SampleWorkloadEditorkodda hata ayıklayabilirsiniz.

Fluent UI denetimleri

UX iş yükleri, Doku ile görsel tutarlılık ve geliştirme kolaylığı için Fluent UI denetimlerini kullanır. Örnek iş yükü projesi, en yaygın denetimlerin nasıl kullanılacağına ilişkin örnekler sağlar.

Daha fazla bilgi için bkz . Fluent Ui.

Ön uç bildirimi özelleştirmesi

Ön uç bildirimi, ürün görünümü, adlar, görsel varlıklar ve kullanılabilir eylemler dahil olmak üzere iş yükünün ön uç yönlerini açıklar. Ön uç bildirimi, Doku ile iş yükü arasındaki ana iletişim noktasıdır.

Örnek iş yükümüz için bildirim Geliştirici modunda Doku'ya yüklenir. Bildirim bölümleri, tanımları ve bildirimin örnekleri ön uç bildirim dosyalarında gösterilir.

Bildirimin girdilerinde, eylem ayarlarında ve görsel varlıklardaki güncelleştirmelerde yapılan değişiklikler, sayfayı yeniledikten sonra gerçek zamanlı olarak gösterilir.

İstemci SDK'sı tarafından desteklenen API'ler

Aşağıdaki API'ler desteklenir:

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
ayarlar.get
settings.onChange
errorHandling.openErrorDialog
errorHandling.handleRequestFailure
itemCrud.createItem
itemCrud.getItem
itemCrud.updateItem
itemCrud.deleteItem
itemSchedule.runItemJob
itemSchedule.cancelItemJob
itemRecentRuns.open

Daha fazla bilgi için bkz . @ms-fabric/workload-client paketi.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-29