Tutoriál: Otevření dokumentů pomocí injektovaného Doconut Viewer v .NET 8

Úvod

Starší příklady Doconut mohou vytvářet Viewer přímo s argumenty cache, HTTP-context a license-path. To není aktuální integrační model .NET 8. AddDoconut() registruje Viewer pomocí dependency injection a koncové body aplikace získávají službu místo volání konstruktoru.

Abstraktní serverové komponenty předávající neprůhledný token relace povrchu pro prohlížení dokumentu

Tento tutoriál následuje aktuální tok požadavků: zaregistrujte služby a middleware, vytvořte vložené zdroje prohlížeče, otevřete dokument pomocí OpenDocumentAsync, vraťte neprůhledný token relace a předáte tento token widgetu prohlížeče.

1. Instalace a registrace Doconut

Přidejte balíček .NET 8:

dotnet add package Doconut.NET8

Zaregistrujte Doconut a služby ASP.NET session:

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

builder.Services.AddSession();

Propojte middleware ve požadovaném pořadí. Middleware pro zdroje musí běžet před terminálním middlewarem pro dokumenty:

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

MiddlewarePath koordinuje konfiguraci, ale sám o sobě nevytváří větev ASP.NET. Mapovaná cesta /doconut musí odpovídat BasePath widgetu.

2. Přidání povrchu prohlížeče a zdrojů

Doconut prohlížeč v prohlížeči je jQuery plugin. V Razor stránce injektujte Viewer a požádejte jej, aby vytvořil značky zdrojů ve správném pořadí závislostí:

@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>

Inicializujte widget s cestami, které odpovídají registraci na serveru:

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);
    }
});

Velikost písmen u možností je významná. Používejte názvy zobrazené nainstalovanou verzí místo jejich normalizace na jednotný styl.

3. Injektování Viewer a otevření dokumentu

Viewer je registrován jako přechodná služba. Získejte jej pomocí injekce v koncovém bodě, konstruktorové injekce nebo ekvivalentního mechanismu ve vaší aplikaci ASP.NET Core.

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 });
});

Pro nahrání poskytněte stream a FileInfo, jehož přípona identifikuje zdrojový formát:

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 });
});

Ověřte velikost nahrávaného souboru, příponu i autorizaci před otevřením obsahu poskytnutého uživatelem. Nepřevádějte odeslaný název souboru na cestu na serveru.

4. Předání tokenu widgetu

Načtěte koncový bod pro otevření a předáte získaný token metodě 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));

Token považujte za přístupové oprávnění pro živou relaci dokumentu:

Nezaznamenávejte ani neukládejte jej.
Vraťte jej pouze autorizovanému klientovi.
Nezveřejňujte cestu ke zdrojovému souboru.
Znovu otevřete dokument, když relace vyprší.
Ukončete relaci, když dokument již není potřeba.

5. Úmyslné ukončení relací na serveru

Klientský kód může zavolat objViewer.Close(), když uživatel opustí prohlížeč. Serverové workflow může také explicitně odvolat známý token:

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

Explicitní uzavření je zvláště užitečné u velkých dokumentů. Vypršení relace zůstává záložním řešením, nikoli náhradou za předvídatelnou správu životního cyklu aplikace.

6. Přidání volitelných modulů až po fungování jádra

Vyhledávání a anotace se připojují ke stejnému inicializovanému prohlížeči. Přidejte jejich CSS, skripty, mounty, licenční kontroly a životní cyklus pouze po úspěšném dokončení základního toku:

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

Toto pořadí udržuje selhání jádra renderování oddělená od konfigurace volitelných modulů.

Běžné chyby při migraci

Starý nebo nesprávný vzor	Aktuální směr .NET 8
`new Viewer(cache, accessor, licensePath)`	Injektujte `Viewer` po `AddDoconut()`
Static license-loading calls in request code	Nakonfigurujte vstup licence v `AddDoconut()`
Synchronous `OpenDocument(...)` examples	Použijte `OpenDocumentAsync(...)`
An external or invented viewer CDN	Vytvořte vložené zdroje pomocí `ReferenceCss` a `ReferenceScripts`
A generic JavaScript `init()` API	Inicializujte `$('#div_ctlDoc').docViewer(...)`
Persisting the viewer token	Ukládejte ID svého dokumentu; token považujte za dočasný

Použijte oficiální dokumentaci Doconut a ověřte příklady vůči nainstalované verzi balíčku, než je přizpůsobíte pro produkční kód.