Viewer – Doconut เอกสาร

Viewer (namespace Doconut) เป็นจุดเข้าถึงสาธารณะสำหรับการเปิดเอกสารจาก Razor pages, MVC controllers, Blazor components หรือ minimal APIs. มันเป็น sealed, ลงทะเบียนเป็นบริการ transient โดย AddDoconut(), และได้รับการแก้ไขผ่านการฉีดคอนสตรัคเตอร์ — ไม่ควรสร้างมันโดยตรง.

Viewer ไม่เก็บสถานะต่อคำขอและตั้งใจ ไม่ implement IDisposable: เซสชันเอกสารทำงานอย่างอิสระในแคชของเซสชัน, ดังนั้นการทำลายบริการจะไม่สามารถปิดเอกสารที่เปิดอยู่ได้ (ดู Core Concepts → How the Viewer Works).

OpenDocumentAsync

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

Overload	Use when
`Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)`	เปิดจากดิสก์ด้วยการตรวจจับรูปแบบอัตโนมัติและการตั้งค่าเริ่มต้นของรูปแบบนั้น
`Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)`	ต้องการตัวเลือกการเรนเดอร์ต่อรูปแบบ (`PdfConfig`, `WordConfig`, …)
`Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)`	เอกสารไม่ได้เป็นไฟล์บนดิสก์ (อัปโหลด, ฐานข้อมูล, blob). `fileInfo` ต้องมีส่วนขยายที่ถูกต้อง — ใช้สำหรับการตรวจจับรูปแบบ

csharp

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Exceptions to handle:

LicenseException — ใบอนุญาตที่พบถูกปฏิเสธ (ข้อความจะบอกเหตุผลการปฏิเสธ), หรือรูปแบบต้องการความสามารถของปลั๊กอินที่ไม่ได้รับการให้สิทธิ์อีกต่อไป. การหมดอายุของปฏิทินโดยไม่มีข้อความปฏิเสธจะทำให้การเรนเดอร์แสดงลายน้ำแทนการโยนข้อผิดพลาด.
FormatNotSupportedException — Document format '<extension>' is not supported.
InvalidDataException — เนื้อหาไฟล์เสียหายหรือไม่ตรงกับส่วนขยายของไฟล์.

CloseDocument

text

void CloseDocument(string token)

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

GetPageCount

text

int GetPageCount(string token)

จำนวนหน้าทั้งหมดของเซสชันที่เปิดอยู่. จะโยนข้อผิดพลาดหาก token ไม่รู้จักหรือหมดอายุ.

DocOptions

ตัวเลือกที่ไม่ขึ้นกับรูปแบบต่อการเปิด (namespace Doconut):

Type	Property	Default	Description
`string`	`Password`	`""`	รหัสผ่านสำหรับเอกสารที่ถูกป้องกัน (จะคัดลอกไปยังการตั้งค่ารูปแบบโดยอัตโนมัติ).
`int`	`ImageResolution`	`0`	Obsolete. เก็บไว้เพื่อความเข้ากันได้เท่านั้น — ตั้งค่า `ImageResolution` บนการตั้งค่ารูปแบบแทน.
`string`	`Watermark`	`""`	ข้อความลายน้ำที่กำหนดเองซึ่งวาดบนหน้าที่เรนเดอร์. รูปแบบสตริง: `"^Text~Color~FontSize~FontName~Opacity~Angle"`, ตัวอย่าง `"^Sample Copy~Red~24~Verdana~80~-45"`.
`int`	`TimeOut`	`60`	การหมดอายุแบบเลื่อนของเซสชันเป็นนาที.
`bool`	`IsSecured`	`true`	Not currently enforced — reserved. การผูก token ถูกควบคุมโดยทั่วโลกโดย `DoconutOptions.UnsafeMode` (ดู Core Concepts → Sessions & Security).

คลาสนี้ยังเปิดเผยคุณสมบัติพิเศษที่ตั้งใจอยู่นอกกระบวนการดูเอกสารแบบโฮสต์เดียวปกติ:

Type	Property	Default	Description
`bool`	`IsWebFarm`	`false`	ระบุว่าการเปิดเป็นสถานการณ์เว็บฟาร์ม. ใช้เฉพาะกับสถาปัตยกรรมที่จัดเก็บ/เซสชันร่วมกันที่สอดคล้อง.
`string`	`WebFarmPath`	`""`	เส้นทางที่ใช้ร่วมกันในกระบวนการเว็บฟาร์มพิเศษ. เป็นค่าว่างในตัวดูเอกสารโฮสต์เดียวปกติ.
`bool`	`EditMode`	`false`	จองไว้สำหรับกระบวนการ Editor ที่แยกออกมา; ให้เป็น `false` สำหรับตัวดูมาตรฐาน.

Custom watermark

DocOptions.Watermark ใช้หกฟิลด์ที่คั่นด้วย tilde. ตัวเลือกนำหน้า ^ จะร้องขอการจัดวางแบบทุกมุม:

text

^Text~Color~FontSize~FontName~Opacity~Angle

csharp

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

Field	Example	Meaning
Leading `^`	`^`	การจัดวางแบบทุกมุม (optional). หากไม่มีจะใช้ตำแหน่งลายน้ำปกติ.
Text	`Confidential`	ข้อความที่แสดงบนแต่ละหน้า. ต้องไม่เป็นค่าว่าง.
Color	`Red`	สีที่กำหนดชื่อซึ่งเข้าใจโดยเลเยอร์การวาด.
FontSize	`24`	ขนาดฟอนต์; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้นของเรนเดอร์.
FontName	`Verdana`	ฟอนต์ที่ต้องการ. ตรวจสอบให้แน่ใจว่าติดตั้งในสภาพแวดล้อมการปรับใช้.
Opacity	`80`	ค่าไบต์จาก 0 ถึง 255. ต้องแปลงสำเร็จ.
Angle	`-45`	มุมการหมุนเป็นองศา; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้น.

ตัวพาร์สเซอร์คาดหวังฟิลด์หกฟิลด์หลัง ^ (ถ้ามี). คำจำกัดความที่ไม่ถูกต้องจะถูกแทนที่ด้วย Invalid Watermark ของ SDK แทนการหายไปโดยเงียบ.

License decision

License state	Custom value supplied	Rendered result
Valid paid viewer license	No	Clean page
Valid paid viewer license	Yes	Custom watermark
Active Temporary/Demo base viewer	No	Clean base-viewer page
Active Temporary/Demo base viewer	Yes	Custom watermark when the clean base-viewer path applies
Missing, rejected, expired, wrong-version, or invalid-domain license	Either	Enforcement/evaluation watermark; the custom value does not override it
Plugin rendering under evaluation rules	Either	Evaluation watermark

การตัดสินใจเดียวกันนี้จะถูกใช้กับภาพหน้าที่ให้บริการและการส่งออกหมายเหตุ. ผลลัพธ์ GIF แบบเคลื่อนไหวจะถูกประทับแต่ละเฟรม. ดังนั้นลายน้ำที่กำหนดเองจึงเป็นฟีเจอร์ที่ต้องมีใบอนุญาต, ไม่ใช่วิธีการแทนที่หรือปิดลายน้ำการประเมิน.

Annotations API

การโหลดและส่งออกหมายเหตุด้านเซิร์ฟเวอร์. คำแนะนำเต็มอยู่ใน Guides → Annotations; ส่วนที่ให้ใช้คือ:

Member	Purpose
`AnnotationManager GetAnnotationManager(string token)`	ตัวจัดการที่ผูกกับมิติของหน้าที่อยู่ในเซสชันที่เปิด
`AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)`	ตัวจัดการที่กำหนดมิติหน้าโดยชัดเจน
`AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)`	ตัวจัดการที่ไม่ขึ้นกับเซสชัน
`void LoadAnnotationData(string token, AnnotationManager manager)`	โหลดหมายเหตุที่สร้างด้วย C# เข้าสู่เซสชัน
`void LoadAnnotationData(string token, string annotationData)`	โหลดหมายเหตุจาก envelope ที่เข้ารหัสเป็นหน้า/Base64 ที่คืนจาก `AnnotationManager.GetAnnotationData()`
`void LoadAnnotationXML(string token, XmlDocument annotationXml)`	โหลดหมายเหตุจาก XML
`XmlDocument GetAnnotationXML(string token)`	ส่งออกหมายเหตุของเซสชันเป็น XML
`Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)`	PDF ที่ฝังหมายเหตุไว้
`Task<int> ExportAnnotationsToPngAsync(…)`	ไฟล์ PNG ที่ฝังหมายเหตุไว้
`Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)`	ZIP ของ PNG ต่อหน้า ที่ฝังหมายเหตุไว้

DICOM metadata

text

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

เมธอดนี้มีเพื่อให้สอดคล้องกับ API, แต่ตัวดู DICOM ของ .NET 6 ไม่สามารถให้แท็กทางเทคนิคได้. มันจะคืนค่า null สำหรับเซสชัน DICOM และ non-DICOM; ในเซสชัน DICOM จะเขียนคำเตือนหนึ่งครั้งอธิบายข้อจำกัดของแพลตฟอร์ม. การเรนเดอร์หน้า, เฟรม, และแอนิเมชันยังคงสนับสนุน.

Resource helpers — ReferenceCss / ReferenceScripts

สร้างแท็ก <link>/<script> สำหรับทรัพยากรที่ฝังไว้ที่ให้บริการโดย UseDoconutResources(), ตามลำดับการพึ่งพาที่ถูกต้อง. แพ็กเกจสำหรับฟีเจอร์ที่ต้องมีใบอนุญาต เช่น การค้นหาและการทำหมายเหตุ จะถูกสร้าง เฉพาะเมื่อใบอนุญาตเปิดใช้งาน, ทำให้ UI ของไคลเอนต์สอดคล้องกับพฤติกรรมของเซิร์ฟเวอร์.

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig flags: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated).

html

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))