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

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

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

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

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

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

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

วิดเจ็ตรับหน้าต่างอย่างไร

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

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

• ไม่มีโทเค็น → มิดเดิลแวร์จะคืนค่า 404 (หรือแบนเนอร์เวอร์ชันเมื่อ ShowDoconutInfo = true).
• โทเค็นไม่รู้จักหรือหมดอายุ → ภาพข้อผิดพลาดพร้อมข้อความ Document session not found. Please re-open document.
• มิดเดิลแวร์เซสชันหายไป (เมื่อ UnsafeMode = false) → HTTP 500 พร้อมข้อความ Session middleware not configured. Call UseSession() before UseDoconut().
• โทเค็นเปิดโดยเซสชันเบราว์เซอร์อื่น → ภาพข้อผิดพลาดพร้อมข้อความ You Are Not Authorized To View This Page.

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

viewer.CloseDocument(token);

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

สรุปประเด็นสำคัญ

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