Betrachter
Die Haupt-Dokumentbetrachterklasse
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 – 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 verschwunden; das Service‑Graph liefert diese Abhängigkeiten.
Viewer hält keinen per‑Anfrage‑Zustand und implementiert absichtlich nicht IDisposable: Dokumentensitzungen leben unabhängig im Sitzungs‑Cache, sodass das Entsorgen des Services niemals ein geöffnetes Dokument schließen könnte (siehe Core Concepts → How the Viewer Works).
OpenDocumentAsync
Öffnet ein Dokument und gibt das Sitzungstoken zurück, das das Client‑Widget für alle nachfolgenden Anfragen verwendet. Jeder Öffnungsvorgang ist asynchron – es gibt keinen synchronen OpenDocument.
| Überladung | Verwendung |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Öffnen von der Festplatte mit automatischer Format‑Erkennung und der Standardkonfiguration des Formats |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Sie benötigen formatbezogene Rendering‑Optionen (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Das Dokument ist keine Datei auf der Festplatte (Upload, Datenbank, Blob). fileInfo muss die korrekte Erweiterung tragen – sie steuert die Format‑Erkennung |
// 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 Dateiinhalt 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 – 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 InvalidOperationException (Document session not found. Please re-open document.), wenn das Token unbekannt oder abgelaufen ist, und ArgumentException für ein leeres Token.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)Die standardmäßig gerenderte Seitengröße des Dokuments bei 100 % Zoom – der Koordinatenraum für in Code erstellte Anmerkungen. page wird aus Kompatibilitätsgründen akzeptiert; das Ergebnis ist der Dokumentstandard. Wirft InvalidOperationException (Document session not found. Please re-open document.), wenn das Token unbekannt oder abgelaufen ist, und ArgumentException für ein leeres Token.
Arbeitsblattnamen abrufen
IReadOnlyList<string> GetWorksheetNames(string token)Gibt die Arbeitsblattnamen einer geöffneten Tabellenkalkulation in Arbeitsbuchreihenfolge zurück oder eine leere Liste, wenn das geöffnete Dokument keine Tabellenkalkulation ist.
Nur gerenderte Arbeitsblätter werden aufgelistet: ausgeblendete und leere Arbeitsblätter werden ausgeschlossen, und wenn ExcelConfig.SheetNames das Rendern einschränkt, erscheinen nur diese Arbeitsblätter. Ein Arbeitsblatt ist nicht immer eine Seite — ein sehr großes wird über mehrere Seiten gerendert. Wirft InvalidOperationException (Document session not found. Please re-open document.), wenn das Token unbekannt oder abgelaufen ist, und ArgumentException für ein leeres Token.
Hinzugefügt in 26.9.0.
Berechtigungs‑Flags
| Mitglied | Bedeutung |
|---|---|
bool IsSearchEnabled | Die aktuelle Lizenz gewährt Search |
bool IsAnnotationEnabled | Die aktuelle Lizenz gewährt Annotation |
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
Pro Öffnung, formatunabhängige Optionen (Namespace Doconut):
| Typ | Eigenschaft | Standard | Beschreibung |
|---|---|---|---|
string | Password | "" | Passwort für geschützte Dokumente (automatisch in die Formatkonfiguration kopiert). |
int | ImageResolution | 0 | Veraltet. Nur zur Kompatibilität beibehalten — setzen Sie stattdessen ImageResolution in der Formatkonfiguration. |
string | Watermark | "" | Benutzerdefinierter Wasserzeichen‑Text, der auf gerenderten Seiten gezeichnet wird. Formatzeichenfolge: "^Text~Color~FontSize~FontName~Opacity~Angle", z. B. "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Gleitende Sitzungsablaufzeit in Minuten. |
bool | IsSecured | true | Derzeit nicht durchgesetzt — reserviert. Die Tokenbindung wird global von DoconutOptions.UnsafeMode gesteuert (siehe Kernkonzepte → Sitzungen & Sicherheit). |
Die Klasse stellt außerdem spezialisierte Eigenschaften bereit, die bewusst außerhalb des normalen Single‑Host‑Anzeigestroms liegen:
| Typ | Eigenschaft | Standard | Beschreibung |
|---|---|---|---|
bool | IsWebFarm | false | Veraltet — hat keine Wirkung. Veröffentlichen Sie das Dokument mit DistributedDocumentPublisher.PublishAsync (oder IDistributedPublishQueue.EnqueueAsync) und setzen Sie stattdessen FileShareConfig.RootPath. Beachten Sie die Groß‑/Kleinschreibung — die vorherige Bibliothek schrieb dies als IsWebfarm. |
string | WebFarmPath | "" | Veraltet — hat keine Wirkung. Verwenden Sie FileShareConfig.RootPath, wie in Verteilte Bereitstellungen beschrieben. Früher geschrieben als WebfarmPath. |
bool | EditMode | false | Reserviert für einen separat verteilten Bearbeitungs‑Workflow; lassen Sie false für den Standard‑Viewer. |
Benutzerdefiniertes Wasserzeichen
DocOptions.Watermark verwendet sechs durch Tilden getrennte Felder. Ein optionales führendes ^ fordert das All‑Corners‑Layout an:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Feld | Beispiel | Bedeutung |
|---|---|---|
Führendes ^ | ^ | Optionales All‑Corners‑Layout. Ohne dieses wird die normale Wasserzeichenplatzierung verwendet. |
| Text | Confidential | Auf jeder Seite gerenderter Text. Er darf nicht leer sein. |
| Farbe | Red | Benannte Farbe, die von der Zeichenebene verstanden wird. |
| Schriftgröße | 24 | Schriftgröße; ungültige numerische Eingabe fällt auf den Standardrenderer zurück. |
| Schriftname | Verdana | Gewünschte Schriftfamilie. Stellen Sie sicher, dass sie in der Bereitstellungsumgebung installiert ist. |
| Deckkraft | 80 | Byte‑Wert von 0 bis 255. Er muss erfolgreich geparst werden. |
| Winkel | -45 | Rotationswinkel in Grad; ungültige numerische Eingabe fällt auf den Standard zurück. |
Der Parser erwartet genau sechs Felder nach dem optionalen ^. Eine ungültige Definition wird durch das sichtbare Invalid Watermark‑Fallback des SDK ersetzt, anstatt stillschweigend zu verschwinden.
Lizenzentscheidung
| Lizenzstatus | Benutzerdefinierter Wert angegeben | Gerendertes Ergebnis |
|---|---|---|
| Gültige bezahlte Viewer-Lizenz | Nein | Saubere Seite |
| Gültige bezahlte Viewer-Lizenz | Ja | Benutzerdefiniertes Wasserzeichen |
| Aktiver temporärer/Demo-Basis-Viewer | Nein | Saubere Basis-Viewer-Seite |
| Aktiver temporärer/Demo-Basis-Viewer | Ja | Benutzerdefiniertes Wasserzeichen, wenn der saubere Basis-Viewer-Pfad angewendet wird |
| Fehlende, abgelehnte, abgelaufene, falsche Version oder ungültige Domain-Lizenz | Beliebig | Durchsetzungs-/Evaluierungswasserzeichen; der benutzerdefinierte Wert überschreibt es nicht |
| Plugin-Rendering unter Evaluierungsregeln | Beliebig | Evaluierungswasserzeichen |
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, um das Evaluierungswasserzeichen zu ersetzen oder zu unterdrücken.
Annotations-API
Serverseitiges Laden und Exportieren von Anmerkungen. Die vollständige Anleitung befindet sich in Leitfäden → Annotations; die Oberfläche ist:
| Mitglied | Zweck |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Manager, gebunden an die Seitenabmessungen der offenen Sitzung |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Manager mit expliziten Seitenabmessungen |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Sitzungsunabhängiger Manager |
void LoadAnnotationData(string token, AnnotationManager manager) | Lädt in C# erstellte Anmerkungen in die Sitzung |
void LoadAnnotationData(string token, string annotationData) | Lädt Anmerkungen aus der codierten Seite/Base64‑Hülle, die von AnnotationManager.GetAnnotationData() zurückgegeben wird |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Lädt Anmerkungen aus XML |
XmlDocument GetAnnotationXML(string token) | Exportiert die Anmerkungen der Sitzung als XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF mit eingebrannten Anmerkungen |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Ein PNG pro Seite, Anmerkungen eingebrannt, geschrieben nach directoryPath (erstellt, falls nicht vorhanden); gibt die Anzahl der geschriebenen Bilder zurück |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP von pro Seite PNGs mit eingebrannten Anmerkungen |
Jeder dieser Vorgänge benötigt das Sitzungstoken. Die session‑freie
GetAnnotationManager(pageWidth, pageHeight)‑Form der vorherigen Bibliothek bleibt zum Erstellen von Anmerkungen
außerhalb einer Sitzung erhalten, 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 mit einem .NET 8‑Build ausgeliefert. Sie gibt null für DICOM und
Nicht‑DICOM‑Sitzungen zurück; in einer DICOM‑Sitzung schreibt sie zudem eine einmalige Warnung, die die
Plattform‑Einschränkung erklärt. Seiten-, Frame‑ und Animations‑Rendering bleiben unterstützt.
Ressourcen‑Hilfsprogramme — ReferenceCss / ReferenceScripts
Erzeuge die <link>/<script>‑Tags für die eingebetteten Ressourcen, die von UseDoconutResources() bereitgestellt werden, in korrekter Abhängigkeitsreihenfolge. Bündel für lizenzgesteuerte Funktionen wie Suche und Annotation werden nur dann ausgegeben, wenn die Lizenz sie aktiviert, sodass die Client‑UI mit dem Serververhalten konsistent bleibt.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + Viewer + Suche + Annotation
string ReferenceScripts(ScriptConfig? config = null)CssConfig Flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (nach Suche gesteuert), IncludeAnnotationCss (nach Annotation gesteuert).
ScriptConfig Flags: IncludeJQuery (von allen anderen benötigt), IncludeBootstrap, IncludeViewerScripts (Kern: docViewer.js + Splitter + Links), IncludeSearchScripts und IncludeSearchBar (nach Suche gesteuert), IncludeAnnotationScripts und IncludeAnnotationBar (nach Annotation gesteuert), EmitFeatureFlags (Standard true: schreibt außerdem ein Inline-window.Doconut.features = { search, annotation, editor }‑Skript; setze es auf false unter einer Content‑Security‑Policy, die Inline‑Skripte blockiert).
@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 erzeugten Tags gerendert wird.
War diese Seite hilfreich?