Переглядач

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

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

Viewer не містить стану, специфічного для запиту, і навмисно не реалізує IDisposable: сеанси документів живуть незалежно в кеші сеансу, тому видалення сервісу ніколи не може закрити відкритий документ (див. Core Concepts → How the Viewer Works).

OpenDocumentAsync

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

// Просте відкриття
string token = await viewer.OpenDocumentAsync(path);

// З конфігурацією та параметрами для кожного формату
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// З завантаження
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)

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

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Повертає назви листів відкритої електронної таблиці у порядку книги, або порожній список, якщо відкритий документ не є електронною таблицею.

Перераховуються лише відрендерені листи: приховані та порожні листи виключаються, і коли ExcelConfig.SheetNames обмежує рендеринг, відображаються лише ці листи. Лист не завжди відповідає одній сторінці — дуже великий лист розбивається на кілька сторінок. Викидає виключення, якщо токен невідомий або прострочений.

Додано у 26.9.0.

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

Використовуйте їх у 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 та недICOM сесій; у DICOM‑сесії він також виводить одноразове попередження, що пояснює обмеження платформи. Відтворення сторінок, кадрів та анімації залишається підтримуваним.

Допоміжні ресурси — ReferenceCss / ReferenceScripts

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

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + переглядач + пошук + анотація
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, повинні видалити ці копії після того, як сторінка відобразиться за допомогою виведених тегів.