Tutoriál: Otevírání dokumentů s injektovaným 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() zaregistruje Viewer pomocí dependency injection a koncové body aplikace získají službu místo volání konstruktoru.

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

Tento tutoriál následuje aktuální tok požadavku: zaregistrovat služby a middleware, vygenerovat vložené zdroje vieweru, otevřít dokument pomocí OpenDocumentAsync, vrátit neprůhledný token relace a předat tento token widgetu v prohlížeči.

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 vyžadovaném pořadí. Middleware pro zdroje musí běžet před terminálním middlewarem dokumentu:

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

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

2. Přidání povrchu vieweru a zdrojů

Doconut prohlížeč v prohlížeči je jQuery plugin. V Razor stránce injektujte Viewer a požádejte jej, aby vygeneroval 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 do jednotného stylu.

3. Injekce Vieweru a otevření dokumentu

Viewer je registrován jako transientní služba. Získejte jej prostřednictvím 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í souboru poskytněte stream a FileInfo, jehož přípona určuje formát zdroje:

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 a oprávnění před otevřením obsahu poskytnutého uživatelem. Nepřevádějte předané jméno souboru na cestu na serveru.

4. Předání tokenu widgetu

Načtěte koncový bod pro otevření a předávejte 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é uzavření relací na serveru

Klientský kód může zavolat objViewer.Close(), když uživatel opustí viewer. 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 vieweru. Přidejte jejich CSS, skripty, montáže, licenční kontroly a životní cykly pouze poté, co základní tok uspěje:

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	Současný směr .NET 8
`new Viewer(cache, accessor, licensePath)`	Injektujte `Viewer` po `AddDoconut()`
Statické volání načítání licence v kódu požadavku	Nakonfigurujte vstup licence v `AddDoconut()`
Synchronní příklady `OpenDocument(...)`	Použijte `OpenDocumentAsync(...)`
Externí nebo vymyšlený CDN pro viewer	Vygenerujte vložené zdroje pomocí `ReferenceCss` a `ReferenceScripts`
Obecné JavaScriptové API `init()`	Inicializujte `$('#div_ctlDoc').docViewer(...)`
Ukládání tokenu vieweru	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.