Viewer

Viewer (namespace Doconut) jest publicznym punktem wejścia do otwierania dokumentów z Razor pages, kontrolerów MVC, komponentów Blazor lub minimalnych API. Jest sealed, zarejestrowany jako usługa transient przez AddDoconut(), i rozwiązywany poprzez wstrzykiwanie przez konstruktor — nigdy nie twórz go bezpośrednio.

Viewer nie przechowuje stanu per‑request i celowo nie implementuje IDisposable: sesje dokumentów istnieją niezależnie w pamięci podręcznej sesji, więc zwolnienie usługi nigdy nie mogłoby zamknąć otwartego dokumentu (zobacz Podstawowe pojęcia → Jak działa Viewer).

OpenDocumentAsync

Otwiera dokument i zwraca token sesji, którego widget kliencki używa we wszystkich kolejnych żądaniach.

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

Wyjątki do obsłużenia:

• LicenseException — znalezione licencja jest odrzucona (wiadomość zawiera przyczynę odrzucenia) lub format wymaga możliwości wtyczki, która nie jest już przyznana. Wygaśnięcie kalendarza bez wiadomości o odrzuceniu skutkuje renderowaniem z znakiem wodnym zamiast wyrzucenia wyjątku.
• FormatNotSupportedException — Document format '<extension>' is not supported. (format dokumentu '' nie jest obsługiwany).
• InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia.

CloseDocument

void CloseDocument(string token)

Usuwa sesję z pamięci podręcznej (natychmiast zwalnia silnik dokumentu), usuwa znacznik bezpieczeństwa i cofa przyznany dostęp. Opcjonalnie — wygasanie ze ślizgiem wykonuje tę samą czynność czyszczenia — ale zalecane przy dużych dokumentach.

GetPageCount

int GetPageCount(string token)

Łączna liczba stron otwartej sesji. Rzuca wyjątek, jeśli token jest nieznany lub wygasł.

DocOptions

Opcje niezależne od formatu, stosowane przy otwieraniu (namespace Doconut):

Klasa udostępnia również specjalistyczne właściwości, które są celowo poza normalnym przepływem przeglądania jednego hosta:

Custom watermark

DocOptions.Watermark używa sześciu pól oddzielonych tyldą. Opcjonalny początkowy znak ^ żąda układu na wszystkich rogach:

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

Parser oczekuje dokładnie sześciu pól po opcjonalnym ^. Nieprawidłowa definicja jest zastępowana widocznym w SDK zastępstwem Invalid Watermark zamiast cichego zniknięcia.

License decision

Ta sama decyzja jest stosowana do serwowanych obrazów stron i eksportów adnotacji. Wyjście w formacie animowanego GIF jest znakowane klatka po klatce. Niestandardowy znak wodny jest więc funkcją licencjonowaną, a nie sposobem na zastąpienie lub ukrycie znaku wodnego ewaluacji.

Annotations API

Ładowanie i eksport adnotacji po stronie serwera. Pełny przewodnik znajduje się w Przewodniki → Adnotacje; interfejs to:

DICOM metadata

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

Zwraca metadane tagów DICOM dla sesji otwartych przez wtyczkę DICOM; null dla dokumentów nie‑DICOM.

Resource helpers — ReferenceCss / ReferenceScripts

Generuje znaczniki <link>/<script> dla wbudowanych zasobów serwowanych przez UseDoconutResources(), w prawidłowej kolejności zależności. Pakiety dla funkcji zabezpieczonych licencją, takich jak wyszukiwanie i adnotacje, są emitowane tylko gdy licencja je włącza, utrzymując interfejs UI klienta spójny z zachowaniem serwera.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

Flagi CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (zabezpieczone wyszukiwaniem), IncludeAnnotationCss (zabezpieczone adnotacjami).

Flagi ScriptConfig: IncludeJQuery (wymagane przez wszystkie pozostałe), IncludeBootstrap, IncludeViewerScripts (rdzeń: docViewer.js + splitter + links), IncludeSearchScripts i IncludeSearchBar (zabezpieczone wyszukiwaniem), IncludeAnnotationScripts i IncludeAnnotationBar (zabezpieczone adnotacjami).

@inject Doconut.Viewer Viewer

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