Просмотрщик

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

Viewer не хранит состояние запроса и намеренно не реализует IDisposable: сеансы документов живут независимо в кэше сеансов, поэтому освобождение сервиса никогда не может закрыть открытый документ (см. Основные концепции → Как работает Viewer).

OpenDocumentAsync

Открывает документ и возвращает токен сеанса, который клиентский виджет использует для всех последующих запросов.

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

Общее количество страниц открытого сеанса. Выбрасывает исключение, если токен неизвестен или истёк.

DocOptions

Параметры, независимые от формата, задаваемые при открытии (namespace Doconut):

Custom watermark

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 аннотаций

Загрузка и экспорт аннотаций на стороне сервера. Полный пошаговый гид находится в Руководства → Аннотации; интерфейс выглядит так:

Метаданные DICOM

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

Возвращает метаданные DICOM‑тегов для сеансов, открытых через плагин DICOM; null для недICOM‑документов.

Вспомогательные ресурсы — ReferenceCss / ReferenceScripts

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

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