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‑Dienst registriert und wird über Konstruktorinjektion aufgelöst — nie 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 per‑Request‑Zustand und implementiert bewusst nicht IDisposable: Dokumentensitzungen leben unabhängig im Sitzungs‑Cache, sodass das Entsorgen des Dienstes niemals ein geöffnetes Dokument schließen könnte (siehe Kernkonzepte → 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.

// Einfach öffnen
string token = await viewer.OpenDocumentAsync(path);

// Mit pro-Format-Konfiguration und Optionen
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Aus einem 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. Das Ablaufdatum des Kalenders ohne Ablehnungsnachricht führt zu einer Wasserzeichen‑Darstellung statt zu einer Ausnahme.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — der Dateiinhalte ist beschädigt oder stimmt nicht mit seiner Erweiterung überein.

CloseDocument

void CloseDocument(string token)

Entfernt die Sitzung aus dem Cache (der Dokument‑Engine wird sofort entsorgt), löscht den Sicherheitsmarker und widerruft die Zugriffsberechtigung. Optional — Sliding‑Expiration 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.

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Gibt die Arbeitsblattnamen einer offenen Tabellenkalkulation in Arbeitsbuchreihenfolge zurück oder eine leere Liste, wenn das geöffnete Dokument keine Tabellenkalkulation ist.

Nur gerenderte Arbeitsblätter werden aufgelistet: versteckte und leere Arbeitsblätter werden ausgeschlossen, und wenn ExcelConfig.SheetNames das Rendering einschränkt, erscheinen nur diese Arbeitsblätter. Ein Arbeitsblatt ist nicht immer eine Seite — ein sehr großes wird über mehrere Seiten gerendert. Wirft eine Ausnahme, wenn das Token unbekannt oder abgelaufen ist.

Hinzugefügt in 26.9.0.

Fähigkeitskennzeichen

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

DocOptions

Optionen pro Öffnung, formatunabhängig (Namespace Doconut):

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

Benutzerdefiniertes Wasserzeichen

DocOptions.Watermark verwendet sechs durch Tilden getrennte Felder. Ein optional führendes ^ fordert das All‑Corners‑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 sichtbare Invalid Watermark‑Fallback des SDK ersetzt, anstatt stillschweigend zu verschwinden.

Lizenzentscheidung

Die gleiche Entscheidung wird auf bereitgestellte Seitenbilder und Anmerkungs‑Exporte angewendet. Animierte GIF‑Ausgabe wird Bild für Bild gestempelt. Ein benutzerdefiniertes Wasserzeichen ist daher ein lizenziertes Anwendungs‑Feature, nicht ein Mittel, um das Evaluierungswasserzeichen zu ersetzen oder zu unterdrücken.

Annotations-API

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

Jeder dieser nimmt das Sitzungs‑Token. Die session‑freie GetAnnotationManager(pageWidth, pageHeight)‑Form 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 Metadaten‑Reader wird nur als .NET‑8‑Build ausgeliefert. Sie gibt null für DICOM‑ und Nicht‑DICOM‑Sitzungen zurück; in einer DICOM‑Sitzung schreibt sie außerdem eine einmalige Warnung, die die Plattform‑Einschränkung erklärt. Seiten-, Frame‑ und Animations‑Rendering bleiben unterstützt.

Ressourcen‑Hilfsprogramme — 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 Funktionen wie Suche und Anmerkungen werden nur dann ausgegeben, wenn die Lizenz sie aktiviert, wodurch die Client‑UI mit dem Serververhalten konsistent bleibt.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + Betrachter + Suche + Annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig Flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (durch Suche gesperrt), IncludeAnnotationCss (durch Anmerkungen gesperrt).

ScriptConfig Flags: IncludeJQuery (von allen anderen benötigt), IncludeBootstrap, IncludeViewerScripts (Kern: docViewer.js + Splitter + Links), IncludeSearchScripts und IncludeSearchBar (durch Suche gesperrt), IncludeAnnotationScripts und IncludeAnnotationBar (durch Anmerkungen gesperrt).

@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 Hilfsprogramme sind der unterstützte 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 aus den ausgegebenen Tags gerendert wird.