ลงทะเบียนและเปิดใช้งานวิดเจ็ตแปลงไฟล์แบบ Drop‑in ของ Doconut ใน .NET 8

วิดเจ็ตแบบ Drop‑in คือ UI สำเร็จรูปของ Doconut สำหรับอัปโหลดไฟล์, เรียกการแปลง, และดาวน์โหลดผลลัพธ์.
โดยค่าเริ่มต้น จุดเชื่อมต่อสาม ?convert= ของวิดเจ็ตจะคืนค่า 404; จุดเชื่อมต่อเหล่านี้จะทำงานเมื่อคุณลงทะเบียนปลั๊กอิน Converter และ เรียก AddConverterWidget() บน DoconutOptions.

ด้านล่างเป็นการกำหนดค่าเริ่มต้นที่สมบูรณ์พร้อมคัดลอก‑วาง ที่ตอบสนองความต้องการทั้งสอง.

---

1. ข้อกำหนดเบื้องต้น – ใบอนุญาตและการสนับสนุนเซสชัน

• License – ปลั๊กอิน Converter ต้องการใบอนุญาตที่ให้ความสามารถ Converter. วางไฟล์ (เช่น Doconut.Viewer.lic) ไว้ในตำแหน่งที่แอปสามารถเข้าถึงได้และชี้ DoconutOptions.LicensePath ไปที่ไฟล์นั้น.
• Session state – โมเดลความปลอดภัยของ Doconut เก็บโทเค็นเอกสาร‑เซสชันในเซสชันของ ASP.NET Core. เพิ่มแคชแบบกระจายและ AddSession() ก่อนที่มิดเดิลแวร์จะถูกเชื่อมต่อ.

builder.Services.AddDistributedMemoryCache();   // จำเป็นสำหรับเซสชัน
builder.Services.AddSession();                  // เปิดใช้งานเซสชันที่สนับสนุนโดย IDistributedCache‑backed session

---

2. ลงทะเบียนบริการหลักของ Doconut

AddDoconut() คือจุดเข้าถึงเดียวที่ฉีด viewer, บริการใบอนุญาต, และรีจิสทรีของปลั๊กอิน.

builder.Services.AddDoconut(options =>
{
    // บอก Doconut ว่าไฟล์ใบอนุญาตอยู่ที่ไหน
    options.LicensePath = "Doconut.Viewer.lic";

    // ลงทะเบียนปลั๊กอิน Converter – สิ่งนี้ยังตรวจสอบความสามารถของใบอนุญาตด้วย
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

หากใบอนุญาต ไม่ มีความสามารถ Converter, การเรียกด้านบนจะโยนข้อผิดพลาด InvalidOperationException และแอปพลิเคชันจะไม่เริ่มทำงาน. พฤติกรรม fail‑fast นี้ป้องกันไม่ให้คุณปรับใช้บิลด์ที่ไม่มีใบอนุญาตที่ถูกต้อง.

---

3. เปิดใช้งานวิดเจ็ตด้วย AddConverterWidget

วิดเจ็ตต้องเปิดใช้งานโดยเลือก. การเรียก AddConverterWidget() จะลงทะเบียนจุดเชื่อมต่อการแปลงสามรายการ (?convert=open, ?convert=run, ?convert=download) และเชื่อมต่อการกำหนดค่าข้างไคลเอนต์เล็กน้อย (ขนาดอัปโหลดสูงสุด, เส้นทางฐาน, ฯลฯ).

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // เปิดใช้งาน UI แบบ drop‑in และตั้งค่าขีดจำกัดการอัปโหลดฝั่งไคลเอนต์
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // การตรวจสอบล่วงหน้าฝั่งไคลเอนต์; เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเอง
    });
});

มีเพียงการเรียก AddConverterWidget เท่านั้นที่สร้างจุดเชื่อมต่อ; ไฟล์ JavaScript สถิต (doconutConverter.js) จะเสมอให้บริการเป็นทรัพยากรฝังตัว, แต่จะล้มเหลวในการติดต่อเซิร์ฟเวอร์หากจุดเชื่อมต่อหายไป.

---

4. เชื่อมต่อมิดเดิลแวร์ในลำดับที่ถูกต้อง

มิดเดิลแวร์ที่ให้บริการทรัพยากรสถิต (UseDoconutResources) ต้องทำงาน ก่อน มิดเดิลแวร์ viewer สุดท้าย (UseDoconut). มิดเดิลแวร์เซสชันต้องวางไว้ก่อนเช่นกันเนื่องจาก Doconut ตรวจสอบเซสชันในทุกคำขอ.

app.UseSession();           // ต้องมาก่อน UseDoconut()
app.UseDoconutResources();  // ให้บริการไฟล์ JS, CSS, รูปภาพ
app.UseDoconut();           // จัดการคำขอ ?convert= และหน้าของเอกสาร

เมื่อมี pipeline นี้, คำขอไปยัง /doconut-res/doconutConverter.js จะสำเร็จ, และวิดเจ็ตสามารถเรียก /doconut?convert=open, /doconut?convert=run, และ /doconut?convert=download.

---

5. สิ่งที่วิดเจ็ตทำจริง

ขั้นตอน	จุดเชื่อมต่อเซิร์ฟเวอร์	การตอบสนองทั่วไป
เปิด	?convert=open	ส่งคืน payload JSON ที่ประกอบด้วย token, จำนวนหน้า, ส่วนขยายของไฟล์ต้นฉบับ, และรายการของรูปแบบเป้าหมายที่อนุญาต.
ทำงาน	?convert=run	เริ่มการแปลงและส่งคืน downloadToken, จำนวนหน้าผลลัพธ์, ชื่อไฟล์ที่แนะนำ, และแฟล็กที่บ่งชี้ว่าผลลัพธ์มีลายน้ำหรือไม่.
ดาวน์โหลด	?convert=download	สตรีมไฟล์ที่แปลงแล้วเมื่อไคลเอนต์ตาม URL ดาวน์โหลดที่ให้ไว้.

ด้านไคลเอนต์, วิดเจ็ตทำการตรวจสอบขนาดไฟล์ก่อนอัปโหลดเทียบกับ widget.MaxUploadMb. หากไฟล์เกินขีดจำกัด, วิดเจ็ตจะยกเลิกการอัปโหลดและเรียก callback onError พร้อมกับ phase = "open" และข้อความที่เป็นมิตร. เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเองและจะตอบ 413 Payload Too Large หากคำขอผ่านการตรวจสอบของไคลเอนต์.

---

6. การเชื่อมต่อกับเหตุการณ์ของวิดเจ็ต (ไม่จำเป็นต้องเขียน C#)

Callback ทั้งหมด (onReady, onSourceLoaded, onConverted, onError, เป็นต้น) เป็นฟังก์ชัน JavaScript ที่หน้าที่โฮสต์วิดเจ็ตจัดเตรียมให้. เนื่องจากคำถามเน้นที่ด้าน registration, คุณไม่จำเป็นต้องเขียนโค้ด C# เพิ่มเติมเพื่อจัดการ callback เหล่านั้น – วิดเจ็ตจะเรียกใช้โดยอัตโนมัติเมื่อจุดเชื่อมต่อพร้อมใช้งาน.

---

7. ข้อผิดพลาดทั่วไปและวิธีหลีกเลี่ยง

อาการ	สาเหตุที่เป็นไปได้	วิธีแก้
404 on /doconut?convert=open	AddConverterWidget() ถูกละเว้น.	เพิ่มการเรียกตามที่แสดงในส่วน 3.
แอปพลิเคชันไม่สามารถเริ่มทำงานได้ด้วย InvalidOperationException เกี่ยวกับความสามารถที่หายไป	ไฟล์ใบอนุญาตไม่ได้ให้สิทธิ์ Converter.	รับใบอนุญาตที่รวมความสามารถ Converter.
ข้อผิดพลาด 500 ที่เกี่ยวกับเซสชัน	UseSession() ถูกวางหลัง UseDoconut() หรือไม่มีการลงทะเบียนแคช.	ตรวจสอบให้ app.UseSession() ทำงานก่อน app.UseDoconut() และมีการลงทะเบียนบริการแคช.

---

8. รันแอปและดูวิดเจ็ตทำงาน

1. สร้างและรันโปรเจกต์ ASP.NET Core.
2. เปิดหน้าที่มีองค์ประกอบ <div id="doconut-convert"></div> และรวมสคริปต์แปลงของ Doconut (สคริปต์นี้ให้บริการโดยอัตโนมัติจาก /doconut-res/doconutConverter.js).
3. ลากไฟล์ที่รองรับ (PDF, DOCX, DWG, ฯลฯ) ไปยังพื้นที่วาง.
4. วิดเจ็ตจะเรียก ?convert=open, จากนั้น ?convert=run, และสุดท้ายแสดงลิงก์ Download ที่ชี้ไปยัง ?convert=download.

หากจุดเชื่อมต่อทั้งสามตอบกลับด้วย JSON แทน 404, วิดเจ็ตได้ลงทะเบียนอย่างถูกต้องและพร้อมใช้งานในสภาพแวดล้อมการผลิต.

---

ขั้นตอนต่อไป: เพิ่มโค้ดสแนปช็อตด้านบนลงใน Program.cs (หรือ Startup.cs), ตรวจสอบว่าไฟล์ใบอนุญาตมีอยู่, แล้วเปิดแอป. วิดเจ็ตแปลงแบบ Drop‑in จะพร้อมใช้งานโดยไม่ต้องเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์เพิ่มเติม.