Betrachter

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

Die vorherige .NET‑Standard‑Bibliothek stellte einen öffentlichen Konstruktor bereit, der den Memory‑Cache, den HTTP‑Context‑Accessor und einen oder mehrere Lizenzpfade entgegennahm. Dieser Konstruktor ist nicht mehr vorhanden; das Service‑Graph liefert diese Abhängigkeiten.

Viewer hält keinen pro‑Anfrage‑Zustand und implementiert bewusst nicht IDisposable: Dokument‑Sitzungen leben eigenständig im Sitzungs‑Cache, sodass das Entsorgen des Dienstes niemals ein geöffnetes Dokument schließen könnte (siehe Core Concepts → Wie der Viewer funktioniert).

OpenDocumentAsync

Öffnet ein Dokument und gibt das Sitzungs‑Token zurück, das das Client‑Widget für alle nachfolgenden Anfragen verwendet. Jeder Öffnungsvorgang ist asynchron – es gibt kein synchrones 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));

Ausnahmen zu behandeln:

• 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 wird. Ablauf des Kalenders ohne Ablehnungsnachricht führt zu einer Wasserzeichen‑Darstellung anstelle einer Ausnahme.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — der Dateiinhalt ist beschädigt oder stimmt nicht mit der Erweiterung überein.

CloseDocument

void CloseDocument(string token)

Entfernt die Sitzung aus dem Cache (der Dokument‑Engine wird sofort entsorgt), löscht das Sicherheits‑Marker und widerruft die Zugriffsberechtigung. Optional – die gleitende Ablaufzeit führt dieselbe Bereinigung durch – wird jedoch für große Dokumente empfohlen.

GetPageCount

int GetPageCount(string token)

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

Fähigkeits‑Flags

Verwenden Sie diese in einer Razor‑View, um ein lizenziertes Ribbon nur dann zu rendern, wenn der Server es tatsächlich bereitstellt — siehe Schnellstart.

DocOptions

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

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

Benutzerdefiniertes Wasserzeichen

DocOptions.Watermark verwendet sechs durch Tilde getrennte Felder. Ein optional führendes ^ fordert das Layout in allen Ecken 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 genau sechs Felder nach dem optionalen ^. Eine ungültige Definition wird durch das im SDK sichtbare Invalid Watermark‑Fallback ersetzt, anstatt still zu verschwinden.

Lizenzentscheidung

Die gleiche Entscheidung wird auf bereitgestellte Seitenbilder und Annotations‑Exporte angewendet. Die Ausgabe von animierten GIFs wird Bild für Bild gestempelt. Ein benutzerdefiniertes Wasserzeichen ist daher ein lizenziertes Anwendungsfeature und kein Mittel, das Evaluationswasserzeichen zu ersetzen oder zu unterdrücken.

Annotations‑API

Serverseitiges Laden und Exportieren von Anmerkungen. Die vollständige Anleitung befindet sich in Guides → Annotations; die Übersicht ist:

Jede dieser Methoden benötigt das Sitzungstoken. Die session‑freie Form GetAnnotationManager(pageWidth, pageHeight) der vorherigen Bibliothek bleibt erhalten, um Anmerkungen außerhalb einer Sitzung zu erstellen, aber das Laden erfordert weiterhin ein Token.

DICOM-Metadaten

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

Die Methode ist zur API‑Ausrichtung vorhanden, aber dieses Paket kann keine technischen DICOM‑Tags bereitstellen: Der Metadatenleser wird nur als .NET 8‑Build ausgeliefert. Sie gibt null für DICOM‑ und Nicht‑DICOM‑Sitzungen zurück; bei einer DICOM‑Sitzung schreibt sie zudem eine einmalige Warnung, die die Plattformbeschränkung erklärt. Seiten-, Frame‑ und Animations‑Rendering bleiben unterstützt.

Ressourcenhilfen — ReferenceCss / ReferenceScripts

Gibt die <link>‑/<script>‑Tags für die eingebetteten Ressourcen aus, die von UseDoconutResources() bereitgestellt werden, in korrekter Abhängigkeitsreihenfolge. Pakete für lizenzgesteuerte Funktionen wie Suche und Annotation werden nur dann ausgegeben, wenn die Lizenz sie aktiviert, wodurch die Client‑UI konsistent zum Serververhalten 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 (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and 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 }))

Diese Hilfsfunktionen sind der empfohlene Weg, um die Browser‑Ressourcen bereitzustellen. Anwendungen, die docViewer.js, documentLinks.js und docViewer.UI.js in wwwroot kopiert haben, sollten diese Kopien entfernen, sobald die Seite die von den ausgegebenen Tags geladenen Ressourcen rendert.