Microsoft Fabric ön ucunu genişletin

İş yükleri oluşturmak ve Doku deneyimini genişleten özel özellikler oluşturmak için Microsoft Fabric İş Yükü Geliştirme Seti'ni kullanabilirsiniz. Fabric platformu, bağımsız yazılım sağlayıcısı (ISV) özellikleriyle birlikte çalışabilir olacak şekilde tasarlanmıştır. Örneğin, bir ISV'nin ön yüzünü bir Fabric çalışma alanı öğesinin bağlamına yerleştirerek doğal 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 Fabric portalında korumalı alana alınmış bir <iframe> öğesi içinde barındırır ve ç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.
Fabric'in görünümünü ve kullanım hissini yansıtan, 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.

Fabric'te iş yükü geliştirme özelliğini etkinleştirin

Kiracı yöneticisi önce kiracı ayarlarında iş yükü geliştirme özelliğini etkinleştirmelidir. Ö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ükü geliştirme kiracısı değiştirme 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: bootstrap ile index.worker ve index.ui iFrame'lerini içeren ana başlatma dosyası (ayrıntılar için bu makalenin ilerleyen bölümlerine bakın).
  - App.tsx: Bu dosya yolları sayfalara yönlendirir. Örneğin, /sample-workload-editor, components altındaki SampleWorkloadEditor işlevine 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ı arayüzü tarafından kullanılan ve boilerplate’in backend’iyle iletişim kurmak için gerekli olan 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 . npm start üzerinde ç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ı 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/manifestsgidin.

Ö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 Merkez oluştur simgesini seçin (bazen simge Daha fazla göster üç nokta simgesinde 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ü.

Fabric WorkloadClient API’sinin (iş yükü SDK’sı) özelliklerini görmek için çeşitli denetimleri inceleyin:

Bildirimleri ve iletişim kutularını açma
Sayfalara git
Tema ve iş yükü ayarlarını alma
Eylemleri gerçekleştir

Kullanılabilir SDK işlevlerinin çoğu ya düğme işlemleri olarak yapılandırılır ya da geri çağrı 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.Action adlı bir eylemle action.execute() API'sini çağırır. 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 girebildiği ve öğeyi Fabric’e 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, Fabric tema yapılandırmalarının bir listesini (theme.get() API'si aracılığıyla) gösterir.

Örnek iş yükü kullanıcı arayüzü, web sayfasında geliştirici modunda gösterilen, Fabric korumalı alanındaki bir iframe öğesinde barındırılır.

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

Not

Korumalı alana alınmış iframe öğesi, allow-same-origin ve allow-scripts özniteliklerini destekler.

korumalı alan ve öznitelikler hakkında daha fazla bilgi için MDN Web Docs'a bakın.

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 kontrol edin. 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 Fabric iş yükü uygulaması iki modda başlatılmayı 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 kaydıdır. Fabric ana bilgisayarının, yürütülen eylemler tarafından tetiklenen gönderdiği olayları işler.

Eylemler, iş yükü tarafından Fabric'e gönderilip onAction işleyicisinde geri çağrılabilir veya Fabric ana bilgisayarı tarafından başlatılabilir. Örneğin, Örnek Öğe Oluştur - Yalnızca Ön Uç seçeneğini belirlediğinizde Fabric, open.createSampleWorkloadFrontendOnly eylemini tetikler ve onAction işleyicisi iş yükünün ana kullanıcı arayüzü sayfasının açılmasını başlatır. Geçerli çalışma alanı objectId değeri de yalnızca ön uca yönelik deneyime aktarılır.

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

initialize() işlevi, App işlevinin gömülü olduğu React DOM'unu oluşturur. API çağrılarını yürütmek için, kod genelinde kullanılan workloadClient SDK tanıtıcısını geçirin.

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. İşlev, React.JSX.Element için bir 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 SampleWorkloadController işlevlerini çağırır ve ilgili durum değişkenlerini aktarır.
CRUD işlemlerini desteklemek için, oluşturulan/yüklenen öğenin durumu, workspaceObjectId ve yük değişkenlerinin örnek bir uygulamasıyla birlikte artifactItem içinde depolanır.

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>

İşleyici:

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 durumdaysa ve Org.WorkloadSample.SampleWorkloadItem türü Fabric’e kaydedildiyse, bu tür üzerinde CRUD işlemleri gerçekleştirebilirsiniz.

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

OLUŞTUR

create için örnek bir çağrı yapmak üzere, iş yükü öğesinin ilk kez nasıl kaydedileceğini 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:

Arka uçtaki onCreateFabricItem geri çağırımı, CREATE çağrısını 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, Fabric, ön uç bildirim dosyasında artifacts>editor>path tanımlanan yola gider:

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

itemCrud.getItem çağrıldığında, veriler hem Fabric arka ucundan hem de iş yükü arka ucundan 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ü.

Güncelleme

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

SİL

delete işlemini, Fabric çalışma alanı görünümünde tüm öğeler için kullanılabilen genel bir eylem olarak ya da iş yükünden itemCrud.deleteItem öğesine yapılan açık bir çağrı aracılığıyla çağırabilirsiniz.

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 manifestosunu 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ü.

Worker iframe öğesine bir kesme noktası yerleştirebilir ve gelen eylemde ana switch öğesini 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, Fabric ile görsel tutarlılık sağlamak ve geliştirmeyi kolaylaştırmak 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.

Frontend manifest ö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ç bildirim dosyası, Fabric ile iş yükü arasındaki ana bağlantı noktasıdır.

Örnek iş yükümüzde manifest, Geliştirici modunda Fabric'e 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:

bildirim.aç
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?

Son güncelleştirme: 2026-09-29