Betrachter

Viewer (Namespace Doconut) ist der öffentliche Einstiegspunkt zum Öffnen von Dokumenten aus MVC-Controllern, Web‑Forms‑Seiten und Handlern. Es ist ein transient Service, 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 Services auf – was dafür sorgt, dass migrierter Code aus dem klassischen Paket kompiliert bleibt. Vor Initialize wirft es InvalidOperationException.

Viewer hält keinen pro‑Request‑Dokumentstatus und implementiert absichtlich nicht IDisposable: Dokument‑Sitzungen existieren unabhängig davon, sodass das Entsorgen eines Viewer niemals ein offenes Dokument schließen könnte (siehe Wie der Viewer funktioniert).

OpenDocumentAsync

Öffnet ein Dokument und gibt das Sitzungs‑Token zurück, das das Widget für jede spätere Anforderung verwendet. Wenn UnsafeMode false ist (Standard), wird das Token der ASP.NET‑Sitzung der aktuellen Anforderung zugewiesen – rufe es aus einer Anforderung mit Sitzungsstatus auf (siehe Sitzungen & Sicherheit).

// Einfaches Ö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 (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 unterstützt 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 Konverter-Plugin.

CloseDocument

void CloseDocument(string token)

Entfernt die Sitzung (setzt 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.

Session queries

Jeder wirft eine Ausnahme, wenn das Token unbekannt oder abgelaufen ist.

DocOptions

Per-open, format-independent options (namespace Doconut):

Benutzerdefiniertes Wasserzeichen

DocOptions.Watermark akzeptiert sechs durch Tilde getrennte Felder. Ein optionales 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 genau sechs Felder nach dem optionalen ^. Eine ungültige Definition wird durch einen sichtbaren Invalid Watermark‑Text ersetzt, anstatt still zu verschwinden.

Lizenzentscheidung

Die gleiche Entscheidung gilt für ausgelieferte Seiten und für Anmerkungs‑Exporte. Ein benutzerdefiniertes Wasserzeichen ist eine Funktion einer lizenzierten Anwendung, nicht dazu gedacht, das Evaluationswasserzeichen zu ersetzen.

Annotations API

Serverseitiges Laden und Exportieren von Anmerkungen. Die Anleitung befindet sich unter 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

Geben Sie die <link> und <script> Tags für die Ressourcen aus, die das Ressourcenmodul unter DoconutOptions.ResourcesPath bereitstellt, in Abhängigkeitsreihenfolge. Die Dateien für lizenzabhängige 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 des ribbon init Codes
bool IsAnnotationEnabled { get; }

CssConfig Flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search‑gated), IncludeAnnotationCss (annotation‑gated).

ScriptConfig Flags: IncludeJQuery (erforderlich für alle anderen), IncludeBootstrap, IncludeViewerScripts (die Kern‑Viewer‑Skripte), IncludeSearchScripts und IncludeSearchBar (search‑gated), IncludeAnnotationScripts und IncludeAnnotationBar (annotation‑gated).

Beide geben HTML zurück: Schreiben Sie sie mit @Html.Raw(...) in MVC 5 (erzeugen Sie sie im Controller — Views haben kein @inject) oder <%= %> in Web Forms. Schnellstart zeigt beide.

RenderViewer

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). Schreiben Sie 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.

Webfarm

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. Senden Sie es an das Widget mit dem Token: objViewer.View(token, access).