Переглядач

Viewer (namespace Doconut) є публічною точкою входу для відкриття документів з контролерів MVC, сторінок Web Forms та обробників. Це транзієнтна служба, створена DoconutHost.Initialize; отримайте її там, де використовуєте:

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

new Viewer() також працює після запуску DoconutHost.Initialize — він вирішує ті самі служби — що дозволяє зберегти сумісність коду, мігруваного з класичного пакету. До Initialize викликає InvalidOperationException.

Viewer не зберігає стан документа на запит і навмисно не реалізує IDisposable: сеанси документів живуть незалежно від нього, тому знищення 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 (синхронний)

Для коду‑бекенду 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 Plugin.

Помічники ресурсів — 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; }                       // license state, for guarding ribbon init code
bool IsAnnotationEnabled { get; }

CssConfig прапорці: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig прапорці: IncludeJQuery (потрібний усім іншим), IncludeBootstrap, IncludeViewerScripts (основні скрипти переглядача), IncludeSearchScripts і IncludeSearchBar (search-gated), IncludeAnnotationScripts і IncludeAnnotationBar (annotation-gated).

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

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