Betrachter

Viewer (Namespace Doconut) ist der öffentliche Einstiegspunkt zum Öffnen von Dokumenten aus Razor‑Seiten, MVC‑Controllern, Blazor‑Komponenten oder Minimal‑APIs. Es ist sealed, von AddDoconut() als transient Service registriert und wird über Konstruktorinjektion aufgelöst – niemals direkt konstruieren.

Viewer hält keinen per‑Request‑Zustand und implementiert absichtlich nicht IDisposable: Dokumenten‑Sitzungen leben unabhängig im Sitzungs‑Cache, sodass das Entsorgen des Services niemals ein offenes Dokument schließen könnte (siehe Kernkonzepte → Wie der Viewer funktioniert).

OpenDocumentAsync

Öffnet ein Dokument und gibt das Sitzungstoken zurück, das das Client‑Widget für alle nachfolgenden Anfragen verwendet.

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

Ausnahmen, die zu behandeln sind:

• LicenseException — eine gefundene Lizenz wird abgelehnt (die Meldung enthält den Ablehnungsgrund) oder das Format benötigt eine Plugin‑Fähigkeit, die nicht mehr gewährt ist. Ablauf des Kalenders ohne Ablehnungsnachricht führt zu einer wasserzeichenbasierten Darstellung anstelle einer Ausnahme.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — die Datei ist beschädigt oder stimmt nicht mit ihrer Erweiterung überein.

CloseDocument

void CloseDocument(string token)

Entfernt die Sitzung aus dem Cache (die Dokument‑Engine wird sofort entsorgt), löscht den Sicherheitsmarker und widerruft die Zugriffsberechtigung. Optional — das gleitende Verfalls‑Verfahren führt dieselbe Bereinigung durch — wird jedoch für große Dokumente empfohlen.

GetPageCount

int GetPageCount(string token)

Gesamtseitenzahl der offenen Sitzung. Wirft eine Ausnahme, wenn das Token unbekannt oder abgelaufen ist.

DocOptions

Pro‑Öffnung, formatunabhängige Optionen (Namespace Doconut):

Die Klasse stellt außerdem spezialisierte Eigenschaften bereit, die bewusst außerhalb des normalen Single‑Host‑Betrachtungs‑Flows liegen:

Custom watermark

DocOptions.Watermark verwendet sechs durch Tilde getrennte Felder. Ein optionales führendes ^ fordert das All‑Ecken‑Layout an:

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

Der Parser erwartet exakt sechs Felder nach dem optionalen ^. Eine ungültige Definition wird durch das im SDK sichtbare Invalid Watermark‑Fallback ersetzt, anstatt still zu verschwinden.

Lizenzentscheidung

Der gleiche Entscheidungs‑Mechanismus wird auf bereitgestellte Seitenbilder und Annotations‑Exporte angewendet. Animierte GIF‑Ausgabe wird Bild für Bild gestempelt. Ein benutzerdefiniertes Wasserzeichen ist daher ein lizenziertes Anwendungs‑Feature und keine Möglichkeit, das Evaluations‑Wasserzeichen zu ersetzen oder zu unterdrücken.

Annotations API

Serverseitiges Laden und Exportieren von Anmerkungen. Der vollständige Leitfaden befindet sich in Leitfäden → Anmerkungen; die Oberfläche ist:

DICOM metadata

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

Gibt DICOM‑Tag‑Metadaten für Sitzungen zurück, die über das DICOM‑Plugin geöffnet wurden; null für Nicht‑DICOM‑Dokumente.

Resource helpers — ReferenceCss / ReferenceScripts

Gibt die <link>/<script>‑Tags für die eingebetteten Ressourcen aus, die von UseDoconutResources() bereitgestellt werden, in korrekter Abhängigkeitsreihenfolge. Bündel für lizenzgesteuerte Features wie Suche und Anmerkungen werden nur dann ausgegeben, wenn die Lizenz sie aktiviert, sodass die Client‑UI mit dem Server‑Verhalten konsistent bleibt.

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

CssConfig‑Flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search‑gated), IncludeAnnotationCss (annotation‑gated).

ScriptConfig‑Flags: IncludeJQuery (erforderlich für alle anderen), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts und IncludeSearchBar (search‑gated), IncludeAnnotationScripts und IncludeAnnotationBar (annotation‑gated).

@inject Doconut.Viewer Viewer

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