Переглядач

Viewer (простір імен Doconut) є публічною точкою входу для відкриття документів з Razor‑сторінок, MVC‑контролерів, компонентів Blazor або мінімальних API. Він запечатаний, зареєстрований як транзієнтна служба за допомогою AddDoconut(), і отримується через ін’єкцію в конструктор — ніколи не створюйте його безпосередньо.

Попередня бібліотека .NET Standard надавала публічний конструктор, який приймав кеш пам’яті, accessor HTTP‑контексту та один або кілька шляхів до ліцензій. Цей конструктор більше не існує; граф сервісів постачає ці залежності.

Viewer не зберігає стану на запит і навмисно не реалізує IDisposable: сеанси документів живуть незалежно в кеші сеансів, тому вивільнення служби ніколи не може закрити відкритий документ (див. Основні концепції → Як працює Viewer).

OpenDocumentAsync

Відкриває документ і повертає токен сеансу, який клієнтський віджет використовує для всіх подальших запитів. Кожне відкриття виконується асинхронно — синхронного OpenDocument не існує.

// 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

void CloseDocument(string token)

Видаляє сеанс з кешу (негайно звільняє движок документа), видаляє маркер безпеки та анулює наданий доступ. Необов’язково — скользяче закінчення терміну виконує те ж очищення — проте рекомендується для великих документів.

GetPageCount

int GetPageCount(string token)

Загальна кількість сторінок відкритого сеансу. Викидає виключення, якщо токен невідомий або прострочений.

Прапори можливостей

Використовуйте ці властивості у Razor‑виді для відображення ліцензованої стрічки лише коли сервер дійсно її надає — див. Швидкий старт.

DocOptions

Параметри, незалежні від формату, що задаються під час відкриття (простір імен Doconut):

Клас також містить спеціалізовані властивості, які навмисно виходять за межі звичайного однохостового процесу перегляду:

Користувацький водяний знак

DocOptions.Watermark використовує шість полів, розділених тильдами. Необов’язковий початковий символ ^ запитує розташування у всіх кутах:

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

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

Парсер очікує саме шість полів після необов’язкового ^. Неправильне визначення замінюється на видимий у SDK запасний варіант Invalid Watermark замість того, щоб просто зникнути.

Рішення щодо ліцензії

Те саме рішення застосовується до зображень сторінок, що подаються, та експортів анотацій. Вихід у форматі анімованого GIF маркується кадр за кадром. Таким чином, користувацький водяний знак є функцією ліцензованого застосунку, а не способом замінити або придушити водяний знак оцінки.

API анотацій

Завантаження та експорт анотацій на боці сервера. Повний посібник розташований у Guides → Annotations; основна схема виглядає так:

Кожен з цих методів приймає токен сесії. Форма безсесійного GetAnnotationManager(pageWidth, pageHeight) з попередньої бібліотеки зберігається для створення анотацій поза сесією, проте їхнє завантаження все одно вимагає токен.

Метадані DICOM

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

Метод присутній для узгодженості API, проте цей пакет не може постачати технічні теги DICOM: читач метаданих постачається лише у збірці .NET 8. Він повертає null для DICOM‑ і недо‑DICOM‑сесій; у DICOM‑сесії також виводить одноразове попередження про обмеження платформи. Рендеринг сторінок, кадрів і анімації залишається підтримуваним.

Помічники ресурсів — ReferenceCss / ReferenceScripts

Виводить теги <link>/<script> для вбудованих ресурсів, що надаються UseDoconutResources(), у правильному порядку залежностей. Пакети для функцій, доступних лише за ліцензією, таких як пошук та анотація, виводяться лише коли ліцензія їх дозволяє, забезпечуючи узгодженість інтерфейсу клієнта з поведінкою сервера.

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

CssConfig прапорці: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (пошук‑залежний), IncludeAnnotationCss (аннотація‑залежний).

ScriptConfig прапорці: IncludeJQuery (потрібний для всіх інших), IncludeBootstrap, IncludeViewerScripts (ядро: docViewer.js + splitter + links), IncludeSearchScripts та IncludeSearchBar (пошук‑залежний), IncludeAnnotationScripts та IncludeAnnotationBar (аннотація‑залежний).

@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, повинні видалити ці копії після того, як сторінка буде відображена за допомогою виведених тегів.