สร้างไอเท็ม Fabric ใหม่

คู่มือที่ครอบคลุมนี้แสดงวิธีสร้างรายการแบบกําหนดเองใน Microsoft Fabric โดยใช้ Extensibility Toolkit คุณสามารถเลือกระหว่างสองวิธีตามความชอบและระดับประสบการณ์ของคุณ

ข้อกําหนดเบื้องต้น

ก่อนสร้างรายการแบบกําหนดเอง โปรดตรวจสอบให้แน่ใจว่าคุณมีสิ่งต่อไปนี้

• ✅ ทําคู่มือ การตั้งค่า และมีสภาพแวดล้อมการพัฒนาการทํางาน
• ✅ ปริมาณงานของคุณทํางานในเครื่องและเข้าถึงได้ใน Fabric
• ✅ ความคุ้นเคยกับ TypeScript และ React (สําหรับการปรับแต่ง)

เลือกแนวทางของคุณ

🤖 แนวทาง AI-Assisted (แนะนําสําหรับนักพัฒนารายใหม่)

ใช้ GitHub Copilot เพื่อแนะนําคุณตลอดกระบวนการทั้งหมดแบบโต้ตอบ เหมาะสําหรับ:

• นักพัฒนาที่เพิ่งเริ่มใช้ Fabric Extensibility Toolkit
• เรียนรู้รูปแบบแพลตฟอร์มและแนวทางปฏิบัติที่ดีที่สุด
• รับคําอธิบายและคําแนะนําขณะทํางาน

🛠️ แนวทางสคริปต์ด้วยตนเอง (แนะนําสําหรับนักพัฒนาที่มีประสบการณ์)

ใช้สคริปต์ PowerShell อัตโนมัติสําหรับการตั้งค่าอย่างรวดเร็ว เหมาะสําหรับ:

• นักพัฒนาที่คุ้นเคยกับโครงสร้างชุดเครื่องมือ
• สร้างหลายรายการอย่างมีประสิทธิภาพ
• เวิร์กโฟลว์การผลิตและระบบอัตโนมัติ

🤖 AI-Assisted การสร้างรายการ

เริ่มต้นใช้งาน GitHub Copilot

GitHub Copilot สามารถแนะนําคุณตลอดการสร้างรายการ Fabric แบบกําหนดเองที่สมบูรณ์โดยปฏิบัติตามแนวทางปฏิบัติที่ดีที่สุดทั้งหมด AI เข้าใจรูปแบบ Extensibility Toolkit และจะช่วยให้คุณนําไปใช้ได้อย่างถูกต้อง

ตัวอย่างข้อความแจ้งที่ได้ผล

นี่คือข้อความแจ้งที่ได้รับการพิสูจน์แล้วซึ่งจะช่วยให้คุณเริ่มต้นสร้างรายการได้:

การสร้างไอเท็มพื้นฐาน:

@fabric create a new item called MyDataReport that shows data analysis reports

ข้อกําหนดเฉพาะ:

@fabric create a custom item for managing data pipelines with these features:
- Pipeline configuration interface
- Status monitoring dashboard  
- Error handling and retry logic

รายการที่ซับซ้อนพร้อมการรวม OneLake:

@fabric create an item called DataExplorer that:
- Browses OneLake files in the left panel
- Shows file preview in the center
- Saves user preferences and settings

กระบวนการ AI-Assisted ทั่วไป

แนวทางที่ใช้ AI ช่วยทําตามรูปแบบการทําซ้ํานี้:

1. ขั้นตอนการวางแผนเบื้องต้น

• AI วิเคราะห์ความต้องการของคุณ
• แนะนําโครงสร้างและส่วนประกอบของรายการ
• สร้างแผนการพัฒนาด้วยสิ่งที่ต้องทํา

2. การสร้างส่วนประกอบ

• สร้างรูปแบบ 4 ไฟล์ (คําจํากัดความ, ตัวแก้ไข, ว่างเปล่า, ริบบิ้น)
• ใช้อินเทอร์เฟซ TypeScript ที่เหมาะสม
• ตั้งค่าส่วนประกอบ Fluent UI

3. การใช้งานคุณสมบัติ

• เพิ่มฟังก์ชันเฉพาะของคุณ
• ผสานรวมกับ Fabric API
• ใช้การจัดการข้อผิดพลาดที่เหมาะสม

4. การทดสอบและการปรับแต่ง

• ทดสอบรายการในสภาพแวดล้อมการพัฒนาของคุณ
• แก้ไขปัญหาที่พบ
• เพิ่มประสิทธิภาพและประสบการณ์ของผู้ใช้

การทํางานกับ AI Assistant

เริ่มต้นด้วยข้อกําหนดที่ชัดเจน:

I want to create a [ItemType] item that [primary purpose]. 
The item should have [list key features].
Users should be able to [list main actions].

ทําซ้ําและปรับแต่ง:

The item looks good, but I need to add [specific feature]

How can I integrate this with OneLake storage?

Can you add error handling for when the API is unavailable?

ขอคําอธิบาย:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

แนวทางปฏิบัติที่ดีที่สุดสําหรับการทํางานร่วมกันด้วย AI

• มีความเฉพาะเจาะจง: ระบุข้อกําหนดและบริบทที่ชัดเจน
• ตรวจสอบแต่ละขั้นตอน: ทําความเข้าใจโค้ดที่สร้างขึ้นก่อนดําเนินการต่อ
• ถามคําถาม: ขอคําอธิบายสําหรับรูปแบบที่คุณไม่เข้าใจ
• ทดสอบบ่อยๆ: เรียกใช้และทดสอบรายการหลังจากการเปลี่ยนแปลงที่สําคัญแต่ละครั้ง
• ติดตามผล: ขอการปรับแต่งและการปรับปรุง

เครื่องมือพัฒนา AI และสิ่งแวดล้อม

ที่เก็บนี้ทํางานได้ดีเป็นพิเศษกับเครื่องมือการเขียนโปรแกรมคู่ AI ไม่ว่าคุณจะพัฒนาในเครื่องหรือใน GitHub Codespaces คุณสามารถใช้ GitHub Copilot หรือผู้ช่วย AI อื่นๆ เพื่อเร่งงานต่างๆ เช่น การแก้ไขส่วนประกอบ React การอัปเดตเส้นทาง หรือการสร้างนั่งร้านทดสอบ

พื้นที่ช่วยเหลือ AI เฉพาะ:

• ใช้ AI เพื่อร่างส่วนประกอบตัวแก้ไขรายการ/ดู แล้วปรับให้เข้ากับรูปแบบ API โฮสต์ที่ใช้ใน Starter-Kit
• ขอให้ AI สรุปรายการปริมาณงานและเสนอชุดสิทธิ์ขั้นต่ํา
• ใน Codespaces Copilot พร้อมใช้งานในเบราว์เซอร์หรือเดสก์ท็อป VS Code ให้เซิร์ฟเวอร์ Dev ทํางานเพื่อดูการเปลี่ยนแปลงทันที

การทําซ้ําและการดีบักอย่างรวดเร็ว

เฟรมเวิร์กความสามารถในการขยายได้รับการออกแบบมาสําหรับการพัฒนาอย่างรวดเร็วเมื่อใช้ความช่วยเหลือของ AI:

• เมื่อเซิร์ฟเวอร์ dev และ DevGateway ทํางานอยู่ การเปลี่ยนแปลงโค้ดในแอปของคุณจะสะท้อนให้เห็นทันทีเมื่อคุณเปิดรายการภายใน Fabric
• คุณสามารถแก้ไขข้อบกพร่องได้โดยใช้เครื่องมือสําหรับนักพัฒนาของเบราว์เซอร์ในขณะที่ปริมาณงานโฮสต์อยู่ใน Fabric iFrame
• ทําซ้ํา UI เส้นทาง และการกําหนดค่ารายการได้อย่างรวดเร็ว และตรวจสอบพฤติกรรมแบบ end-to-end ในพื้นที่ทํางาน Fabric ของคุณ
• เครื่องมือ AI สามารถช่วยระบุและแก้ไขปัญหาแบบเรียลไทม์ในขณะที่คุณพัฒนา

ไทม์ไลน์ที่คาดไว้

• รายการง่ายๆ: 30-60 นาทีพร้อมคําแนะนํา AI
• รายการที่ซับซ้อน: 1-3 ชั่วโมงพร้อมการทําซ้ําหลายครั้ง
• รายการขั้นสูง: ครึ่งวันพร้อมการปรับแต่งที่กว้างขวาง

🛠️ แนวทางสคริปต์ด้วยตนเอง

การใช้สคริปต์ CreateNewItem.ps1

วิธีการด้วยตนเองใช้สคริปต์ PowerShell อัตโนมัติที่คัดลอกเทมเพลตรายการ HelloWorld และกําหนดค่าสําหรับรายการใหม่ของคุณ

เริ่มต้นใช้งานด่วน

1. ไปที่ไดเรกทอรีสคริปต์:

   cd scripts\Setup
   

2. เรียกใช้สคริปต์การสร้าง:

   .\CreateNewItem.ps1 -ItemName "MyCustomItem"
   

สคริปต์ทําอะไร

การสร้างไฟล์อัตโนมัติ:

• ✅ คัดลอกไฟล์ส่วนประกอบหลักทั้ง 4 ไฟล์จากเทมเพลต HelloWorld
• ✅ เปลี่ยนชื่อไฟล์ให้ตรงกับชื่อรายการของคุณ
• ✅ อัปเดตการอ้างอิงภายในและการนําเข้าทั้งหมด
• ✅ สร้างไฟล์ Manifest (การกําหนดค่า XML และ JSON)
• ✅ คัดลอกและเปลี่ยนชื่อเนื้อหาไอคอน

โครงสร้างไฟล์ที่สร้างขึ้น:

Workload/app/items/MyCustomItemItem/
├── MyCustomItemDefinition.ts         # Data model and interfaces
├── MyCustomItemEditor.tsx            # Main editor component
├── MyCustomItemEditorEmpty.tsx       # First-time user experience
├── MyCustomItemEditorRibbon.tsx      # Action buttons and toolbar
└── MyCustomItem.scss                 # Styling

Workload/Manifest/items/MyCustomItem/
├── MyCustomItemItem.xml              # Item type definition
└── MyCustomItemItem.json             # Item configuration

Workload/Manifest/assets/images/
└── MyCustomItemItem-icon.png         # Item icon

ขั้นตอนด้วยตนเองที่จําเป็น

หลังจากเรียกใช้สคริปต์ คุณต้อง ทําตามขั้นตอนการกําหนดค่าด้วยตนเองเหล่านี้:

1. อัปเดตไฟล์สภาพแวดล้อมที่สําคัญ🚨

เพิ่มรายการใหม่ของคุณลงใน ITEM_NAMES ตัวแปรในไฟล์สภาพแวดล้อมทั้งหมด:

ไฟล์ที่จะอัปเดต:

• Workload\.env.dev
• Workload\.env.test
• Workload\.env.prod

เปลี่ยนจาก:

ITEM_NAMES=HelloWorld

เปลี่ยนเป็น:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ หากไม่มีขั้นตอนนี้ รายการของคุณจะไม่ปรากฏในปริมาณงาน!

2. อัปเดตการกําหนดค่า Product.json

เพิ่มการกําหนดค่ารายการของคุณไปที่ Workload\Manifest\Product.json:

{
  "items": [
    {
      "name": "HelloWorldItem",
      // ... existing config
    },
    {
      "name": "MyCustomItemItem",
      "displayName": "My Custom Item",
      "description": "Description of what your item does",
      "contentType": "MyCustomItem",
      "configurationSections": []
    }
  ]
}

3. เพิ่มสตริงการแปลเป็นภาษาท้องถิ่น

อัปเดตไฟล์แปลใน Workload\Manifest\assets\locales\:

ใน en-US.json (และไฟล์ตําแหน่งที่ตั้งอื่นๆ):

{
  "MyCustomItemItem": {
    "displayName": "My Custom Item",
    "description": "Description of your custom item"
  }
}

4. เพิ่มการกําหนดค่าการกําหนดเส้นทาง

อัปเดต Workload\app\App.tsx เพื่อรวมการกําหนดเส้นทางสําหรับสินค้าใหม่ของคุณ:

// Add import
import { MyCustomItemEditor } from "./items/MyCustomItemItem/MyCustomItemEditor";

// Add route in the Routes section
<Route path="/MyCustomItemItem-editor" element={<MyCustomItemEditor {...props} />} />

ขั้นตอนการยืนยัน

หลังจากทําตามขั้นตอนด้วยตนเองทั้งหมดแล้ว:

1. สร้างโครงการ:

   npm run build
   

2. รีสตาร์ทเซิร์ฟเวอร์การพัฒนา:

   .\scripts\Run\StartDevServer.ps1
   

3. ทดสอบในผ้า:

   • นําทางไปยังปริมาณงานของคุณใน Fabric
   • ยืนยันว่าประเภทรายการใหม่ของคุณปรากฏในกล่องโต้ตอบการสร้าง
   • สร้างอินสแตนซ์และตรวจสอบว่าโหลดอย่างถูกต้อง

แนวทางปฏิบัติและแนวทางปฏิบัติที่ดีที่สุด

ทําไมไม่เปลี่ยนชื่อ HelloWorld?

รายการ HelloWorld ทําหน้าที่เป็น เทมเพลตอ้างอิง ที่ได้รับการอัปเดตเป็นประจําจาก Microsoft เหตุผลสําคัญที่ควรไม่เปลี่ยนแปลง:

• การอัปเดตและการปรับปรุง: Microsoft อัปเดต HelloWorld เป็นประจําด้วยฟีเจอร์ใหม่ การแก้ไขข้อบกพร่อง และแนวทางปฏิบัติที่ดีที่สุด
• การทดสอบการบูรณาการ: HelloWorld ช่วยให้มั่นใจได้ว่าสภาพแวดล้อมของคุณทํางานได้อย่างถูกต้อง
• เอกสารอ้างอิง: ทําหน้าที่เป็นเอกสารสดสําหรับรูปแบบการใช้งาน
• ความเข้ากันได้แบบย้อนหลัง: การอัปเดตจะรักษาความเข้ากันได้กับการปรับแต่งที่มีอยู่

เวิร์กโฟลว์ที่แนะนำ

1. ไม่แตะต้อง HelloWorld: ใช้เป็นข้อมูลอ้างอิงและรายการทดสอบของคุณ
2. สร้างรายการใหม่: ใช้สคริปต์หรือความช่วยเหลือ AI เพื่อสร้างรายการแยกต่างหาก
3. การอัปเดตปกติ: ดึงการอัปเดตเป็นระยะจากที่เก็บพื้นฐาน
4. ผสานรูปแบบ: ใช้รูปแบบใหม่จาก HelloWorld ที่อัปเดตกับรายการที่กําหนดเองของคุณ

แนวทางปฏิบัติที่ดีที่สุดสําหรับการพัฒนาไอเท็ม

สถาปัตยกรรมส่วนประกอบ:

• ✅ ทําตามรูปแบบ 4 องค์ประกอบ (คําจํากัดความ, ตัวแก้ไข, ว่างเปล่า, ริบบิ้น)
• ✅ ใช้คอนเทนเนอร์ ItemEditor สําหรับเลย์เอาต์และลักษณะการทํางานที่สอดคล้องกัน
• ✅ ใช้สถานะการโหลดที่เหมาะสมและการจัดการข้อผิดพลาด
• ✅ ทําตามรูปแบบการออกแบบ UI ที่คล่องแคล่ว

การจัดการข้อมูล:

• ✅ ใช้สําหรับ saveWorkloadItem() รายการที่มีข้อมูลที่ซับซ้อน
• ✅ ใช้ getWorkloadItem() สําหรับการโหลดด้วยค่าเริ่มต้นสํารอง
• ✅ ใช้อินเทอร์เฟซ TypeScript ที่เหมาะสมในไฟล์คําจํากัดความ
• ✅ จัดการสถานะที่ไม่ได้กําหนด/ว่างเปล่าอย่างสง่างาม

ประสบการณ์ของผู้ใช้:

• ✅ ระบุสถานะว่างที่ชัดเจนสําหรับผู้ใช้ครั้งแรก
• ✅ ใช้ตัวบ่งชี้การโหลดที่เหมาะสม
• ✅ ใช้ข้อความแสดงข้อผิดพลาดที่เป็นประโยชน์
• ✅ ปฏิบัติตามรูปแบบการออกแบบผ้าและแนวทางการช่วยสําหรับการเข้าถึง

ข้อควรพิจารณาด้านประสิทธิภาพ

• Lazy Loading: โหลดข้อมูลเมื่อจําเป็นเท่านั้น
• การอัปเดตที่มีประสิทธิภาพ: ใช้รูปแบบ React เพื่อลดการแสดงผลซ้ํา
• การรวม OneLake: ใช้สําหรับ createItemWrapper() การกําหนดขอบเขตที่เหมาะสม
• ขอบเขตข้อผิดพลาด: ใช้การจัดการข้อผิดพลาดที่เหมาะสมตลอด

ขั้นตอนถัดไป

เมื่อสร้างรายการของคุณแล้ว:

1. ปรับแต่งโมเดลข้อมูล: อัปเดตไฟล์คําจํากัดความด้วยอินเทอร์เฟซเฉพาะของคุณ
2. ใช้คุณสมบัติหลัก: สร้างฟังก์ชันหลักในส่วนประกอบตัวแก้ไข
3. ออกแบบสถานะว่างเปล่า: สร้างประสบการณ์ผู้ใช้ครั้งแรกที่น่าสนใจ
4. กําหนดค่าการดําเนินการ: ตั้งค่าการดําเนินการ Ribbon ที่เหมาะสมสําหรับเวิร์กโฟลว์ของคุณ
5. ทดสอบอย่างละเอียด: ตรวจสอบฟังก์ชันการทํางานทั้งหมดในสภาพแวดล้อมการพัฒนาของคุณ
6. เตรียมพร้อมสําหรับการผลิต: ทําตาม คู่มือการเผยแพร่ เมื่อพร้อม

การแก้ไขปัญหา

รายการไม่ปรากฏในปริมาณงาน:

• ✅ ตรวจสอบ ITEM_NAMES ในไฟล์ .env ทั้งหมด
• ✅ ตรวจสอบการกําหนดค่า Product.json
• ✅ รีสตาร์ทเซิร์ฟเวอร์การพัฒนา

สร้างข้อผิดพลาด:

• ✅ ตรวจสอบอินเทอร์เฟซ TypeScript ในไฟล์คําจํากัดความ
• ✅ ยืนยันว่าการนําเข้าทั้งหมดถูกต้อง
• ✅ ตรวจสอบให้แน่ใจว่าได้กําหนดค่าการกําหนดเส้นทางอย่างถูกต้อง

ข้อผิดพลาดรันไทม์:

• ✅ ตรวจสอบคอนโซลเบราว์เซอร์เพื่อดูข้อความแสดงข้อผิดพลาดโดยละเอียด
• ✅ ตรวจสอบการผสานรวม API และการรับรองความถูกต้อง
• ✅ ทดสอบด้วยข้อมูลแบบง่ายก่อน

ทรัพยากรเพิ่มเติม

• เอกสารควบคุม ItemEditor
• คู่มือการรวม OneLake
• การใช้งาน Fabric API
• ข้อกําหนดในการเผยแพร่

มีความสุขในการเขียนโค้ด! 🚀