การแก้ปัญหา

ข้อความทั้งหมดด้านล่างเป็นข้อความดิบที่ Doconut สร้างขึ้น จัดเรียงตามอาการ หากพบข้อผิดพลาดของคุณ ให้ใช้วิธีแก้ที่ระบุ

ตัวดูไม่แสดงอะไรเลย

พื้นที่ตัวดูว่างเปล่า คอนโซลของเบราว์เซอร์เต็มไปด้วย 404 สำหรับ /doconut-res/...
UseDoconutResources() หายไป หรือวางไว้หลัง UseDoconut() ควรวางเป็นอันดับแรกใน pipeline

HTTP 500 พร้อมข้อความ:

Session middleware not configured. Call UseSession() before UseDoconut().

ความปลอดภัยโทเคนของ Doconut (เปิดโดยค่าเริ่มต้น) ต้องการสถานะเซสชันของ ASP.NET เพิ่ม builder.Services.AddSession() และ app.UseSession() ก่อน สาขา middleware ของ Doconut สถานะเซสชันต้องการแคชด้วย: ในแอป minimal‑API ให้เพิ่ม builder.Services.AddDistributedMemoryCache() มิฉะนั้นแอปจะหยุดทำงานที่การเริ่มต้นด้วยข้อความ Unable to resolve service for type 'IDistributedCache' (แอป MVC และ Razor Pages จะลงทะเบียนให้แล้ว)

รูปภาพข้อผิดพลาดในพื้นที่หน้าแสดงข้อความ:

You Are Not Authorized To View This Page.

โทเคนถูกเปิดโดยเซสชันเบราว์เซอร์อื่น สาเหตุทั่วไป: คุกกี้เซสชันไม่ถึงคำขอหน้า (การตั้งค่า cross‑origin, นโยบาย SameSite, ไคลเอนต์ API ที่ไม่มีคุกกี้), หรือแอปรีสตาร์ท (คีย์เซสชันใหม่) นี่คือชั้นความปลอดภัยทำงานตามที่ออกแบบ — ดู Core Concepts → Sessions & Security

รูปภาพข้อผิดพลาดแสดงข้อความ:

Document session not found. Please re-open document.

โทเคนหมดอายุ (หน้าต่างเลื่อน, ค่าเริ่มต้น 60 นาที — DocOptions.TimeOut) หรือเซสชันถูกปิด เปิดเอกสารใหม่เพื่อรับโทเคนใหม่

เซิร์ฟเวอร์ทำงานปกติแต่หน้าเว็บทำงานผิดปกติ — ไม่มีข้อผิดพลาดใด ๆ

นี่คือโหมดการล้มเหลวที่ควรสงสัยเป็นอันดับแรกหลังจากย้ายแอปพลิเคชันไปยังสภาพแวดล้อมใหม่ ทั้งสามกรณีทำให้เซิร์ฟเวอร์ทำงานสมบูรณ์ แสดงเอกสารได้ถูกต้อง และไม่มีข้อความใดในคอนโซลของเบราว์เซอร์

สปินเนอร์แสดงการทำงานตลอดเวลา ตัวเรียกกลับของตัวดูถูกประกาศเป็นฟังก์ชันระดับโลกที่มีชื่อเดียวกับ id ของคอนเทนเนอร์ — ctlDoc_OnViewerReady() และอื่น ๆ ตัวดูก่อนหน้านี้ค้นหาชื่อเหล่านี้ได้ แต่ตัวดูนี้ไม่พบ ตัวจัดการที่ควรซ่อนสปินเนอร์จึงไม่ทำงาน ส่งฟังก์ชันเหล่านี้เป็นตัวเลือกแทน:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

เอกสารที่อยู่ด้านหลังสปินเนอร์ไม่มีปัญหา รายการตัวเลือกทั้งหมดอยู่ใน
การกำหนดค่า Viewer

ไอคอนหรือ Chrome ของตัวดูหายไป แต่หน้าอื่น ๆ แสดงถูกต้อง ResPath ว่างเปล่าหรือชี้ไปที่รากของแอปพลิเคชัน — ค่าที่ถูกต้องในไลบรารีก่อนหน้า แต่ไม่ถูกต้องที่นี่ ต้องระบุพรีฟิกซ์ที่ UseDoconutResources() ติดตั้ง:

ResPath: 'doconut-res/images'   // หรือ '<your ResourcesPath>/images'

แผ่นภาพ (tiles) ของหน้าถัดไปเสียหายเมื่อให้บริการจากที่เก็บร่วม หน้าเหล่านั้นยังอยู่ระหว่างการเขียนตอบกลับด้วย 202 Accepted ไคลเอนต์ที่ไม่มี retryOn409: true จะถือว่าเป็นการโหลดภาพล้มเหลว ดู การปรับใช้แบบกระจาย

การเปิดเอกสารล้มเหลว

LicenseException พร้อมข้อความปฏิเสธ — พบไฟล์ใบอนุญาตแต่ถูกปฏิเสธ (ลายเซ็นไม่ถูกต้อง, ถูกดัดแปลง, ถูกบล็อก, หรือรุ่น/อัปเดตของใบอนุญาตไม่ตรง) สถานะนี้บล็อกการเปิด (fail‑fast) แทนการแสดงลายน้ำ; อ่าน License.RejectionMessage เพื่อดูสาเหตุ

LicenseException:

This document type requires the 'Dicom' plugin license.

ส่วนขยายนี้รองรับโดยปลั๊กอินเท่านั้น (ที่นี่: DICOM) และความสามารถนั้นไม่ได้รับการให้สิทธิ์อีกต่อไป ลงทะเบียนปลั๊กอินและตรวจสอบ lic.IsCapabilityGranted(LicenseCapability.Dicom) การขาดหรือสิทธิ์ไม่เพียงพอแบบไม่ชั่วคราวมักจะล้มเหลวก่อนหน้าใน AddDoconut()

FormatNotSupportedException:

Document format '<extension>' is not supported.

ไม่มีตัวดูใด (ในตัว, ปลั๊กอิน, หรือแบบกำหนดเอง) รองรับส่วนขยายนี้ ตรวจสอบรายการรูปแบบที่รองรับ; สำหรับรูปแบบของคุณเอง สามารถเพิ่มด้วย DoconutOptions.RegisterViewer

InvalidDataException — เนื้อหาไฟล์เสียหายหรือไม่ตรงกับส่วนขยาย (เช่น ไฟล์ที่เปลี่ยนชื่อ) ตรวจสอบการอัปโหลดก่อนเปิด

InvalidOperationException:

No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

คุณได้เรียกใช้ DocumentConverter แต่ไม่ได้ลงทะเบียนปลั๊กอิน Converter.

การเริ่มต้นล้มเหลว

InvalidOperationException mentioning a plugin registered via AddPlugin — ใบอนุญาตที่ไม่ใช่แบบชั่วคราวปัจจุบันไม่ได้ให้สิทธิ์การทำงานของปลั๊กอินนั้น ให้ลบการลงทะเบียนหรือทำการติดตั้งใบอนุญาตที่ให้สิทธิ์นั้น การไม่มีใบอนุญาตและไฟล์ TRIAL รุ่นเก่าไม่ได้ให้สิทธิ์ปลั๊กอินใด ๆ

ArgumentException from AddDoconut():

DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

การตรวจสอบตัวเลือกแบบ fail‑fast — แก้ไขเส้นทางที่ทำให้เกิดปัญหา

ข้อผิดพลาดการสร้าง / การพึ่งพา

แพคเกจไม่สามารถติดตั้งได้เลย — Doconut.NETStandard 26.8.0 ตั้งเป้าหมายที่ netstandard2.1 ทำให้ NuGet ปฏิเสธโครงการ .NET Framework นี่ไม่ใช่ข้อผิดพลาดการกู้คืนที่แก้ไขได้: .NET Framework ไม่สามารถใช้ netstandard2.1 ได้ ใช้แพคเกจ Doconut.NETFramework แทน

Compiler error CS1705, or at runtime when opening a document:

Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

โครงการของคุณกำหนดเวอร์ชันของ System.Text.Json หรือ System.Text.Encodings.Web ให้ต่ำกว่าขึ้นตอนที่ Doconut.NETStandard กำหนดไว้ 9.0.x ให้ลบการลดเวอร์ชันและให้ NuGet ทำการกู้คืนกราฟของแพคเกจ (System.Text.Json 9.0.0 และ System.Text.Encodings.Web 9.0.0 ในแพคเกจ 26.8.0 ที่ตรวจสอบแล้ว)

กำแพงของข้อผิดพลาดการคอมไพล์ปรากฏทันทีหลังอัปเดตแพคเกจ — สิ่งนี้เป็นเรื่องปกติ 26.8.0 มี API surface ที่แตกต่างจาก 26.7.0 ไม่ใช่การอัปเดตที่เข้ากันได้ ส่วนใหญ่ของข้อผิดพลาดเป็นบรรทัด using ที่ย้ายไปยังเนมสเปซราก Doconut ให้ทำตามขั้นตอน ย้ายไปใช้ .NET Standard 2.1 แทนการแก้ไขทีละรายการ

TypeInitializationException on the first presentation file:

Could not load ... System.Drawing.Common, Version=6.0.0.0

เอนจินการนำเสนอจำเป็นต้องใช้ System.Drawing.Common 6.0.0 (ที่ประกาศในแพคเกจ) อย่าลบหรือเขียนทับการพึ่งพานี้ — ทุกการเปิดไฟล์ PPT/PPTX/PPS/POT/ODP จะล้มเหลวหากไม่มีมัน

ผลลัพธ์แสดงผลไม่ถูกต้อง

หน้าแสดงลายน้ำ — แอปอยู่ในสถานะการประเมิน: ไม่พบไฟล์ใบอนุญาต, หน้าต่างชั่วคราวหรือการสมัครสมาชิกหมดอายุ, หรือโดเมนไม่ถูกต้อง ตรวจสอบ IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — การอ้างอิง IDoconutLicenseService ของหน้า Licensing แสดง endpoint ที่พร้อมใช้งาน

เอกสารรุ่นเก่าแสดงข้อความเป็นอักขระผิดพลาด — การเข้ารหัส code‑page ไม่ได้ถูกโหลดโดยค่าเริ่มต้น ให้เพิ่มหนึ่งครั้งที่การเริ่มต้น

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

ฟอนต์ไม่ถูกต้องหรือถูกแทนที่บน Linux/Docker — คอนเทนเนอร์ไม่มีฟอนต์ของเอกสาร ให้กำหนด FontFolders (บน WordConfig/PptConfig) ให้ชี้ไปยังไดเรกทอรีฟอนต์ที่เมานท์ไว้

การนำเสนอเปิดได้แต่ไม่สามารถเรนเดอร์บน Linux/macOS — ตัวเรนเดอร์ PPT/PPTX/PPS/POT/ODP ปัจจุบันต้องการ libgdiplus แบบเนทีฟพร้อมกับ System.Drawing.EnableUnixSupport=true แพคเกจจึงจัดหา System.Drawing.Common 6.0.0 เพราะเป็นเวอร์ชันสุดท้ายที่รองรับสวิตช์นี้

ฟีเจอร์ทำงานในโหมดประเมิน แต่เงียบในโปรดักชัน

ความประหลาดใจแบบคลาสสิกเมื่อเปิดใช้งานจริง: ใบอนุญาต Temporary ที่ใช้งานอยู่ให้ทุกความสามารถ; ใบอนุญาตที่คุณซื้อให้เฉพาะสิ่งที่คุณได้ซื้อเท่านั้น แพ็คเกจการค้นหาและการทำโน้ตอาจหายไปเมื่อความสามารถของมันไม่มี ปลั๊กอิน Converter หรือ DICOM ที่ลงทะเบียนไว้แต่มีใบอนุญาตไม่ใช่แบบชั่วคราวที่ไม่เพียงพอจะล้มเหลวระหว่าง AddDoconut() ให้เปรียบเทียบ IsCapabilityGranted(...) กับทุกฟีเจอร์ที่คุณเปิดใช้งานก่อนการปรับใช้

การค้นหาไม่พบอะไร (หรือพบน้อยเกินไป)

• สำหรับ PDF โดยตรง AllowSearch ไม่ได้ถูกเปิดใช้งานในขณะเปิดไฟล์ Word, Excel และ PowerPoint จะเปิดสวิตช์เดียวกันผ่าน PdfConfig ที่ซ้อนอยู่
• เนื้อหาเป็นแบบสแกน/ภาพเท่านั้น ทำให้การค้นหาปกติไม่มีชั้นข้อความให้จับคู่ ให้ใช้แหล่งข้อมูลที่มีข้อความหรือการฉายภาพ PDF ที่คงข้อความไว้
• HTML และ MS Project (MPP) ไม่สามารถค้นหาได้ตามค่าเริ่มต้น — ตั้งค่า DefaultRender = false เพื่อให้พวกมันเรนเดอร์ผ่านการฉายภาพ PDF ที่มีชั้นข้อความพื้นฐาน Word, Excel, PowerPoint, TXT, Visio, email, EPUB และ MHT จะค้นหาได้ตามค่าเริ่มต้นของแคตาล็อก
• objViewer.CanSearch() มีค่า false หลังการเริ่มต้น — รูปแบบที่ได้แก้ไขไม่มีเส้นทางการค้นหามาตรฐาน คำตัดสินนี้แยกจากใบอนุญาต Search; โปรดตรวจสอบทั้งสองอย่างพร้อมกัน

ยังติดอยู่หรือ?

แยกปัญหาออกจากแอป Quick Start ขั้นพื้นฐาน; หากมันเกิดซ้ำที่นั่น, ติดต่อฝ่ายสนับสนุนพร้อมเอกสาร, Program.cs ของคุณ, และผลการวินิจฉัยใบอนุญาต