Tutorial: Dokumente mit dem injizierten Doconut Viewer in .NET 8 öffnen

Einführung

Ältere Doconut-Beispiele können Viewer direkt mit Cache-, HTTP-Kontext- und Lizenzpfad-Argumenten konstruieren. Das ist nicht das aktuelle .NET 8-Integrationsmodell. AddDoconut() registriert Viewer mittels Dependency Injection, und Anwendungsendpunkte erhalten den Service, anstatt einen Konstruktor aufzurufen.

Dieses Tutorial folgt dem aktuellen Anforderungsablauf: Registrieren von Diensten und Middleware, Ausgeben der eingebetteten Viewer-Ressourcen, Öffnen eines Dokuments mit OpenDocumentAsync, Zurückgeben eines undurchsichtigen Session-Tokens und Weitergabe dieses Tokens an das Browser-Widget.

---

1. Doconut installieren und registrieren

Fügen Sie das .NET 8-Paket hinzu:

dotnet add package Doconut.NET8

Registrieren Sie Doconut und ASP.NET-Session-Dienste:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

Binden Sie die Middleware in der erforderlichen Reihenfolge ein. Die Ressourcen-Middleware muss vor der terminalen Dokument-Middleware ausgeführt werden:

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath koordiniert die Konfiguration, erstellt jedoch nicht eigenständig den ASP.NET-Zweig. Der zugeordnete Pfad /doconut muss mit dem BasePath des Widgets übereinstimmen.

2. Die Viewer-Oberfläche und Ressourcen hinzufügen

Der Doconut-Browser-Viewer ist ein jQuery-Plugin. In einer Razor-Seite injizieren Sie Viewer und lassen ihn die Ressourcen-Tags in Abhängigkeitsreihenfolge ausgeben:

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true
}))

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

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Initialisieren Sie das Widget mit Pfaden, die der Server-Registrierung entsprechen:

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Die Groß-/Kleinschreibung der Optionen ist wichtig. Verwenden Sie die von der installierten Version angezeigten Namen, anstatt sie zu einem einheitlichen Stil zu normalisieren.

3. Viewer injizieren und ein Dokument öffnen

Viewer ist als transiente Dienst registriert. Lösen Sie ihn über Endpunkt-Injektion, Konstruktor-Injektion oder die entsprechende Einrichtung in Ihrer ASP.NET Core-Anwendung auf.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

Für einen Upload stellen Sie einen Stream und ein FileInfo bereit, dessen Erweiterung das Quellformat identifiziert:

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

Validieren Sie Dateigröße, Erweiterung und Autorisierung vor dem Öffnen von benutzergenerierten Inhalten. Wandeln Sie den übermittelten Dateinamen nicht in einen Serverpfad um.

4. Das Token an das Widget übergeben

Rufen Sie den Öffnungs-Endpunkt ab und übergeben Sie das zurückgegebene Token an objViewer.View:

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

Behandeln Sie das Token als Berechtigungsnachweis für eine aktive Dokumentensitzung:

• Nicht protokollieren oder speichern.
• Nur an einen autorisierten Client zurückgeben.
• Den Quelldateipfad nicht offenlegen.
• Das Dokument erneut öffnen, wenn eine Sitzung abläuft.
• Die Sitzung schließen, wenn das Dokument nicht mehr benötigt wird.

5. Serverseitige Sitzungen bewusst schließen

Client-Code kann objViewer.Close() aufrufen, wenn der Benutzer den Viewer verlässt. Server-Workflows können ein bekanntes Token ebenfalls explizit widerrufen:

app.MapPost("/api/close", (string token, Viewer viewer) =>
{
    viewer.CloseDocument(token);
    return Results.NoContent();
});

Ein expliziter Abschluss ist besonders bei großen Dokumenten nützlich. Das Ablaufdatum der Sitzung bleibt ein Rückgriff, nicht ein Ersatz für eine vorhersehbare Anwendungslebenszyklusverwaltung.

6. Optionale Module erst hinzufügen, wenn der Kern funktioniert

Suche und Anmerkungen werden an denselben initialisierten Viewer angehängt. Fügen Sie deren CSS, Skripte, Mounts, Lizenzprüfungen und Lebenszyklus-Callbacks erst hinzu, wenn der Basisablauf erfolgreich ist:

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

Diese Reihenfolge hält Kern-Rendering-Fehler von der Konfiguration optionaler Module getrennt.

Häufige Migrationsfehler

Altes oder falsches Muster	Aktuelle .NET 8‑Richtung
new Viewer(cache, accessor, licensePath)	Injiziere Viewer nach AddDoconut()
Statische Lizenz‑Ladeaufrufe im Anforderungscode	Lizenz‑Eingabe in AddDoconut() konfigurieren
Synchronen OpenDocument(...)‑Beispiele	Verwende OpenDocumentAsync(...)
Ein externes oder erfundenes Viewer‑CDN	Eingebettete Ressourcen mit ReferenceCss und ReferenceScripts ausgeben
Eine generische JavaScript init()‑API	Initialisiere $('#div_ctlDoc').docViewer(...)
Speichern des Viewer‑Tokens	Speichern Sie Ihre Dokument‑ID; behandeln Sie das Token als temporär

Verwenden Sie die offizielle Doconut‑Dokumentation und prüfen Sie die Beispiele anhand der installierten Paketversion, bevor Sie sie für Produktionscode anpassen.