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.
Serverinställning
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. Sessionanropen krävs också — Doconut:s standarddokumentssäkerhet validerar varje sidbegäran mot ASP.NET‑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 stoppar appen vid start med Unable to resolve service for type 'IDistributedCache'. Har du redan registrerat Doconut under Installation? Hoppa vidare till nästa avsnitt.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state behöver en cache (MVC/Razor Pages lägger redan till en)
builder.Services.AddSession(); // Doconut-dokumentsäkerhet bygger på ASP.NET session state
app.UseSession(); // anropa UseSession() innan UseDoconut()
app.UseDoconutResources(); // måste registreras innan UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());För en produktionsliknande sökvägslayout, mappa dokument‑middleware till en explicit gren och håll de fyra sökvägsinställningarna i linje:
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 är ett koordineringsvärde; det mappar inte en ASP.NET Core‑gren i sig. I det här exemplet mappar värden /doconut, så klienten använder BasePath: 'doconut'. ResourcesPath levererar det inbäddade paketet på /doconut-res, och widgetens bildresursväg är därför ResPath: 'doconut-res/images'. Skriv båda utan inledande snedstreck: visaren lägger till ett själv, så '/doconut' skulle bli //doconut/DocImage.axd, vilket webbläsaren läser som en begäran till en värd som heter doconut, och visaren misslyckas med "The viewer handler could not be reached".
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:
<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 monteringarna, men dessa moduler är aldrig fristående: de fäster alltid på Viewer på samma sida. Använd denna ordning:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer‑navigering, 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 visarens resurser
I en Razor‑vy injicerar den injicerade Viewer‑tjänsten visarens <link>‑ och <script>‑taggar i beroendeordning — widgeten är ett jQuery‑plugin, så jQuery måste laddas innan visarskripten:
@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.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ärnflaggan. Publicera aldrig ett exempel på sök‑ eller annotationsband 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å.
Initiera visaren
Klient‑sidans widget är ett jQuery‑plugin. Detta är en minimal uppsättning av faktiska initieringsalternativ (inte pseudokod):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // ingen inledande '/'
ResPath: 'doconut-res/images', // ingen inledande '/'
onViewerReady: function () {
// sidorna är synliga; säkert att dölja en laddningsindikator här
},
// Skicka vidare annoteringslivscykelhändelser till den inbäddade ribbon när den finns.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});Alternativens skiftning ä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 skiftningen fel så ignoreras alternativet tyst (widgeten återgår till sitt standardvärde istället för att kasta ett fel).
Fyra ytterligare detaljer misslyckas utan ett felmeddelande:
BasePathhar ingen inledande snedstreck.'doconut'begär/doconut/DocImage.axd;'/doconut'producerar//doconut/DocImage.axd, vilket webbläsaren läser som en begäran till en annan värd.ResPath: 'doconut-res/images'— ikonerna finns en mapp under resursroten. Med'doconut-res'returnerar varje ikon 404: inga verktygsfältssymboler och ingen laddningsspinner, medan själva dokumentet fortfarande renderas. Ett inledande snedstreck bryter det på samma sätt somBasePath.- Callback‑funktioner är alternativ.
onViewerReady,onErroroch resten går i objektet som skickas tilldocViewer(...). En global funktion namngiven efter visaren, såsomctlDoc_ViewerReady, anropas aldrig. - Behåll visaren, och anropa sedan
Viewseparat.docViewer(...)returnerar objektet medZoom,NextochFitType;View(...)returnerar något annat.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)renderar dokumentet, men misslyckas medobjViewer.Zoom is not a functionvid det första klicket på verktygsfältet.
Sätt ihop det kompletta Viewer‑paketet
En komplett visarsida installerar följande delar tillsammans:
| Del av paketet | Krav | Hur den är ansluten |
|---|---|---|
Viewer‑resurser, montering och objViewer | Krävs | Kärndokumentrenderare |
| Viewer‑verktygsfält | Krävs för en komplett sida | Värd‑markup; knappar anropar samma objViewer |
| Sök‑band | Valfri, licensierad modul | doconutSearchBar(...).attach(objViewer) |
| Annoterings‑band | Valfri, licensierad modul | doconutAnnotationBar(...).attach(objViewer) |
Även om huvud‑Viewer‑verktygsfältet är värd‑markup, installeras det tillsammans med Viewer och får aldrig dokumenteras som en fristående kontroll. Detta håller dess layout, etiketter, ikoner och behörighetsregler under din applikations kontroll medan varje knapp driver samma Viewer‑instans:
<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>Rotation, miniatyr, utskrift, helskärm, layout och knapp‑tillstånd‑hjälpare bör ligga i ditt eget verktygsfältsskript, som anropar samma objViewer. Läs in det efter Viewer.ReferenceScripts(...), och håll det tillsammans med dess <nav id="toolbar">‑markup.
Behåll denna initieringsordning:
- Generera CSS för Viewer och licensierade moduler.
- Rendera Viewer‑verktygsfältet, Search/Annotation‑monteringar och Viewer‑monteringen tillsammans.
- Generera skript för Viewer och licensierade moduler.
- Läs in värdapplikationens egna verktygsfältshjälpskript.
- Initiera
docVieweroch behåll den resulterandeobjViewer. - Initiera varje licensierad Search‑ eller Annotation‑band.
- Anropa
attach(objViewer)på varje band. - Öppna dokumentet och behåll dess token för Viewer‑ och modul‑förfrågningar.
I en distribuerad utrullning tillhör det extra access‑förfrågningsvärdet och asynkron‑render‑återförsöksinställningarna transporten; de förändrar inte hur Viewer, verktygsfältet eller banden sätts ihop.
Server‑sidans skydd är viktiga: när en valfri funktionalitet är otillgänglig, genereras inte dess skript, så dess jQuery‑plug‑in‑funktion existerar inte.
<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. Sök‑bandet innehåller Sök‑, Alternativ‑ och Resultat‑grupperna. Annoterings‑bandet 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 annoterings‑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
Server‑sidan är en enda slutpunkt: den injicerade Viewer‑tjänsten öppnar dokumentet och returnerar en sessionstoken.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// token är ogenomskinlig — 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):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Stäng dokumentet
Kalla på 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, frigör renderingsmotorn, tar bort 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.
Det fullständiga begäransflödet är:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentBehandla 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 slutar fungera när den 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ärderingsvattenstämpel. 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?