Snabbstart

Rendera ditt första dokument på några minuter

Denna genomgång tar en ASP.NET Core-app från en tom Program.cs till ett dokument som renderas i webbläsaren: serverregistrering, det kompletta Viewer‑paketet (Viewer‑verktygsfält, Viewer‑montering och valfria sök‑/annotationsband), resursreferenser, klientinitialisering, dokumentöppning och körning.

Värdprogrammet måste rikta in sig på en runtime som stödjer netstandard2.1 — .NET Core 3.0 eller senare.

Serverkonfiguration

AddDoconut() registrerar tjänsterna; UseDoconutResources() och UseDoconut() kopplar middleware. Resursanropet måste komma först. UseDoconut() svarar på varje begäran som når den, så montera den på sin egen gren med app.Map. Sessionsanropen krävs också — Doconuts standarddokumentssäkerhet validerar varje sidbegäran mot ASP.NET:s sessionsstatus. Sessionsstatus behöver en cache: AddDistributedMemoryCache() tillhandahåller en. En MVC‑ eller Razor Pages‑app registrerar den redan, men en minimal-API‑app gör det inte, och utan den stannar appen vid start med Unable to resolve service for type 'IDistributedCache'. Har du redan registrerat Doconut under Installation? Hoppa vidare till nästa avsnitt.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // sessionsstillstånd behöver en cache (MVC/Razor Pages lägger redan till en)
builder.Services.AddSession(); // Doconut dokumentsäkerhet bygger på ASP.NET sessionstillstånd

app.UseSession();          // anropa UseSession() innan UseDoconut()
app.UseDoconutResources(); // måste registreras innan UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Denna konfiguration behåller den historiska DocImage.axd‑förfrågningsformen och monterar dokument‑middleware på en matchande gren. Detta är upplägget att kopiera när du för vidare en befintlig .NET Standard‑applikation, eftersom klienten fortsätter att anropa samma URL som den alltid gjort:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // behåll Doconut's sessionskontroll aktiverad
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // sessionsstillstånd behöver en cache (MVC/Razor Pages lägger redan till en)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Krävs för multibyte‑kodningar i vissa dokumentformat.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // FÖRE dokumentgrenen
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() tar inga alternativ i denna version — allt har flyttats till AddDoconut(). MiddlewarePath är ett koordineringsvärde; det mappar inte en ASP.NET Core‑gren i sig. Med DocImage.axd‑grenen ovan använder klienten BasePath: '/'; med app.Map("/doconut", ...) från den minimala konfigurationen använder den BasePath: 'doconut'. ResourcesPath levererar det inbäddade paketet på /doconut-res, och widgetens bildresurs‑sökväg är därför ResPath: 'doconut-res/images'.

Lägg till visaren på en sida

Viewer är den nödvändiga kärnan på sidan. Dess renderingsyta använder två nästlade divs:

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

Behandla verktygsfältet, modulmonteringarna och Viewer‑ytan som en enda sidkomposition. Sök och Annotation injicerar sina inbäddade band i valfria monteringar, men dessa moduler är aldrig fristående: de fästs alltid på Viewer på samma sida.

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Visarnavigation, zoom, sökning och annoteringsknappar -->
</nav>

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

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

Referera till visningsresurserna

I en Razor‑vy avger den injicerade Viewer‑tjänsten visningens <link>‑ och <script>‑taggar i beroendeordning — widgeten är ett jQuery‑plugin, så jQuery måste laddas innan visnings‑skripten:

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 det kompletta Viewer‑paketet, begär Viewer‑ och modulresurserna tillsammans:

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 och IncludeViewerScripts är de obligatoriska kärnflaggorna. Publicera aldrig ett Search‑ eller Annotation‑Ribbon‑exempel utan dem, Viewer‑monteringen och en docViewer‑instans. ReferenceCss och ReferenceScripts utelämnar ett valfritt moduls resurser när den aktuella licensen inte ger den möjligheten; kärn‑Viewer startar ändå.

Dessa anrop ersätter handkopierade skriptfiler. Om applikationen fortfarande laddar sina egna docViewer.js, documentLinks.js eller docViewer.UI.js, ta bort dessa taggar när sidan fungerar med de utsända resurserna — se migrationsguiden.

Initiera visaren

Klient‑sidans widget är ett jQuery‑plugin. Detta är en minimal uppsättning av faktiska init‑alternativ (inte pseudokod):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // DocImage.axd-grenen; 'doconut' med app.Map("/doconut", ...)
    ResPath:    'doconut-res/images',
    onViewerReady: function () {
        // sidor är synliga; säkert att dölja en laddningsindikator här
    },
    // Skicka vidare annoteringslivscykelhändelser till den inbäddade ribbonen när den är närvarande.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Fyra detaljer avgör om den här sidan fungerar alls:

  • Callbacks är alternativ. onViewerReady, onViewerBusy, onCopy och onAutoLoadStatus skickas i options‑objektet. Den tidigare visaren härledde globala funktionsnamn från container‑id och anropade dem; den här gör det inte. En handler som bara deklareras som en global funktion körs aldrig, och inget rapporteras.
  • ResPath pekar på resursprefixet, inte applikationsroten. Med standard‑ResourcesPath är det värdet doconut-res/images. Om du ändrade ResourcesPath, använd ditt eget prefix istället. Ikonerna ligger en mapp under resursroten: med 'doconut-res' returnerar varje ikon 404 medan själva dokumentet fortfarande renderas.
  • BasePath har ingen inledande snedstreck förutom webbplats‑rotnodens värde '/'. 'doconut' begär /doconut/DocImage.axd; '/doconut' producerar //doconut/DocImage.axd, vilket webbläsaren tolkar som en begäran till en annan värd.
  • Behåll visaren, anropa sedan View separat. docViewer(...) returnerar objektet med Zoom, Next och FitType; View(...) returnerar något annat. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) renderar dokumentet, men misslyckas med objViewer.Zoom is not a function vid första verktygsfältsklicket.

Alla dessa misslyckas tyst — se Felsökning och migrationsguiden.

Alternativens versalisering är faktiskt blandad — showThumbs, autoLoad och pageZoom är camelCase, men FitType, BasePath och ResPath är PascalCase. Det finns ingen konsekvent regel; om du får versaliseringen fel så ignoreras alternativet tyst (widgeten återgår till sitt standardvärde istället för att kasta ett fel).

Sätt ihop det kompletta Viewer-paketet

En komplett viewer-sida installerar följande delar tillsammans:

Del av paketetKravHur den är ansluten
Viewer-resurser, montering och objViewerKrävsKärndokumentrenderare
Viewer-verktygsfältKrävs för en komplett sidaVärd-markup; knappar anropar samma objViewer
SökbandValfri, licensierad moduldoconutSearchBar(...).attach(objViewer)
AnnoteringsbandValfri, licensierad moduldoconutAnnotationBar(...).attach(objViewer)

Även om huvud-Viewer-verktygsfältet är värd-markup, installeras det tillsammans med Viewer och får aldrig dokumenteras som en isolerad kontroll. Detta håller dess layout, etiketter, ikoner och auktoriseringsregler under din applikations kontroll medan varje knapp styr samma Viewer-instans:

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>

Behåll denna initieringsordning:

  1. Generera CSS för Viewer och licensierade moduler.
  2. Rendera Viewer-verktygsfältet, Search/Annotation-monteringar och Viewer-monteringen tillsammans.
  3. Generera skript för Viewer och licensierade moduler.
  4. Läs in värdapplikationens egna verktygsfältshjälpskript.
  5. Initiera docViewer och behåll den resulterande objViewer.
  6. Initiera varje licensierad Search- eller Annotation-band.
  7. Anropa attach(objViewer) på varje band.
  8. Öppna dokumentet och behåll dess token för Viewer- och modulförfrågningar.

Server-sidiga skydd är viktiga: när en valfri funktionalitet är otillgänglig, genereras dess skript inte, så dess jQuery‑plug‑in‑funktion existerar inte.

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>

Båda inbäddade komponenterna genererar sin egen Ribbon‑DOM. Search innehåller Find-, Options- och Results‑grupper. Annotation innehåller sina författarverktyg, stilkontroller, spara‑åtgärder och valfria export-/bild‑åtgärder. Balkarna exponerar open(), close(), reset() och isOpen(); anropa alltid attach(objViewer) en gång efter att de skapats.

Exemplet ovan utelämnar valfria värd‑callback‑funktioner och Annotation‑export-/bild‑slutpunkter för att hålla uppstarten minimal. Se Sök och Annotationer för den kompletta funktionsspecifika konfigurationen, eller Anpassade teman för att styla eller ersätta det värdeägda Viewer‑verktygsfältet.

Öppna ett dokument

Serverdelen är en enda slutpunkt: den injicerade Viewer-tjänsten öppnar dokumentet och returnerar en sessions‑token. Öppning är asynkron i den här releasen.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token är opak — ge den till widgeten, logga eller spara den aldrig.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Klienten hämtar den token och överlämnar den till widgeten med objViewer.View(token):

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

Det finns inget att förbereda innan den första öppningen. Om du vidareför en applikation, ta bort alla InitCache()‑anrop och flaggan som skyddar dem — metoden finns inte längre.

Stäng dokumentet

Anropa objViewer.Close(true) när användaren lämnar visaren eller öppnar ett ersättningsdokument: den rensar widgeten och skickar en stängningsbegäran till servern. objViewer.Close() utan argument rensar endast widgeten. Vid serverstyrda arbetsflöden tar viewer.CloseDocument(token) omedelbart bort den cachade sessionen, avvecklar renderingsmotorn, raderar dess säkerhetsmarkör och återkallar token. Glidande utgång utför så småningom samma städning, men explicit stängning rekommenderas för stora dokument.

Den kompletta begäranflödet är:

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

Behandla token som en bärar‑behörighet: logga den aldrig, lagra den aldrig, överlämna den endast till widgeten. Den identifierar en aktiv dokumentsession på servern och upphör att fungera när sessionen löper ut — öppna dokumentet igen för att få en ny.

Kör det

Placera en PDF på wwwroot/files/Sample.pdf, kör dotnet run och öppna sidan som innehåller widgeten. Den första sidan renderas i visaren, med en miniatyrpanel till vänster. Om den inte gör det, se Felsökning.

Vad du får utan licens

En saknad licens kastar inte ett fel. Visaren renderar normalt, men varje sida har ett utvärderingsvattenmärke. Se Licensinställning för hur Doconut hittar en licens och vad som förändras när den gör det.

Var den här sidan hjälpsam?