Просмотрщик

Viewer (namespace Doconut) является публичной точкой входа для открытия документов из контроллеров MVC, страниц Web Forms и обработчиков. Это transient сервис, создаваемый DoconutHost.Initialize; получайте его там, где используете:

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() также работает после выполнения DoconutHost.Initialize — он разрешает те же сервисы — что позволяет сохранять совместимость кода, перенесённого из классического пакета. До вызова Initialize он бросает InvalidOperationException.

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

OpenDocumentAsync

Открывает документ и возвращает токен сеанса, который виджет использует для всех последующих запросов. Когда UnsafeMode равно false (по умолчанию), токен привязывается к ASP.NET‑сессии текущего запроса — вызывайте его из запроса, имеющего состояние сессии (см. Сессии и безопасность).

// 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 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

Исключения, которые следует обрабатывать:

• LicenseException — лицензия была найдена, но отклонена (сообщение содержит причину), либо формат требует возможности плагина, которой лицензия не предоставляет.
• FormatNotSupportedException — ни один просмотрщик не поддерживает расширение файла.
• InvalidDataException — содержимое повреждено или не соответствует его расширению.

OpenDocument (synchronous)

Для кода‑behind Web Forms и другого кода, который не использует асинхронные страницы:

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

Каждый из них возвращает токен и также сохраняет его в viewer.Token. fileName должен содержать правильное расширение. Эти обёртки безопасно вызывать из страницы Web Forms: путь открытия никогда не возобновляется в контексте запроса ASP.NET, поэтому ожидание не может привести к взаимной блокировке. То же самое не верно для всех асинхронных API Doconut — см. раздел Web Forms в Плагине конвертера.

CloseDocument

void CloseDocument(string token)

Удаляет сессию (немедленно освобождая движок документа), удаляет предоставление токена из текущей ASP.NET‑сессии запроса и аннулирует токен. Необязательно — скользящее истечение времени выполняет ту же очистку — но рекомендуется для больших документов.

Запросы сессии

Каждый метод бросает исключение, если токен неизвестен или истёк.

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

Парсер ожидает ровно шесть полей после необязательного ^. Некорректное определение заменяется видимым текстом Invalid Watermark вместо тихого исчезновения.

Решение по лицензии

То же решение применяется к обслуживаемым страницам и к экспорту аннотаций. Пользовательский водяной знак — это функция лицензированного приложения, а не способ заменить оценочный знак.

API аннотаций

Загрузка и экспорт аннотаций на стороне сервера. Руководство находится в разделе Аннотации.

Метаданные DICOM

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

В этом пакете он всегда возвращает null, а запрос метаданных виджета отвечает 501 Not Implemented: чтение тегов DICOM недоступно в .NET Framework. Рендеринг DICOM — страницы, кадры и анимация — работает. См. Плагин DICOM.

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

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

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // состояние лицензии, для защиты кода инициализации ленты
bool IsAnnotationEnabled { get; }

Флаги CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ограничено поиском), IncludeAnnotationCss (ограничено аннотациями).

Флаги ScriptConfig: IncludeJQuery (требуется всем остальным), IncludeBootstrap, IncludeViewerScripts (основные скрипты просмотрщика), IncludeSearchScripts и IncludeSearchBar (ограничено поиском), IncludeAnnotationScripts и IncludeAnnotationBar (ограничено аннотациями).

Оба возвращают HTML: выводите их с помощью @Html.Raw(...) в MVC 5 (генерируйте в контроллере — в представлениях нет @inject) или <%= %> в Web Forms. Быстрый старт показывает оба варианта.

RenderViewer

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

Возвращает блок <script>, который инициализирует виджет в элементе с id elementId и отображает документ: docViewer({...}), построенный из ViewerConfig (по умолчанию: BasePath: '/', ResPath: 'doconut-res/images'), затем вызывается .View(token). Разместите его после скриптов просмотрщика. Сгенерированный скрипт не сохраняет ссылку на объект просмотрщика, поэтому страница со своей панелью инструментов должна инициализировать виджет вручную. См. ViewerConfig.

Веб-ферма

string? AccessToken хранит подписанный билет, выданный последним открытием при активном распределённом режиме и UnsafeMode = false; в односерверной конфигурации он null. Передайте его виджету вместе с токеном: objViewer.View(token, access).