Viewer – Doconut เอกสาร

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

ไลบรารี .NET Standard ก่อนหน้านี้เปิดเผยคอนสตรัคเตอร์สาธารณะที่รับ memory cache, HTTP context accessor, และหนึ่งหรือหลายเส้นทางใบอนุญาต. คอนสตรัคเตอร์นั้นได้หายไป; กราฟบริการจะจัดหาขึ้นอยู่เหล่านั้นให้โดยอัตโนมัติ.

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

OpenDocumentAsync

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

รูปแบบการเรียก	ใช้เมื่อ
`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));

ข้อยกเว้นที่ต้องจัดการ:

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

CloseDocument

text

void CloseDocument(string token)

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

GetPageCount

text

int GetPageCount(string token)

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

Capability flags

สมาชิก	ความหมาย
`bool IsSearchEnabled`	ใบอนุญาตปัจจุบันให้สิทธิ์ `Search`
`bool IsAnnotationEnabled`	ใบอนุญาตปัจจุบันให้สิทธิ์ `Annotation`

ใช้ค่าเหล่านี้ใน Razor view เพื่อเรนเดอร์ Ribbon ที่มีลิขสิทธิ์เฉพาะเมื่อเซิร์ฟเวอร์จะให้บริการจริง — ดู เริ่มต้นอย่างเร็ว.

DocOptions

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

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`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`	การหมดอายุแบบ sliding ของเซสชันเป็นนาที
`bool`	`IsSecured`	`true`	Not currently enforced — จองไว้. การผูก token ถูกควบคุมโดยทั่วโลกโดย `DoconutOptions.UnsafeMode` (ดู แนวคิดหลัก → Sessions & Security)

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

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`bool`	`IsWebFarm`	`false`	ทำเครื่องหมายการเปิดเป็นสถานการณ์ที่ใช้ที่เก็บข้อมูลร่วม. โปรดสังเกตการใช้ตัวพิมพ์ใหญ่ — ไลบรารีก่อนหน้านี้ใช้ `IsWebfarm`
`string`	`WebFarmPath`	`""`	เส้นทางที่ใช้ร่วมกันในเวิร์กโฟลว์นั้น. ก่อนหน้านี้เขียนเป็น `WebfarmPath`. เป็นค่าว่างใน Viewer โฮสต์เดียวปกติ, และไม่จำเป็นบนเส้นทางเผยแพร่ที่อธิบายใน การปรับใช้แบบกระจาย
`bool`	`EditMode`	`false`	จองไว้สำหรับเวิร์กโฟลว์การแก้ไขที่แจกจ่ายแยกต่างหาก; ให้เป็น `false` สำหรับ Viewer มาตรฐาน

ลายน้ำแบบกำหนดเอง

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
    });

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

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

การตัดสินใจเรื่องใบอนุญาต

สถานะใบอนุญาต	ค่าที่กำหนดเองที่ให้	ผลลัพธ์ที่แสดง
ใบอนุญาตผู้ชมแบบจ่ายเงินที่ถูกต้อง	ไม่มี	หน้าสะอาด
ใบอนุญาตผู้ชมแบบจ่ายเงินที่ถูกต้อง	มี	ลายน้ำแบบกำหนดเอง
ผู้ชมฐานชั่วคราว/สาธิตที่ใช้งานอยู่	ไม่มี	หน้าฐานผู้ชมสะอาด
ผู้ชมฐานชั่วคราว/สาธิตที่ใช้งานอยู่	มี	ลายน้ำแบบกำหนดเองเมื่อเส้นทางผู้ชมฐานสะอาดถูกใช้
ใบอนุญาตที่หายไป, ถูกปฏิเสธ, หมดอายุ, เวอร์ชันไม่ตรง, หรือโดเมนไม่ถูกต้อง	ใดก็ได้	ลายน้ำบังคับ/ประเมิน; ค่าที่กำหนดเองจะไม่ทับแทน
การเรนเดอร์ปลั๊กอินภายใต้กฎการประเมิน	ใดก็ได้	ลายน้ำการประเมิน

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

API คำอธิบายภาพ

การโหลดและส่งออกคำอธิบายภาพบนเซิร์ฟเวอร์ คู่มือเต็มอยู่ใน Guides → Annotations; ส่วนสรุปคือ:

สมาชิก	วัตถุประสงค์
`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)`	โหลดคำอธิบายภาพจากหน้า/ซอง 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 แยกหน้าแต่ละหน้าที่ฝังคำอธิบายภาพไว้

แต่ละเมธอดเหล่านี้ต้องรับโทเค็นของเซสชัน ไลบรารีก่อนหน้าที่มีรูปแบบ GetAnnotationManager(pageWidth, pageHeight) ที่ไม่ต้องใช้เซสชันยังคงอยู่สำหรับสร้างคำอธิบายภาพนอกเซสชัน แต่การโหลดยังคงต้องใช้โทเค็น

เมตาดาต้า DICOM

text

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

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

ตัวช่วยทรัพยากร — ReferenceCss / ReferenceScripts

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

text

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

CssConfig แฟล็ก: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig แฟล็ก: 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 }))

ตัวช่วยเหล่านี้เป็นวิธีที่สนับสนุนสำหรับการส่งมอบทรัพยากรของเบราว์เซอร์ แอปพลิเคชันที่คัดลอก docViewer.js, documentLinks.js, และ docViewer.UI.js ไปยัง wwwroot ควรลบไฟล์คัดลอกเหล่านั้นออกเมื่อหน้าเว็บแสดงผลจากแท็กที่สร้างขึ้น.