Просмотрщик

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

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

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