Przeglądarka

Viewer (namespace Doconut) jest publicznym punktem wejścia do otwierania dokumentów z stron Razor, kontrolerów MVC, komponentów Blazor lub minimalnych API. Jest sealed, rejestrowany jako usługa transient przez AddDoconut() i rozwiązywany poprzez wstrzykiwanie w konstruktorze — 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‑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 koncepcje → Jak działa Viewer).

OpenDocumentAsync

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

// 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 — znalezioną licencję odrzuca (wiadomość zawiera przyczynę odrzutu) lub format wymaga możliwości wtyczki, która nie jest już przyznana. Wygaśnięcie licencji bez komunikatu o odrzuceniu skutkuje renderowaniem z znakiem wodnym zamiast wyrzucenia wyjątku.
• FormatNotSupportedException — 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ść, ale jest zalecane przy dużych dokumentach.

GetPageCount

int GetPageCount(string token)

Zwraca całkowitą liczbę stron otwartej sesji. Rzuca wyjątek, jeśli token jest nieznany lub wygasł.

Flagi możliwości

Użyj ich w widoku Razor, aby wyświetlić licencjonowany pasek tylko wtedy, gdy serwer faktycznie go udostępni — zobacz Szybki start.

DocOptions

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

Klasa udostępnia także specjalistyczne właściwości, które są celowo poza normalnym przepływem podglądu w pojedynczym hoście:

Niestandardowy znak wodny

DocOptions.Watermark używa sześciu pól oddzielonych tyldą. Opcjonalny początkowy ^ żą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ą w SDK wartością Invalid Watermark zamiast zniknąć cicho.

Decyzja licencyjna

Ta sama decyzja ma zastosowanie 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ą aplikacji objętą licencją, 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; najważniejsze elementy to:

Każda z tych metod przyjmuje token sesji. Kształt biblioteki poprzedniej, wolny od sesji GetAnnotationManager(pageWidth, pageHeight), nadal istnieje do budowania adnotacji poza sesją, ale ich ładowanie wciąż wymaga tokenu.

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 jedynie 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

Emituj tagi <link>/<script> dla osadzonych zasobów udostępnianych przez UseDoconutResources(), w prawidłowej kolejności zależności. Pakiety dla funkcji ograniczonych licencją, takich jak wyszukiwanie i adnotacje, są emitowane tylko gdy licencja je włącza, co zapewnia spójność interfejsu klienta z zachowaniem serwera.

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

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

Flagi ScriptConfig: IncludeJQuery (wymagane przez wszystkie pozostałe), IncludeBootstrap, IncludeViewerScripts (rdzeń: docViewer.js + splitter + links), IncludeSearchScripts i IncludeSearchBar (ograniczone wyszukiwaniem), IncludeAnnotationScripts i IncludeAnnotationBar (ograniczone 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ą wspieraną metodą dostarczania zasobów przeglądarki. Aplikacje, które skopiowały docViewer.js, documentLinks.js i docViewer.UI.js do wwwroot, powinny usunąć te kopie, gdy strona zostanie wyrenderowana przy użyciu wygenerowanych tagów.