Переглядач

Viewer (namespace Doconut) — це публічна точка входу для відкриття документів з Razor‑сторінок, MVC‑контролерів, Blazor‑компонентів або мінімальних API. Він запечатаний, зареєстрований як транзієнтна служба за допомогою AddDoconut(), і отримується через ін’єкцію в конструктор — ніколи не створюйте його безпосередньо.

Viewer не зберігає стану на запит і навмисно не реалізує IDisposable: сеанси документів живуть незалежно в кеші сеансів, тому звільнення служби ніколи не може закрити відкритий документ (див. Основні концепції → Як працює переглядач).

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

Користувацький водяний знак

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 клієнта з поведінкою сервера.

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))