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

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

สามส่วนที่ทำงานร่วมกัน

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

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

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

คุณไม่ต้องสร้างมันอีกต่อไป. AddDoconut() ลงทะเบียนเป็นบริการแบบชั่วคราว; ฉีดเข้าไปที่ไหนก็ได้ที่คุณต้องการ:

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

ในแอปพลิเคชัน MVC, รับเป็นพารามิเตอร์ของคอนสตรัคเตอร์; ใน Razor view, ใช้ @inject Doconut.Viewer Viewer. แคชที่เป็นของแอปพลิเคชันสำหรับอินสแตนซ์ Viewer ไม่จำเป็นอีกต่อไป — และไม่ถูกต้องอีกต่อไป, เนื่องจากมันไม่ได้เก็บอะไรที่ควรแคช.

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

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

ไม่มีขั้นตอนอุ่นเครื่องแยกออก. ไลบรารีก่อนหน้ามี InitCache() เพื่อจุดประสงค์นั้น; ตอนนี้ไม่มีแล้ว, และไม่มีอะไรมาแทนที่มัน.

การโอเวอร์โหลดสามแบบแตกต่างกันเพียงในอินพุต: เส้นทางไฟล์, เส้นทางไฟล์พร้อมการกำหนดค่าตามรูปแบบ (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.

ที่ที่มิดเดิลแวร์ถูกเมานท์

UseDoconut() ตอบสนองต่อคำขอที่มีโทเค็น, ไม่ว่าคุณจะเมานท์มันที่ไหน. แอปอ้างอิงเก็บรูปแบบคำขอ DocImage.axd แบบเก่าไว้บนสาขา MapWhen, ดังนั้นไคลเอนต์ที่มีอยู่จะยังคงเรียก URL เดิม. ไม่ว่าคุณจะเลือกอย่างไร, BasePath ของไคลเอนต์ต้องสอดคล้องกับมัน — ดูที่ การกำหนดค่า Viewer.

การให้บริการหน้าจากที่เก็บข้อมูลร่วมแทนโหนดที่เปิดเป็นการจัดการที่แตกต่างอย่างสิ้นเชิง; ดูที่ การปรับใช้แบบกระจาย.

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

viewer.CloseDocument(token);

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

มันถูกเรียกบน Viewer ที่ฉีดเข้าไป. รูปแบบก่อนหน้า — การสร้าง Viewer ชั่วคราวในบล็อก using เพียงเพื่อปิดโทเค็น — ไม่มีเทียบเท่าและไม่จำเป็น.

สิ่งที่ควรจำ

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