Tutorial: Öffnen von Dokumenten mit dem injizierten Doconut Viewer in .NET 8

Einführung

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

Abstrakte Serverkomponenten, die ein undurchsichtiges Session‑Token an eine Dokumentanzeigefläche übergeben

Dieses Tutorial folgt dem aktuellen Anforderungsablauf: Dienste und Middleware registrieren, die eingebetteten Viewer‑Ressourcen ausgeben, ein Dokument mit OpenDocumentAsync öffnen, ein undurchsichtiges Session‑Token zurückgeben und dieses Token an das Browser‑Widget übergeben.

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. Ressourcen‑Middleware muss vor der abschließenden 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 /doconut‑Pfad muss mit dem BasePath des Widgets übereinstimmen.

2. 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 Ressourcentags 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 bedeutend. 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 Service registriert. Lösen Sie ihn über Endpunkt‑Injection, Konstruktor‑Injection 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 Größe, Erweiterung und Autorisierung des Uploads, bevor Sie benutzerbereitgestellte Inhalte öffnen. Wandeln Sie den übermittelten Dateinamen nicht in einen Server‑Pfad um.

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 Bearer‑Anmeldeinformation für eine Live‑Dokument‑Session:

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

5. Serverseitige Sessions 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 Ablauf‑Verhalten der Session bleibt ein Rückfall, kein Ersatz für ein vorhersehbares Anwendungs‑Lebenszyklus‑Management.

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 Lifecycle‑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(...)`
Persistieren des Viewer‑Tokens	Persistiere deine Dokument‑ID; behandle das Token als temporär

Verwenden Sie die offizielle Doconut-Dokumentation und prüfen Sie die Beispiele anhand der installierten Paketversion, bevor Sie sie in Produktionscode übernehmen.