Betrachter
Die Hauptklasse für die Dokumentenanzeige
Viewer (Namespace Doconut) ist der öffentliche Einstiegspunkt zum Öffnen von Dokumenten aus MVC-Controllern, Web‑Forms‑Seiten und Handlern. Es ist ein transient Dienst, zusammengesetzt aus DoconutHost.Initialize; löse ihn dort auf, wo du ihn benutzt:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() funktioniert ebenfalls, sobald DoconutHost.Initialize ausgeführt wurde — es löst dieselben Dienste auf — was dafür sorgt, dass migrierter Code aus dem klassischen Paket kompiliert bleibt. Vor Initialize wirft es InvalidOperationException.
Viewer hält keinen pro‑Anfrage‑Dokumentzustand und implementiert bewusst nicht IDisposable: Dokumentsitzungen existieren unabhängig davon, sodass das Entsorgen eines Viewer niemals ein geöffnetes Dokument schließen könnte (siehe Wie der Viewer funktioniert).
OpenDocumentAsync
Öffnet ein Dokument und gibt das Sitzungstoken zurück, das das Widget für jede spätere Anforderung verwendet. Wenn UnsafeMode false ist (der Standard), wird das Token der ASP.NET‑Sitzung der aktuellen Anforderung zugewiesen – rufe es aus einer Anforderung mit Sitzungszustand auf (siehe Sitzungen & Sicherheit).
| Ü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 (ein Upload, eine Datenbank, ein Blob). fileInfo muss die richtige Erweiterung besitzen — sie wählt das Format aus |
// Einfach öffnen
string token = await viewer.OpenDocumentAsync(path);
// Mit formatbezogener Konfiguration und Optionen
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Aus einem Upload (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
await file.InputStream.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}Ausnahmen zu behandeln:
LicenseException— eine Lizenz wurde gefunden, aber abgelehnt (die Meldung enthält den Grund) oder das Format benötigt eine Plugin‑Fähigkeit, die die Lizenz nicht gewährt.FormatNotSupportedException— kein Viewer verarbeitet die Dateierweiterung.InvalidDataException— der Inhalt ist beschädigt oder stimmt nicht mit seiner Erweiterung überein.
OpenDocument (synchron)
Für Web‑Forms‑Code‑Behind und anderen Code, der keine asynchronen Seiten verwendet:
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)Jeder gibt das Token zurück und speichert es außerdem in viewer.Token. fileName muss die richtige Erweiterung besitzen. Diese Wrapper sind sicher von einer Web‑Forms‑Seite aus aufzurufen: Der Öffnungspfad wird niemals im ASP.NET‑Anforderungskontext fortgesetzt, sodass das Warten darauf keinen Deadlock verursachen kann. Das gilt nicht für jede asynchrone Doconut‑API — siehe den Web‑Forms‑Abschnitt von Converter‑Plugin.
CloseDocument
void CloseDocument(string token)Entfernt die Sitzung (gibt die Dokument‑Engine sofort frei), entfernt die Berechtigung des Tokens aus der ASP.NET‑Sitzung der aktuellen Anforderung und widerruft das Token. Optional – die gleitende Ablaufzeit führt dieselbe Bereinigung durch – wird jedoch für große Dokumente empfohlen.
Sitzungsabfragen
| Mitglied | Rückgabewert |
|---|---|
int GetPageCount(string token) | Gesamtseiten des geöffneten Dokuments |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Standardgröße der gerenderten Seite bei 100 % Zoom – der Koordinatenraum für Annotationen, der im Code erstellt wird |
IReadOnlyList<string> GetWorksheetNames(string token) | Gerenderte Arbeitsblätter einer Tabellenkalkulation in Arbeitsbuchreihenfolge; für andere Dokumente leer |
Jeder wirft InvalidOperationException (Document session not found. Please re-open document.), wenn das Token unbekannt oder abgelaufen ist, und ArgumentException bei einem leeren Token.
DocOptionen
Optionen pro Öffnung, formatunabhängig (Namespace Doconut):
| Typ | Eigenschaft | Standard | Beschreibung |
|---|---|---|---|
string | Password | "" | Passwort für geschützte Dokumente (automatisch in die Formatkonfiguration kopiert). |
string | Watermark | "" | Benutzerdefinierter Wasserzeichen‑Text, der auf gerenderten Seiten gezeichnet wird – siehe unten. |
int | TimeOut | 60 | Gleitende Sitzungsablaufzeit, in Minuten. |
string | BrowserId | "" | Web‑Farms: der Browser, an den ein signiertes Ticket gebunden ist. Setzen Sie ihn mit DoconutFarmBinding.EnsureBrowserId (siehe Sitzungen & Sicherheit). |
string | UserId | "" | Web‑Farms: der angemeldete Benutzer, an den ein Ticket gebunden ist, von DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Veraltet. Setzen Sie stattdessen ImageResolution in der Formatkonfiguration. |
bool | IsSecured | true | Reserviert; nicht durchgesetzt. Zugriffskontrolle ist DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Beibehalten für Code, der aus dem klassischen Paket migriert wurde. Sie schalten den Farm‑Modus nicht ein – AddDoconutDistributed tut es. |
bool | EditMode | false | Reserviert für den separat verteilten Editor; lassen Sie false. |
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~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Feld | Beispiel | Bedeutung |
|---|---|---|
Leading ^ | ^ | Optionales All‑Corners‑Layout. Ohne dieses wird die normale Platzierung verwendet. |
| Text | Confidential | Auf jeder Seite gezeichneter Text. Er darf nicht leer sein. |
| Color | Red | Eine benannte Farbe. |
| FontSize | 24 | Schriftgröße; ungültige numerische Eingabe fällt auf den Standard zurück. |
| FontName | Verdana | Schriftfamilie. Sie muss auf dem Server installiert sein – Windows Server hat weniger Schriftarten als ein Desktop. |
| Opacity | 80 | 0 bis 255. Sie muss geparst werden. |
| Angle | -45 | Drehung 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 einen sichtbaren Invalid Watermark‑Text ersetzt, anstatt still zu verschwinden.
Lizenzentscheidung
| Lizenzstatus | Benutzerdefinierter Wert angegeben | Gerendertes Ergebnis |
|---|---|---|
| Gültige kostenpflichtige Viewer‑Lizenz | Nein | Leere Seite |
| Gültige kostenpflichtige Viewer‑Lizenz | Ja | Benutzerdefiniertes Wasserzeichen |
| Aktive temporäre/Demo‑Lizenz | Nein | Leere Seite |
| Aktive temporäre/Demo‑Lizenz | Ja | Benutzerdefiniertes Wasserzeichen |
| Fehlende, abgelehnte, abgelaufene, falsche Version oder ungültige Domain‑Lizenz | Beide | Evaluierungswasserzeichen; der benutzerdefinierte Wert ersetzt es nicht |
Anmerkungen-API
Serverseitiges Laden und Exportieren von Anmerkungen. Die Anleitung befindet sich in Anmerkungen.
| Member | Purpose |
|---|---|
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 den codierten 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 fehlend); gibt die Anzahl der geschriebenen Bilder zurück |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP von PNGs pro Seite mit eingebrannten Anmerkungen |
DICOM-Metadaten
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)In diesem Paket gibt es immer null zurück, und die Metadaten‑Anfrage des Widgets liefert 501 Not Implemented: Das Auslesen von DICOM‑Tags ist im .NET Framework nicht verfügbar. DICOM Rendering — Seiten, Frames und Animation — funktioniert. Siehe DICOM‑Plugin.
Ressourcen‑Hilfsprogramme — ReferenceCss / ReferenceScripts
Gibt die <link>‑ und <script>‑Tags für die Ressourcen aus, die das Ressourcenmodul unter DoconutOptions.ResourcesPath bereitstellt, in Abhängigkeitsreihenfolge. Die Dateien für lizenzgesteuerte Funktionen (Search, Annotation) werden nur ausgegeben, wenn die Lizenz sie gewährt.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // Lizenzstatus, zum Schützen von ribbon init code
bool IsAnnotationEnabled { get; }CssConfig Flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).
ScriptConfig Flags: IncludeJQuery (von allen anderen benötigt), IncludeBootstrap, IncludeViewerScripts (die Kern‑Viewer‑Skripte), IncludeSearchScripts und IncludeSearchBar (search-gated), IncludeAnnotationScripts und IncludeAnnotationBar (annotation-gated), 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).
Beide geben HTML zurück: Schreibe sie mit @Html.Raw(...) in MVC 5 (erzeuge sie im Controller — Views haben kein @inject) oder <%= %> in Web Forms. Schnellstart zeigt beide.
RenderViewer (Ansicht rendern)
string RenderViewer(string elementId, string token, ViewerConfig? config = null)Gibt einen <script>‑Block zurück, der das Widget auf dem Element mit der ID elementId initialisiert und das Dokument anzeigt: docViewer({...}), erstellt aus dem ViewerConfig (Standard: BasePath: '/', ResPath: 'doconut-res/images'), dann .View(token). Schreibe ihn nach den Viewer‑Skripten. Das erzeugte Skript hält keine Referenz auf das Viewer‑Objekt, sodass eine Seite mit eigener Symbolleiste das Widget manuell initialisieren sollte. Siehe ViewerConfig.
Web‑Farm
string? AccessToken enthält das signierte Ticket, das bei der letzten Öffnung ausgestellt wurde, wenn der verteilte Modus aktiv ist und UnsafeMode ist false; es ist null auf einem einzelnen Server. Sende es an das Widget mit dem Token: objViewer.View(token, accessToken).
War diese Seite hilfreich?