Просмотрщик

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

В предыдущей библиотеке .NET Standard был публичный конструктор, принимающий кэш памяти, аксессор HTTP‑контекста и один или несколько путей к лицензиям. Этот конструктор удалён; граф сервисов поставляет эти зависимости.

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

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)

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

Capability flags

Используйте эти свойства в Razor‑view, чтобы отрисовать лицензированную ленту только тогда, когда сервер действительно её обслуживает — см. Быстрый старт.

DocOptions

Параметры, независимые от формата, задаваемые при каждом открытии (namespace 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‑сессии также выводит одноразовое предупреждение, объясняющее ограничение платформы. Отображение страниц, кадров и анимаций остаётся поддерживаемым.

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

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

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

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