วิธีการทำงานของ Viewer

Doconut แสดงเอกสารเป็นภาพที่แบ่งหน้าโดยให้บริการผ่าน middleware ของ ASP.NET Core การเข้าใจวงจรชีวิต — เปิด, โทเคน, คำขอหน้า, ปิด — จะอธิบายพฤติกรรมเกือบทั้งหมดที่คุณจะสังเกตเห็น รวมถึงข้อความแสดงข้อผิดพลาดด้วย

ส่วนประกอบหลักสามส่วน

• Viewer — บริการสาธารณะที่คุณฉีดเข้าไป มันเปิดเอกสารและส่งคืนโทเคนเซสชัน
• เซสชันเอกสาร — วัตถุฝั่งเซิร์ฟเวอร์ที่เก็บเอกสารที่โหลดแล้ว โดยใช้โทเคนเป็นคีย์ใน IMemoryCache
• มิดเดิลแวร์ Doconut — ถูกเพิ่มโดย UseDoconut(); ตอบสนองต่อทุกคำขอที่วิดเจ็ตของเบราว์เซอร์ทำ (pages, thumbnails, search, annotations, …) โดยยืนยันตัวตนด้วยโทเคนเสมอ

Viewer ไม่มีสถานะ — ตามการออกแบบ

Viewer ถูกปิดกั้น, ไม่เก็บสถานะเอกสารต่อคำขอ, และโดยเจตนา ไม่ implement IDisposable. เซสชันดำรงอยู่แยกจากกันในตัวจัดการเซสชันและจะถูกทำความสะอาดโดยการหมดอายุของแคชหรือโดยการเรียก CloseDocument(token) อย่างชัดเจน

ฉีดเข้าไปที่ใดก็ได้ที่คุณต้องการ:

app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

สิ่งที่เกิดขึ้นภายใน OpenDocumentAsync

1. ขั้นตอนตรวจสอบใบอนุญาต – ใบอนุญาตที่ถูกปฏิเสธหรือหมดอายุเวอร์ชัน (ถูกบล็อก, ถูกดัดแปลง, หรือเป็นบิลด์ที่อยู่นอกช่วงอัปเดตของใบอนุญาต) จะโยน LicenseException ทันที พร้อมข้อความเหตุผลการปฏิเสธ — การเปิดจะไม่ลดคุณภาพโดยเงียบสำหรับใบอนุญาตที่ไม่ถูกต้อง (ต่างจากไม่มีใบอนุญาต). ใบอนุญาต Temporary หรือแบบสมัครสมาชิกที่หมดอายุตามปฏิทินเป็นข้อยกเว้น: จะไม่โยนข้อผิดพลาด — จะลดคุณภาพเป็นลายน้ำ
2. การสร้างเซสชัน – ฟา́กทอรีของ viewer จะเลือก viewer ที่เหมาะกับรูปแบบไฟล์ตามส่วนขยายและโหลดเอกสาร (ดู Rendering Pipeline). เซสชันจะถูกเก็บใน IMemoryCache ภายใต้โทเคน GUID ใหม่พร้อม การหมดอายุแบบเลื่อน — DocOptions.TimeOut นาที, ค่าเริ่มต้น 60. ทุกคำขอหน้า จะรีเซ็ตนาฬิกา
3. การลงทะเบียนความปลอดภัย – เมื่อ UnsafeMode = false (ค่าเริ่มต้น), โทเคนจะผูกกับเซสชัน ASP.NET ของผู้เรียก: จะเขียนเครื่องหมาย secure-{token} ลงในเซสชัน, ดังนั้นเฉพาะเซสชันของเบราว์เซอร์ที่เปิดเอกสารเท่านั้นที่สามารถขอหน้าของมันได้
4. การส่งคืนโทเคน – โทเคนเป็นข้อมูลประจำตัวเดียวสำหรับทุกอย่างที่ตามมา

การ overload สามแบบแตกต่างกันเพียงแค่ข้อมูลเข้า: เส้นทางไฟล์, เส้นทางไฟล์พร้อมการกำหนดค่าตามรูปแบบ (PdfConfig, WordConfig, …), หรือ Stream พร้อม FileInfo ที่ส่วนขยายของไฟล์กำหนดการตรวจจับรูปแบบ

วิธีที่วิดเจ็ตรับหน้า

วิดเจ็ตของไคลเอนต์เรียก Doconut middleware พร้อมโทเคนใน query string. สิ่งที่ middleware ทำขึ้นอยู่กับคำขอ:

แต่ละเส้นทางเหล่านี้จะตรวจสอบก่อน:

• No token → middleware จะคืนค่า 404 (หรือแบนเนอร์เวอร์ชันเมื่อ ShowDoconutInfo = true).
• Unknown or expired token → รูปภาพข้อผิดพลาดที่มีข้อความ Document session not found. Please re-open document.
• Session middleware missing (กับ UnsafeMode = false) → HTTP 500 พร้อมข้อความ Session middleware not configured. Call UseSession() before UseDoconut().
• Token opened by a different browser session → รูปภาพข้อผิดพลาดที่มีข้อความ You Are Not Authorized To View This Page.

การปิดเอกสาร

viewer.CloseDocument(token);

CloseDocument จะลบเซสชันออกจากแคช (ซึ่งทำลายเอนจินเอกสารพื้นฐานและปล่อยหน่วยความจำทันที), ลบเครื่องหมาย secure-{token}, และเพิกถอนการให้สิทธิ์การเข้าถึง. การเรียกใช้เป็นทางเลือก — การหมดอายุแบบเลื่อนจะทำความสะอาดแบบเดียวโดยอัตโนมัติ — แต่สำหรับเอกสารขนาดใหญ่เป็นวิธีที่สุภาพในการปล่อยหน่วยความจำทันทีที่ผู้ใช้เสร็จสิ้น.

สรุป

• เอกสารที่เปิดหนึ่งไฟล์ = เซสชันหนึ่ง = โทเคนหนึ่ง. โทเคนเป็นต่อเซสชันของเบราว์เซอร์, ไม่ใช่ URL ทั่วโลก.
• โทเคนจะหมดอายุตามหน้าต่างเลื่อน; หาก viewer อยู่นิ่งเกิน DocOptions.TimeOut จำเป็นต้องเปิดใหม่.
• Viewer สามารถฉีดและแชร์ได้อย่างอิสระ; เซสชันบรรจุสถานะทั้งหมด.