Snabbstart

Rendera ditt första dokument i MVC 5 eller Web Forms

Denna genomgång tar en ASP.NET-applikation på .NET Framework 4.7.2 från ett installerat paket till ett dokument som renderas i webbläsaren: Global.asax, en öppen slutpunkt, visningskomponentens resurser, widgeten och token som kopplar dem. Den förutsätter att Web.config-registreringarna från Installation är på plats — utan DocImage.axd-hanteraren och resursmodulen kan inget nedan nå servern.

Sätt ihop Doconut i Global.asax

En komplett Application_Start för en MVC 5-applikation:

csharp
// Global.asax.cs - komponera en gång per arbetsprocess, frigör vid avstängning.
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // en sida levereras endast till den session som öppnade dokumentet
    });

    // Endast MVC: håll de två Doconut-endpunkterna utanför routning.
    RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}
  • Encoding.RegisterProvider gör de äldre kodsidor som vissa dokumentformat använder tillgängliga för processen. Anropa den en gång, innan det första dokumentet öppnas.
  • UnsafeMode = false är standard, skriven explicit så att ingen av misstag ändrar den: DocImage.axd levererar en sida endast till den ASP.NET-session som öppnade dokumentet.
  • De två IgnoreRoute-anropen håller MVC-routing borta från DocImage.axd och /doconut-res/*, som hanteraren och modulen betjänar. En Web Forms-applikation har inga MVC-rutter och behöver ingen av dessa rader.
  • DoconutHost.Shutdown stoppar Doconut's bakgrundsarbete och frigör dess tjänster när applikationspoolen återcirkuleras. Det är säkert att anropa även om Initialize aldrig kördes.

Öppna ett dokument

Att öppna ett dokument returnerar en opak token. Widgeten skickar den tokenen med varje sidförfrågan.

I MVC 5 löser en controller‑åtgärd Viewer-tjänsten från DoconutHost.Services — MVC 5 har ingen konstruktor‑injektion för den:

csharp
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // Token är opak - ge den till visaren, logga eller spara den aldrig.
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

Dokumentet måste öppnas inom en begäran som har sessionsstate, eftersom öppnandet är det som ger den aktuella ASP.NET-sessionen åtkomst till dess sidor. MVC‑controllers och Web Forms‑sidor har sessionsstate som standard. En anpassad IHttpHandler har det inte, såvida den inte implementerar System.Web.SessionState.IRequiresSessionState. Öppna ett dokument från en handler utan den, och visaren visar "You Are Not Authorized To View This Page." på varje sida.

I Web Forms kan själva sidan öppna dokumentet i sin kod‑behind. OpenDocument är den synkrona formen av OpenDocumentAsync, avsedd för kod‑behind som inte använder asynkrona sidor:

csharp
// Default.aspx.cs
protected string Token;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}

Behandla tokenen som en bärar‑behörighet: logga den aldrig eller lagra den; ge den endast till widgeten. Den slutar fungera när dokumentsessionen löper ut — öppna dokumentet igen för att få en ny.

Referera till visningsresurserna

Viewer.ReferenceCss och Viewer.ReferenceScripts avger <link>‑ och <script>‑taggarna för de inbäddade resurserna, i beroendeordning, pekande på /doconut-res/. Widgeten är ett jQuery‑plugin, så jQuery kommer först.

MVC 5. Vy‑filer har ingen @inject, så producera taggarna i kontrollern och skicka dem vidare ViewBag:

csharp
public ActionResult Index()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
    {
        IncludeBootstrapCss = true,
        IncludeViewerCss    = true
    });
    ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
    {
        IncludeJQuery        = true,
        IncludeBootstrap     = true,
        IncludeViewerScripts = true
    });
    return View();
}
html
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

Behåll det arbetet i kontrollern. MVC 5 kompilerar vyer när de först levereras, och utan ett extra kompilatorpaket förstår den kompileraren bara C# 5 — ingen ?., ingen $"...", ingen nameof. En vy som använder dem kompileras utan problem i Visual Studio, och svarar sedan med en tom 500 i webbläsaren.

Web Forms. Exponera samma strängar från kod‑bakom och skriv dem med <%= %>:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss och IncludeViewerScripts är den obligatoriska kärnan. För att lägga till sök‑ och annoteringsflikar, sätt även IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts och IncludeAnnotationBar. Båda metoderna utelämnar en fliks filer när licensen inte ger den möjligheten; själva visaren startar ändå.

Lägg till visaren på en sida

Renderingsytan är två nästlade divs:

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

Ge den yttre div en riktig höjd — visaren fyller sin behållare och mäter den när den startar. Visaren ritar inte sin egen verktygsrad: GotoPage, Next, Zoom, FitType och resten är metoder som din sida kopplar till sina egna knappar, placerade bredvid visaren:

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.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>
</nav>

Initiera visaren och visa dokumentet

Efter visarskripten, skapa widgeten, och ge den sedan token:

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' betyder DocImage.axd i webbplatsens rot
    ResPath:    'doconut-res/images',  // ingen inledande '/'
    onViewerReady: function () {
        // sidor är synliga; dölj en laddningsindikator här
    },
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

fetch('/Document/Open', { method: 'POST' })
    .then(function (resp) { return resp.json(); })
    .then(function (data) { objViewer.View(data.token); });

I Web Forms, där sidan öppnade dokumentet själv, blir de sista tre raderna objViewer.View('<%= Token %>');.

Fyra detaljer här misslyckas utan felmeddelande:

  • BasePath: '/' adresserar DocImage.axd i webbplatsens rot. För en applikation i en virtuell katalog, använd dess namn utan snedstreck ('myapp' begär /myapp/DocImage.axd). Ett inledande snedstreck ('/myapp') producerar //myapp/DocImage.axd, vilket webbläsaren tolkar 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 verktygsikoner och ingen laddningsindikator, medan själva dokumentet fortfarande renderas. Ett inledande snedstreck bryter det på samma sätt som BasePath.
  • Callbacks är alternativ. onViewerReady, onError och resten går i objektet som skickas till docViewer(...). En global funktion namngiven efter visaren, såsom ctlDoc_ViewerReady, anropas aldrig.
  • Behåll visaren, och 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 det första klicket på verktygsraden.

Alternativnamn blandar camelCase (showThumbs, autoLoad, pageZoom) och PascalCase (FitType, BasePath, ResPath). Ett felstavat alternativ ignoreras, och widgeten använder sitt standardvärde.

Enradigt alternativ

För en sida som bara behöver visa ett dokument, utan någon egen verktygsrad, Viewer.RenderViewer skriver hela initieringsskriptet — docViewer(...) med BasePath: '/' och ResPath: 'doconut-res/images', sedan .View(token). Det finns endast i detta paket:

csharp
// Default.aspx.cs
protected string ViewerInit;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
    ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

Skicka en ViewerConfig som tredje argument för att ändra zoom, anpassning eller miniatyrpanelen. Eftersom det genererade skriptet inte behåller någon referens till visaren, använd den handskrivna initieringen ovan när din sida behöver sin egen verktygsrad.

Stäng dokumentet

Anropa objViewer.Close(true) när användaren lämnar visaren eller öppnar en ersättare: den rensar widgeten och skickar en stängningsbegäran till DocImage.axd. objViewer.Close() utan argument rensar endast widgeten. På servern tar viewer.CloseDocument(token) bort dokumentsessionen omedelbart, frigör dess renderingsresurser och återkallar sessionens åtkomst till dess sidor. Glidande utgång gör så småningom samma sak, men att explicit stänga stora dokument frigör minnet snabbare.

Kör den

Placera en PDF på ~/files/Sample.pdf, starta webbplatsen i IIS Express (F5 i Visual Studio) och öppna sidan som innehåller widgeten. Den första sidan renderas, med miniatyrer 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 var Doconut letar efter din licens.

Var den här sidan hjälpsam?