Panduan Penyiapan Terperinci

Setelah Anda memiliki akses ke kode (baik di Codespace atau secara lokal) dengan mengikuti panduan Memulai, ikuti langkah-langkah berikut:

Petunjuk / Saran

Jika Anda tidak ingin mengikuti langkah-langkah secara manual, minta GitHub Copilot untuk membantu Anda melakukan pekerjaan. Repositori Starter-Kit diaktifkan AI dan Copilot dapat memandu Anda melalui proses penyiapan secara interaktif. Coba perintah ini: "Bantu saya memulai repositori ini dan jalankan sampel HelloWorld."

Langkah 1: Jalankan skrip penyiapan

Skrip penyiapan mengotomatiskan sebagian besar konfigurasi (pendaftaran aplikasi, default, dll.).

# From the repo root
pwsh ./scripts/Setup/Setup.ps1 -WorkloadName "Org.MyWorkload"

Menyiapkan catatan skrip:

  • WorkloadName harus mengikuti pola Organization.WorkloadName. Untuk pengembangan, gunakan Org.[YourWorkloadName].
  • Jika menggunakan kembali aplikasi Microsoft Entra yang ada, pastikan URI pengalihan SPA dikonfigurasi seperti yang dijelaskan dalam panduan penyiapan manual repositori.
  • Di macOS/Linux, gunakan pwsh untuk menjalankan skrip.
  • Pastikan bahwa kebijakan eksekusi PowerShell diatur ke Tidak Dibatasi dan file tidak diblokir jika Anda diminta untuk memulai file PowerShell.
  • Ikuti panduan yang disediakan skrip untuk mendapatkan semua pengaturan

Skrip Penyetelan dapat dijalankan beberapa kali. Jika nilai sudah ada, Anda akan ditanya apakah mereka harus digantikan. Jika Anda ingin menimpa semuanya, gunakan parameter Force.

Nota

Jika Anda mengalami kesalahan penyiapan, lihat kesalahan penyiapan PowerShell di bagian pemecahan masalah di bawah ini.

Petunjuk / Saran

Jika Anda mengalami masalah dengan skrip penyiapan otomatis, Anda dapat mengikuti Panduan Penyiapan Manual untuk konfigurasi manual langkah demi langkah.

Langkah 2: Mulai lingkungan pengembangan

Jalankan server dev (front end + API) dan daftarkan instans lokal Anda dengan Fabric melalui DevGateway.

# Terminal 1: start local dev server
pwsh ./scripts/Run/StartDevServer.ps1

# Terminal 2: start DevGateway to register your local instance with Fabric
pwsh ./scripts/Run/StartDevGateway.ps1

Langkah 3: Mengaktifkan fitur pengembang di Fabric

Navigasikan ke portal Fabric dan konfigurasikan pengaturan yang diperlukan:

3.1 Mengonfigurasi pengaturan penyewa di Portal Admin:

Buka pengaturan Portal Admin dan aktifkan pengaturan penyewa berikut:

  • Pengelola kapasitas dan kontributor dapat menambahkan dan menghapus workload tambahan
  • Admin ruang kerja dapat mengembangkan beban kerja mitra
  • Pengguna dapat melihat dan bekerja dengan beban kerja tambahan yang tidak divalidasi oleh Microsoft

Cuplikan layar pengaturan penyewa.

3.2 Aktifkan Mode Pengembang Fabric:

Navigasi ke Pengaturan Pengembang Fabric dan aktifkan Mode Pengembang Fabric:

Cuplikan layar mode pengembang Fabric.

Anda sekarang siap untuk membuat Item Hello World pertama Anda di Fabric.

Langkah 4: Uji item HelloWorld

Anda dapat mengakses beban kerja dari Workload Hub (mencari nama beban kerja Anda) atau menavigasi secara langsung. Kemudian buat item Halo Dunia.

Steps:

  1. Open Fabric Workload Hub: Temukan beban kerja Anda (misalnya, Org.MyWorkload).

    • Navigasi langsung: https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
    • Ganti <WORKLOAD_NAME> dengan nama beban kerja Anda yang sebenarnya (misalnya, Org.MyWorkload)

  2. Buat item baru: Pilih jenis item Halo Dunia dan pilih ruang kerja pengembangan Anda.

  3. Memverifikasi fungsionalitas: Editor terbuka; konfirmasikan item berfungsi seperti yang diharapkan dan muncul seperti artefak asli di ruang kerja.

Selamat! Anda membuat item pertama dari lingkungan pengembangan Anda.

Langkah 5: Mulai pengkodan

Setelah semuanya disiapkan, Anda dapat mulai membuat item kustom Anda sendiri. Ikuti panduan komprehensif kami untuk mempelajari cara membuat item Fabric kustom:

📖 Panduan Membuat Item Custom Fabric - Panduan ini menyediakan dua pendekatan untuk membuat item:

  • pendekatanAI-Assisted: Gunakan GitHub Copilot untuk panduan interaktif (direkomendasikan untuk pengembang baru)
  • Pendekatan Berskrip Manual: Gunakan skrip PowerShell otomatis untuk penyiapan cepat (direkomendasikan untuk pengembang berpengalaman)

Opsi mulai cepat:

  • Perbarui editor HelloWorld yang ada: Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
  • Atau bangun kerangka item baru dengan skrip: ./scripts/Setup/CreateNewItem.ps1

Selamat mengoding! 🚀

Praktik terbaik

  • Fork repositori: Fork repositori Starter-Kit dan gunakan fork Anda sebagai basis proyek Anda.
  • ** Tetap sinkron: Jaga agar fork Anda tetap sinkron dengan upstream untuk mengadopsi peningkatan.
  • Pertahankan konsistensi struktur proyek: Pertahankan struktur proyek Starter-Kit dan pola organisasi untuk memastikan kompatibilitas dengan pembaruan di masa mendatang dan pertahankan kejelasan kode.
  • Integrasi Starter-Kit reguler: Mengintegrasikan perubahan kode secara teratur dari Starter-Kit ke dalam proyek Anda untuk mendapatkan manfaat dari perbaikan bug, fitur baru, dan pembaruan keamanan. Siapkan proses untuk meninjau dan menggabungkan perubahan upstream secara teratur (bulanan atau triwulanan).
  • Memvalidasi manifes lebih awal: Validasi manifes beban kerja Anda lebih awal dan ikuti izin hak istimewa terkecil.
  • Gunakan kontainer dev: Gunakan kontainer dev atau Codespaces untuk lingkungan yang konsisten dan sekali pakai.
  • Gunakan skrip yang disediakan: Gunakan skrip yang disediakan (Penyiapan, StartDevServer, StartDevGateway) untuk mengotomatiskan penyiapan dan alur kerja harian.

Pemecahan masalah umum

Kesalahan penyiapan PowerShell

Jika Anda mengalami kesalahan selama eksekusi skrip penyiapan, pastikan Anda memiliki PowerShell terbaru yang diinstal dan dikonfigurasi di lingkungan tempat Anda menjalankan skrip.

Cuplikan layar kesalahan penyiapan PowerShell.

Kesalahan kebijakan eksekusi skrip

Jika Anda menemukan: : cannot be loaded because the execution policy is unrestricted

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Port 5173 sedang digunakan

Jika DevServer tidak dapat dimulai pada port 5173, temukan dan hentikan prosesnya:

# Find process using port
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

# Terminate process
Stop-Process -Id <ProcessId> -Force

Kesalahan dependensi

Jika Anda mengalami kesalahan terkait dependensi yang tidak ada:

# From Workload folder
cd Workload
npm install

Masalah autentikasi DevGateway

Jika autentikasi gagal saat memulai DevGateway:

  1. Memverifikasi URI pengalihan pendaftaran aplikasi di Microsoft Entra
  2. Periksa apakah pengaturan penyewa mengizinkan fitur pengembang yang diperlukan
  3. Pastikan Anda masuk ke penyewa yang benar di DevGateway

Untuk informasi pemecahan masalah yang komprehensif, lihat Starter-Kit Repositori README.

Catatan Penting

Pembatasan Akses Jaringan Lokal Chrome Baru

Google telah memperkenalkan pembatasan Akses Jaringan Lokal (LNA) baru di Chrome yang akan memutus pengembangan lokal dengan DevServer. Pembatasan ini mencegah situs web mengakses sumber daya jaringan lokal tanpa izin pengguna eksplisit.

Tindakan yang Diperlukan untuk Pengembangan Lokal: Anda harus mengubah konfigurasi Chrome untuk terus mengembangkan beban kerja secara lokal:

  1. Menavigasi ke chrome://flags/#local-network-access-check di Chrome
  2. Atur bendera ke "Dinonaktifkan"
  3. Mulai ulang Chrome

Mengapa ini diperlukan: Pembatasan baru memblokir komunikasi antara beban kerja Anda yang berjalan di Fabric dan server DevGateway lokal, yang penting untuk alur kerja pengembangan.

Sumber Daya Tambahan:

Penting

Tanpa menonaktifkan bendera ini, pengembangan lokal dengan DevGateway tidak akan berfungsi di Chrome. Perubahan konfigurasi ini hanya diperlukan untuk lingkungan pengembangan.

Langkah selanjutnya

  • Last updated on