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 Dienst registriert und wird über Konstruktorinjektion aufgelöst – niemals direkt konstruieren.

Viewer hält keinen per‑Anfrage‑Zustand und implementiert absichtlich nicht IDisposable: Dokumentensitzungen leben unabhängig im Sitzungs‑Cache, sodass das Entsorgen des Dienstes niemals ein offenes Dokument schließen kann (siehe Kernkonzepte → Wie der Betrachter funktioniert).

OpenDocumentAsync

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

ÜberladungVerwendung
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Öffnen von der Festplatte mit automatischer Format­erkennung und der Standard‑Konfiguration des Formats
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Sie benötigen format‑spezifische 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
csharp
// 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 wasserzeichenbasierten Darstellung anstelle einer Ausnahme.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — der Dateiinhalt ist beschädigt oder stimmt nicht mit seiner Erweiterung überein.

CloseDocument

text
void CloseDocument(string token)

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

GetPageCount

text
int GetPageCount(string token)

Gesamtseitenzahl 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

text
(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 im 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.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

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

Nur gerenderte Arbeitsblätter werden aufgelistet: versteckte 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 hinweg 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.

Fähigkeitskennzeichen

MitgliedBedeutung
bool IsSearchEnabledDie aktuelle Lizenz gewährt Search
bool IsAnnotationEnabledDie 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

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

TypEigenschaftStandardwertBeschreibung
stringPassword""Passwort für geschützte Dokumente (automatisch in die Formatkonfiguration kopiert).
intImageResolution0Veraltet. Nur zur Kompatibilität behalten — stattdessen ImageResolution in der Formatkonfiguration setzen.
stringWatermark""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".
intTimeOut60Gleitende Sitzungsablaufzeit in Minuten.
boolIsSecuredtrueDerzeit nicht durchgesetzt — reserviert. Token‑Binding 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‑Anzeigeablaufs liegen:

TypEigenschaftStandardwertBeschreibung
boolIsWebFarmfalseVeraltet — hat keine Wirkung. Veröffentlichen Sie das Dokument mit DistributedDocumentPublisher.PublishAsync (oder IDistributedPublishQueue.EnqueueAsync) und setzen Sie stattdessen FileShareConfig.RootPath.
stringWebFarmPath""Veraltet — hat keine Wirkung. Verwenden Sie stattdessen FileShareConfig.RootPath.
boolEditModefalseReserviert für den separat verteilten Editor‑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
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
FeldBeispielBedeutung
Führendes ^^Optionales All‑Corners‑Layout. Ohne dieses wird die normale Wasserzeichenplatzierung verwendet.
TextConfidentialAuf jeder Seite gerenderter Text. Er darf nicht leer sein.
FarbeRedBenannte Farbe, die von der Zeichenebene verstanden wird.
Schriftgröße24Schriftgröße; ungültige numerische Eingabe fällt auf den Standard des Renderers zurück.
SchriftnameVerdanaGewünschte Schriftfamilie. Stellen Sie sicher, dass sie in der Bereitstellungsumgebung installiert ist.
Deckkraft80Byte‑Wert von 0 bis 255. Er muss erfolgreich geparst werden.
Winkel-45Rotationswinkel in Grad; ungültige numerische Eingabe fällt auf den Standard zurück.

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

LizenzstatusBenutzerdefinierter Wert angegebenGerendertes Ergebnis
Gültige bezahlte Viewer‑LizenzNeinLeere Seite
Gültige bezahlte Viewer‑LizenzJaBenutzerdefiniertes Wasserzeichen
Aktiver temporärer/Demo‑Basis‑ViewerNeinLeere Basis‑Viewer‑Seite
Aktiver temporärer/Demo‑Basis‑ViewerJaBenutzerdefiniertes Wasserzeichen, wenn der Pfad des sauberen Basis‑Viewers gilt
Fehlende, abgelehnte, abgelaufene, falsche Version oder ungültige Domain‑LizenzBeliebigDurchsetzungs‑/Evaluationswasserzeichen; der benutzerdefinierte Wert überschreibt es nicht
Plugin‑Rendering unter EvaluationsregelnBeliebigEvaluationswasserzeichen

Die gleiche Entscheidung wird auf bereitgestellte Seitenbilder und Anmerkungs‑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 Oberfläche ist:

MemberZweck
AnnotationManager GetAnnotationManager(string token)Manager, der an die Seitenabmessungen der offenen Sitzung gebunden ist
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 dem codierten Seiten-/Base64‑Umschlag, der 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 mit pro Seite PNGs, in die Anmerkungen eingebrannt sind

DICOM-Metadaten

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

Die Methode ist aus Gründen der API‑Ausrichtung vorhanden, aber der .NET 6 DICOM‑Betrachter kann keine technischen Tags bereitstellen. Sie gibt null für DICOM- und Nicht‑DICOM‑Sitzungen zurück; bei einer DICOM‑Sitzung schreibt sie außerdem eine einmalige Warnung, die die Plattformbeschrä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 konsistent zum Serververhalten bleibt.

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

CssConfig‑Flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (suchgesteuert), IncludeAnnotationCss (anmerkungsgesteuert).

ScriptConfig‑Flags: IncludeJQuery (von allen anderen benötigt), IncludeBootstrap, IncludeViewerScripts (Kern: docViewer.js + Splitter + Links), IncludeSearchScripts und IncludeSearchBar (suchgesteuert), IncludeAnnotationScripts und IncludeAnnotationBar (anmerkungsgesteuert), 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).

html
@inject Doconut.Viewer Viewer

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

War diese Seite hilfreich?