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, rejestrowany jako usługa transient przez AddDoconut() i rozwiązywany poprzez wstrzykiwanie przez konstruktor — nigdy nie twórz go bezpośrednio.

Poprzednia biblioteka .NET Standard udostępniała publiczny konstruktor przyjmujący pamięciowy cache, dostęp do kontekstu HTTP oraz jedną lub więcej ścieżek licencji. Ten konstruktor został usunięty; graf usług dostarcza te zależności.

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

OpenDocumentAsync

Otwiera dokument i zwraca token sesji, którego widget kliencki używa we wszystkich kolejnych żądaniach. Każde otwarcie jest asynchroniczne — nie istnieje synchroniczny OpenDocument.

// Proste otwarcie
string token = await viewer.OpenDocumentAsync(path);

// Z konfiguracją i opcjami dla każdego formatu
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Z przesyłki
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Exceptions to handle:

• LicenseException — znaleziona licencja zostaje odrzucona (wiadomość zawiera przyczynę odrzucenia), lub format wymaga możliwości wtyczki, która nie jest już przyznana. Wygaśnięcie kalendarza bez komunikatu o odrzuceniu skutkuje renderowaniem z znakiem wodnym zamiast wyrzucenia wyjątku.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• 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 przesuwne wykonuje tę samą czynność czyszczenia — ale jest zalecane dla dużych dokumentów.

GetPageCount

int GetPageCount(string token)

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

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Zwraca nazwy arkuszy otwartego arkusza kalkulacyjnego, w kolejności skoroszytu, lub pustą listę, gdy otwarty dokument nie jest arkuszem kalkulacyjnym.

Wymieniane są tylko renderowane arkusze: ukryte i puste arkusze są pomijane, a gdy ExcelConfig.SheetNames ogranicza renderowanie, pojawiają się tylko te arkusze. Arkusz nie zawsze odpowiada jednej stronie — bardzo duży arkusz jest renderowany na kilku stronach. Rzuca wyjątek, jeśli token jest nieznany lub wygasł.

Dodano w wersji 26.9.0.

Flagi możliwości

Użyj ich w widoku Razor, aby renderować licencjonowaną wstążkę tylko wtedy, gdy serwer faktycznie ją udostępni — zobacz Szybki start.

DocOptions

Opcje niezależne od formatu, obowiązujące przy każdym otwarciu (przestrzeń nazw Doconut):

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

Niestandardowy znak wodny

DocOptions.Watermark używa sześciu pól oddzielonych tyldą. Opcjonalny wiodący ^ żąda układu we 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 widoczną wartością zastępczą Invalid Watermark SDK zamiast cichego zniknięcia.

Decyzja licencyjna

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

API adnotacji

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

Każdy z nich przyjmuje token sesji. Kształt GetAnnotationManager(pageWidth, pageHeight) wolny od sesji w poprzedniej bibliotece nadal istnieje do budowania adnotacji poza sesją, ale ich wczytanie nadal wymaga tokena.

Metadane DICOM

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

Metoda jest dostępna w celu zachowania zgodności API, ale ten pakiet nie może dostarczyć technicznych tagów DICOM: czytnik metadanych jest dostępny tylko w wersji .NET 8. Zwraca null dla sesji DICOM i nie‑DICOM; w sesji DICOM dodatkowo wypisuje jednorazowe ostrzeżenie wyjaśniające ograniczenie platformy. Renderowanie stron, klatek i animacji pozostaje wspierane.

Pomocnicy zasobów — ReferenceCss / ReferenceScripts

Wstaw tagi <link>/<script> dla osadzonych 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 klienta spójny z zachowaniem serwera.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + przeglądarka + wyszukiwanie + adnotacja
string ReferenceScripts(ScriptConfig? config = null)

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

ScriptConfig flags: 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 }))

Ci pomocnicy są wspieranym sposobem dostarczania zasobów przeglądarki. Aplikacje, które skopiowały docViewer.js, documentLinks.js i docViewer.UI.js do wwwroot, powinny usunąć te kopie po tym, jak strona zostanie wyrenderowana z emitowanych tagów.