Schnellstart

Rendern Sie Ihr erstes Dokument in wenigen Minuten

Dieses Tutorial führt eine ASP.NET Core‑App von einem leeren Program.cs zu einem im Browser gerenderten Dokument: Serverregistrierung, das komplette Viewer‑Paket (Viewer‑Toolbar, Viewer‑Mount und optionale Such‑/Annotations‑Bänder), Asset‑Referenzen, Client‑Initialisierung, Dokumentenöffnung und Ausführung.

Servereinrichtung

AddDoconut() registriert die Services; UseDoconutResources() und UseDoconut() verbinden die Middleware. Der Aufruf der Ressourcen muss zuerst erfolgen. UseDoconut() beantwortet jede Anfrage, die ihn erreicht, also binden Sie ihn mit app.Map auf einem eigenen Zweig ein. Die Sitzungsaufrufe sind ebenfalls erforderlich – Doconut's Standard‑Dokumentensicherheit prüft jede Seitenanfrage gegen den ASP.NET‑Sitzungsstatus. Der Sitzungsstatus benötigt einen Cache: AddDistributedMemoryCache() stellt einen bereit. Eine MVC‑ oder Razor‑Pages‑App registriert ihn bereits, aber eine Minimal‑API‑App nicht, und ohne ihn stoppt die App beim Start mit Unable to resolve service for type 'IDistributedCache'. Haben Sie Doconut bereits während der Installation registriert? Springen Sie zum nächsten Abschnitt.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // Der Sitzungszustand benötigt einen Cache (MVC/Razor Pages fügen bereits einen hinzu)
builder.Services.AddSession(); // Doconut-Dokumentsicherheit basiert auf dem ASP.NET-Sitzungszustand

app.UseSession();          // Rufen Sie UseSession() vor UseDoconut() auf
app.UseDoconutResources(); // Muss vor UseDoconut() registriert werden
app.Map("/doconut", branch => branch.UseDoconut());

Für ein produktionsähnliches Pfadlayout ordnen Sie die Dokument‑Middleware einem expliziten Zweig zu und halten die vier Pfadeinstellungen synchron:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

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

MiddlewarePath ist ein Koordinationswert; er mappt keinen ASP.NET Core‑Zweig allein. In diesem Beispiel mappt der Host /doconut, sodass der Client BasePath: 'doconut' verwendet. ResourcesPath liefert das eingebettete Bundle unter /doconut-res, und der Bild‑Ressourcenpfad des Widgets ist daher ResPath: 'doconut-res/images'. Schreiben Sie beide ohne führenden Schrägstrich: Der Viewer fügt selbst einen hinzu, sodass '/doconut' zu //doconut/DocImage.axd wird, was der Browser als Anfrage an einen Host namens doconut interpretiert, und der Viewer scheitert mit "The viewer handler could not be reached".

Viewer zur Seite hinzufügen

Der Viewer ist der erforderliche Kern der Seite. Seine Rendering‑Oberfläche verwendet zwei verschachtelte divs:

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

Behandeln Sie die Toolbar, Modul‑Mounts und die Viewer‑Oberfläche als eine Seitenkomposition. Suche und Annotation fügen ihre eingebetteten Bänder in optionale Mounts ein, aber diese Module stehen niemals eigenständig: Sie werden immer an den Viewer auf derselben Seite angehängt. Verwenden Sie diese Reihenfolge:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer-Navigation, Zoom, Suche und Annotations-Buttons -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

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

Viewer‑Assets referenzieren

In einer Razor‑View gibt der injizierte Viewer‑Service die <link>‑ und <script>‑Tags des Viewers in Abhängigkeitsreihenfolge aus – das Widget ist ein jQuery‑Plugin, daher muss jQuery vor den Viewer‑Skripten geladen werden:

html
@inject Doconut.Viewer Viewer

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

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

Für das komplette Viewer‑Paket fordern Sie den Viewer und die Modul‑Ressourcen gemeinsam an:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss  = true,
    IncludeViewerCss     = true,
    IncludeSearchCss     = true,
    IncludeAnnotationCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeBootstrap         = true,
    IncludeViewerScripts     = true,
    IncludeSearchScripts     = true,
    IncludeSearchBar         = true,
    IncludeAnnotationScripts = true,
    IncludeAnnotationBar     = true
}))

IncludeViewerCss und IncludeViewerScripts sind die obligatorischen Kern‑Flags. Veröffentlichen Sie niemals ein Such‑ oder Annotation‑Ribbon‑Beispiel ohne sie, den Viewer‑Mount und eine docViewer Instanz. ReferenceCss und ReferenceScripts lassen die Ressourcen eines optionalen Moduls weg, wenn die aktuelle Lizenz diese Fähigkeit nicht gewährt; der Kern‑Viewer startet dennoch.

Viewer initialisieren

Das clientseitige Widget ist ein jQuery‑Plugin. Dies ist ein minimaler Satz echter Initialisierungsoptionen (kein Pseudocode):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   'doconut',             // kein führender '/'
    ResPath:    'doconut-res/images',  // kein führender '/'
    onViewerReady: function () {
        // Seiten sind sichtbar; hier kann ein Lade-Spinner ausgeblendet werden
    },
    // Leite Annotations-Lebenszyklusereignisse an das eingebettete Ribbon weiter, wenn es vorhanden ist.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Die Schreibweise der Optionen ist tatsächlich gemischt — showThumbs, autoLoad und pageZoom sind camelCase, aber FitType, BasePath und ResPath sind PascalCase. Es gibt keine konsistente Regel; wird die Schreibweise falsch verwendet, wird die Option stillschweigend ignoriert (das Widget greift auf seine Vorgabe zurück, anstatt einen Fehler zu werfen).

Vier weitere Details führen zu einem Fehlschlag ohne Fehlermeldung:

  • BasePath hat keinen führenden Schrägstrich. 'doconut' fordert /doconut/DocImage.axd an; '/doconut' erzeugt //doconut/DocImage.axd, das der Browser als Anfrage an einen anderen Host interpretiert.
  • ResPath: 'doconut-res/images' — die Symbole befinden sich einen Ordner unterhalb der Ressourcenwurzel. Mit 'doconut-res' liefert jedes Symbol 404: keine Symbolleiste‑Glyphen und kein Ladekreisel, während das Dokument selbst weiterhin gerendert wird. Ein führender Schrägstrich bricht es auf dieselbe Weise wie BasePath.
  • Callbacks sind Optionen. onViewerReady, onError und der Rest gehen in das Objekt, das an docViewer(...) übergeben wird. Eine globale Funktion, die nach dem Viewer benannt ist, wie z. B. ctlDoc_ViewerReady, wird nie aufgerufen.
  • Behalten Sie den Viewer, und rufen Sie dann View separat auf. docViewer(...) gibt das Objekt mit Zoom, Next und FitType zurück; View(...) gibt etwas anderes zurück. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) rendert das Dokument, schlägt dann beim ersten Klick auf die Symbolleiste mit objViewer.Zoom is not a function fehl.

Das vollständige Viewer‑Paket zusammenstellen

Eine vollständige Viewer‑Seite installiert die folgenden Teile zusammen:

Teil des PaketsAnforderungWie es verbunden ist
Viewer‑Ressourcen, Einbindung und objViewerErforderlichKern‑Dokumenten‑Renderer
Viewer‑SymbolleisteErforderlich für eine vollständige SeiteHost‑Markup; Buttons rufen dasselbe objViewer auf
Such‑BandOptional, lizenziertes ModuldoconutSearchBar(...).attach(objViewer)
Annotations‑BandOptional, lizenziertes ModuldoconutAnnotationBar(...).attach(objViewer)

Obwohl die Haupt‑Viewer‑Symbolleiste Host‑Markup ist, wird sie zusammen mit dem Viewer installiert und darf niemals als isoliertes Steuerelement dokumentiert werden. Dadurch bleiben ihr Layout, ihre Beschriftungen, Symbole und Autorisierungsregeln unter der Kontrolle Ihrer Anwendung, während jeder Button dieselbe Viewer‑Instanz steuert:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
    <button type="button" onclick="objViewer.FitType('height')">Fit height</button>
    <button type="button" id="openSearch">Search</button>
    <button type="button" id="openAnnotations">Annotations</button>
</nav>

Dreh‑, Miniatur‑, Druck‑, Vollbild‑, Layout‑ und Button‑Zustands‑Hilfsfunktionen gehören in Ihr eigenes Symbolleisten‑Skript, das dasselbe objViewer aufruft. Laden Sie es nach Viewer.ReferenceScripts(...) und halten Sie es zusammen mit dessen <nav id="toolbar">‑Markup.

Behalten Sie diese Initialisierungsreihenfolge bei:

  1. Geben Sie CSS für den Viewer und lizenzierte Module aus.
  2. Rendern Sie die Viewer‑Symbolleiste, Such‑/Annotations‑Einbindungen und die Viewer‑Einbindung zusammen.
  3. Geben Sie Skripte für den Viewer und lizenzierte Module aus.
  4. Laden Sie das eigene Symbolleisten‑Hilfsskript der Host‑Anwendung.
  5. Initialisieren Sie docViewer und behalten Sie das resultierende objViewer.
  6. Initialisieren Sie jedes lizenzierte Such‑ oder Annotations‑Band.
  7. Rufen Sie attach(objViewer) für jedes Band auf.
  8. Öffnen Sie das Dokument und bewahren Sie dessen Token für Viewer‑ und Modul‑Anfragen auf.

In einer verteilten Bereitstellung gehören der zusätzliche access‑Anfragewert und die Einstellungen für asynchrones Render‑Retry zum Transport; sie ändern nicht, wie der Viewer, die Symbolleiste oder die Bänder zusammengebaut werden.

Die serverseitigen Schutzmechanismen sind wichtig: Wenn eine optionale Fähigkeit nicht verfügbar ist, wird ihr Skript nicht ausgegeben, sodass ihre jQuery‑Plug‑in‑Funktion nicht existiert.

html
<script>
    let token = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    annBar.attach(objViewer);
        </text>
    }

    document.getElementById('openSearch').addEventListener('click', () => {
        if (!searchBar) return;
        searchBar.isOpen() ? searchBar.close() : searchBar.open();
    });

    document.getElementById('openAnnotations').addEventListener('click', () => {
        if (!annBar) return;
        annBar.isOpen() ? annBar.close() : annBar.open();
    });
</script>

Beide eingebetteten Komponenten erzeugen ihr eigenes Ribbon‑DOM. Suche enthält Gruppen für Finden, Optionen und Ergebnisse. Annotation enthält seine Autorentools, Stil‑Steuerungen, Speicher‑Aktionen und optionale Export‑/Bild‑Aktionen. Die Leisten stellen open(), close(), reset() und isOpen() bereit; rufen Sie stets einmal attach(objViewer) nach deren Erstellung auf.

Das obige Beispiel lässt optionale Host‑Callbacks und Annotation‑Export‑/Bild‑Endpunkte weg, um den Start minimal zu halten. Siehe Suche und Annotationen für die vollständige funktionsspezifische Einrichtung, oder Benutzerdefinierte Themen, um die vom Host besessene Viewer‑Symbolleiste zu stylen oder zu ersetzen.

Dokument öffnen

Die Serverseite ist ein Endpunkt: Der injizierte Viewer Service öffnet das Dokument und gibt ein Sitzungstoken zurück.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Das Token ist undurchsichtig — übergebe es dem Widget, logge es nie und speichere es nicht.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Der Client holt dieses Token und übergibt es dem Widget mit objViewer.View(token):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

Dokument schließen

Rufen Sie objViewer.Close(true) auf, wenn der Benutzer den Viewer verlässt oder ein Ersatzdokument öffnet: Es leert das Widget und sendet eine Schließ‑Anfrage an den Server. objViewer.Close() ohne Argument löscht nur das Widget. Bei servergesteuerten Workflows entfernt viewer.CloseDocument(token) sofort die zwischengespeicherte Sitzung, gibt die Rendering‑Engine frei, löscht dessen Sicherheitsmarker und widerruft das Token. Das gleitende Ablaufdatum führt schließlich dieselbe Bereinigung durch, aber ein explizites Schließen wird für große Dokumente empfohlen.

Der vollständige Anforderungsablauf ist:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

Behandeln Sie das Token wie ein Bearer‑Credential: Loggen Sie es nie, speichern Sie es nie, geben Sie es nur an das Widget weiter. Es identifiziert eine aktive Dokumentsitzung auf dem Server und hört auf zu funktionieren, wenn diese Sitzung abläuft – öffnen Sie das Dokument erneut, um ein frisches Token zu erhalten.

Ausführen

Legen Sie ein PDF unter wwwroot/files/Sample.pdf ab, führen Sie dotnet run aus und öffnen Sie die Seite, die das Widget hostet. Die erste Seite wird im Viewer angezeigt, mit einer Miniaturansicht-Leiste links. Wenn dies nicht geschieht, siehe Fehlerbehebung.

Was Sie ohne Lizenz erhalten

Fehlende Lizenz führt nicht zu einem Fehler. Der Viewer rendert normal, aber jede Seite trägt ein Evaluations‑Wasserzeichen. Siehe Lizenz‑Einrichtung für Informationen, wie Doconut eine Lizenz findet und was sich ändert, sobald sie gefunden ist.

War diese Seite hilfreich?