Login   Company   1-781-743-2119    



PLEASE NOTE: this paper covers version 11.1 of our SDK. The original paper was for 11.0 and contains slightly different links for the diferent jQuery and jQueryUI resources required by 11.0/11.1

For the 11.0 version of this whitepaper, please see Q10475 - INFO: WebDocumentViewer Whitepaper - Getting Started With Web Viewing (11.0 Version)

When creating a new application using the WebDocumentViewer, whether you are migrating from our older web control (WebImageViewer / WebAnnotationViewer), or you are starting a new web project from scratch, there are a few steps you will need in order to get the project up and running.

We will use this document to discuss the requirements of using the WebDocumentViewer, and then walk through its creation, step by step.



WebDocumentViewer (and its companion Thumbnail Viewer, WebDocumentThumbnailer) is a modern HTML5 compatible web viewing control. It replaces WebAnnotationViewer (WebImageViewer) and WebDocumentThumbnailer replaces WebThumbnailViewer. These older controls are still supported, but are considered legacy controls with no new features being added.

As Microsoft further deprecates 'classic asp.net web apps', these legacy controls will become more and more difficult to maintain and support. Customers using WAV/WIV and WTV are encouraged to begin migration to WDV with or without WDT.

When creating a new application using the WebDocumentViewer, whether you are migrating from our older web control (WebImageViewer / WebAnnotationViewer), or you are starting a new web project from scratch, there are a few steps you will need in order to get the project up and running.

We will use this KB to discuss the requirements of using the WebDocumentViewer, and then walk through its creation, step by step.



Development Tools/Environment

This document and our SDK assume that you're a developer familiar with basic use of Visual Studio, IIS Express or IIS, and general web application development practices using MS Visual Studio 2013 or later. The samples will be using an HTML 5 approach in a non-MVC application targeting .NET framework 4.5.2 in a 64 bit application and using Visual Studio's built in IIS Express web server.

To ensure you're using the x64 version of IISExpress, in Visual Studio, go to Tools -> Options and then in the options menu, navigate to Projects and Solutions -> Web Projects and ensure the "Use the 64 bit version of IIS Express for web sites and projects" option is checked

NOTE: There is no major difference in using our control in MVC vs non-MVC apps - the only practical differences are that MVC likes to put scripts and css in specific locations and uses a slightly different means of interpolating paths in includes. All of this information should be able to be applied in an MVC app - just make sure you put all the markup on a single ASPX view.

ALSO NOTE: This document covers a standard ASP.NET web app, not ASP.NET Core. We do have support for ASP.NET Core targeting .NET framework (not pure .NET Core), but that is beyond the scope of this document (please see Q10467 - FAQ: Support for ASP.NET Core / .NET Core). The fundamental concepts of this document apply whether you are going to use ASP.NET or ASP.NET Core the client-side code is the same - the difference is in the handler (used for ASP.NET) versus the startup middleware (used by ASP.NET Core).

We will be providing examples in C#. Our SDK works with VB.NET as well, but for the sake of simplicity any .NET code will be provided in C#. You can use a converter tool such as Telerik Code converter to convert examples to VB.NET.

.NET Framework

Currently, DotImage 11.1 maintains a minimum .NET Framework requirement of either 3.5 (using or .NET 3.5 DLLs) or 4.5.2 or higher (using our 4.5.2 DLLs). Please note that .NET 3.0 and lower are not supported in 11.0 and newer. Likewise, .NET 4.0, 4.5, and 4.5.1 are not supported in DotImage 11.0 and newer

If you have an existing app you want to add DotImage to that targets an unsupported .NET framework, you will need to update it.

It will be necessary to make sure that your application meets the minimum framework requirements. We have not seen any conflicts with using any higher frameworks, so there should be no restrictions in terms of which .NET framework version you use, so long as it meets those minimums.

The WebDocumentViewer also requires jQuery, jQuery UI and jQuery Easing libraries. Additionally, the Raphael.js library will be required if using annotations.

jQuery and other libraries

WebDocumentViewer (and WebDocumentThumbnailer) also requires jQuery, jQuery UI and jQuery Easing libraries. Additionally,the Raphael.js library will be required if using annotations.

Our SDK ships with the minimum version of all required libraries. On SDK installation, they are placed in:
C:\Program Files (x86)\Atalasoft\DotImage 11.1\bin\WebResources\WebDocViewer\

As of 11.1, these are:

SDK Requirements / Versions

A brief set of instructions for downloading our SDK and activating a license will be given, but the rest of the document assumes you've installed the latest DotImage SDK (currently as of January 2019)

We do provide NuGet packages for our components, but this example will assume you've installed and activated our SDK locally. If you wish to use NuGet with our SDK, please check out our NuGet tutorial. (Please note that as of this writing (September 2018) the NuGet tutorial is out of date.. there are outdated script links which will result in a non-working application.. Support recommends using the information in this WDV whitepaper (This current document and not the NuGet tutorial) for the time being.

If you're a licensed developer, or are actively evaluating our SDK and run into problems/questions, you are welcome to contact support. You can make a support case in writing at our support portal. You may also call in to support during our normal business hours Support Hours: M - F from 8AM - 5PM EDT (New York Time)
Call us: 1-781-743-2119



Web applications with WebDocumentViewer / WebDocumentThumbnailer have a lot of "moving parts" and troubleshooting can seem a daunting task.

There is a free third party tool that can greatly enhance troubleshooting and assist you in reporting issues to support

If you are having issues with WebDocumentViewer, problems related to the web components are best diagnosed by looking at a log of the network traffic. Most commonly a faulting application will clearly show a 500 internal server error being thrown and the full response body of that error will offer a great deal of insight into the root cause (licensing issues, and errors in the WebDocumentRequestHandler will most often show up in the 500 error response body)

We recommend Fiddler if you need to collect a log and report it to support.

Please download, install, and run Fiddler web logging

Use it to collect a log while you reproduce the issue, then save the log as a native .saz file and and attach it to your support case as a file attachment/ (please do not save as CSV or text log. The native SAZ file gives us much better access to the tools we need to help diagnose your issue)

PLEASE NOTE: you need to capture a session while NOT using SSL/HTTPS. Fiddler logs cannot see into HTTPS without enabling a special certificate which we do not recommend.. if your capture is of an HTTPS session we will not get useful diagnostic information from the log



If you have not done so already, please download the latest version of Atalasoft DotImage SDK

NOTE: The current version is as of the current version of this document (January 2019) updates of the SDK happen with regularity. We work hard not to make breaking changes so this guide should be compatible with future releases. We will update the specific technical details as needed as changes arise

If you have not done so, please log in or create an account with Atalasoft so that you can activate our SDK.

NOTE for IIS users: The licensing above should be sufficient if you're using the built in web server in Visual Studio (IIS Express.. which this document assumes you are doing) but if you are using a local copy of IIS, then the IIS process does not run as your user name so it will not pick up your licenses. You'll need to take the extra step of copying your licenses into the application bin directory.

Assuming you have an app named SimpleWDVTestApp hosted in IIS under:

Then you'd copy your licenses from:
C:\users\YOUR_USERNAME\AppData\Local\Atalasoft\DotImage 11.1\




We're going to be creating a very minimal WebDocumentViewer (WDV) based application. We will add a WebDocumentThumbnailer (WDT)at a later stage. It's just going to open a document for viewing and allow for annotation and saving using defaults as much as possible.

While this may seem not too useful, it's the fundamental minimum you need to get the WDV running. Don't worry, we will get fancier in a bit. For now, we're going to start with the basics.

The first step will be to open Visual Studio 2013. You can use later versions of Visual Studio, however for the purpose of this project, 2013 is the platform we will be following. From there, you will create a new ASP.Net web application. Lets also target .NET 4.5.2 as our target framework, since it is the minimum version.

Alright. If you've followed everything this far, you should have a ready-to-run application. Go ahead and have Visual studio build and run. If everyting worked out right, it should look like this:

Congratulations! you've built the most basic working WebDocumentViewer!



OK, so the interface is really minimal and all it does is opens a single document at startup. It has annotations available but no option to save your changes. It also (as currently configured) has no support for PDF (the base SDK support out of the box supports PNG, BMP, TIF, GIF, JPEG, and several others, but not PDF).

That's OK, we can make it better.

So, lets flesh this out.. we will start by showing you how to add support for saving, then we'll show you how to programmatically open an arbitrary file, and then we'll add support for viewing PDF in the viewer.

Add support for Saving

The WebDocumentViewer has "out of the box" saving capabilities, but the save button is hidden in our current app/view. This is because the default saving requires at a minimum that you specify a save folder in the configuration.

Thats it for basic saving. If you run your app again, you should now see a save option on the toolbar.. if you add some annotations to the document and then hit save.. it will save a copy to the Saved/ directory with the same name as the original and will save an xmp sidecar file with the annotations.

Look in Saved and you shoud see a DocCleanMultipage.tif and DocCleanMultipage.xmp file now in the Saved directory

This is the super basic out of the box saving.. We could have just included the savepath in the initial config and it would already have been there, but it's important to let you know that the save button does not show automatically unless that option is set. When we get to advanced functionality, we will revisit saving to do something slightly more useful.. like saving to arbitrary locations or even preparing a save to send to a database or web service.


Open Files Programmatically

This next upgrade, we will add buttons to open some additional files. We already had you copy some test files to SampleImages before. If you haven't done so, add a directory called SampleImages to the root of the project and add the files from SampleImages.zip to that directory.

For this example we are going to make super simple HTML buttons. You can use any valid means of triggering programmatically, using third-party controls etc.. the only key issue is that you must never cause / call a postback. The WebDocumentViewer is essentially a Single Page Application (SPA) pattern and works with asynchronous callbacks. Causing a postback (resubmitting/loading the page) completely starts over from scratch and loses all changes.

We will add a button to open a different document (Gettysburgaddress.tif) as well as one to open the document that we already have present (DocCleanMultipage.tif) so you can see the proper method to implement a programmatic OpenURL. Optionally, we will disable the initial document load so that your viewer loads empty and doesn't have any document until it's loaded.

The signature of the OpenUrl command is:

_viewer.openUrl(DocumentUrl, AnnotationsUrl, CallbackFunction);

A string containing the relative path (within the web app) of the document to open.

AnnotationUrl (optional)
A string containing the relative path (Within the web app) of the annotations file to open.

If this is left blank, then no annotations are opened and the current annotations (if any) are preserved. This can cause issues if you open a document with less pages in it than you have of annotations (you had a 3 page doc open with annotations on all pages then you openUrl(NewOnepageDoc);.. this would leave the 3 pages of annotations with the unreachable 2nd and 3rd pages hanging out awkwardly.

If this is set to an empty string ('') then it will tell the control to destroy any existing annotations (so load fresh without any annotations).

CallbackFunction (optional)
A JavaScript function that will be called after the openUrl is completed. This is useful for situations where you need to take some specific action ONLY AFTER the new document loads.. for instance, say you are going to load a 2 page doc and want it to open "to the last page"...

You can not do this:

	_viewer.showPage(1); // page indices are zero indexed so 1 is the second page

If you try, it will error because the openUrl does not hold execution.. so _viewer.showPage will call before the document is open and has the page..

Instead, you'd use the callback like this:

	_viewer.openUrl('folderFor/my2pageDoc.tif', null, function() {_viewer.showPage(1);});

Note that the null is required as a placeholder .. you must either provide an annotations url or give it null because the THIRD argument is the callback, not eh second.. if you wanted to open a new document and clear annotations too and then scroll to the second page, the code would be:

	viewer.openUrl('folderFor/my2pageDoc.tif', '', function() {_viewer.showPage(1);});

Now, calling raw JavaScript is not really "a thing" it's usually called as part of some action. Maybe you have a third party grid or tree control or maybe you have some other code entirely.. either way you normally would be binding to some kind of onclick action or other. So for this example we will make HTML buttons.

This is actually a good excuse to talk about postbacks. If you make an html button or (even worse) an ASP:Button, and do not take steps to prevent a callback, your button will break the viewer/ make it do undesirable things.

This is because the viewer is following an SPA pattern and uses asynchronous Ajax calls to the back end.. a postback completely destroys all data on the control as it requests a reload.

To avoid callbacks, we must ensure any onclick event is done correctly.. that it returns false (a signal to the browser to NOT do a postback)

So, to put this all together, lets add a button for each test file (modify the html form tag to add the buttons right above the viewer divs:

<form id="form1" runat="server">
	<input type="button" id="btn_open_DocCleanMultipage" value="Open DocCleanMultipage" 
	    onclick="_viewer.openUrl('SampleImages/DocCleanMultipage.tif', ''); return false;" />
	<input type="button" id="btn_open_GettysburgAddress" value="Open GettysburgAddress" 
	    onclick="_viewer.openUrl('SampleImages/GettysburgAddress.tif', ''); return false;" />
	<input type="button" id="btn_open_dcm" value="Open DCM (pdf)" 
	    onclick="_viewer.openUrl('SampleImages/DCM.pdf', ''); return false;" />
	<input type="button" id="btn_open_hamlet" value="Open Hamlet (pdf)" 
	    onclick="_viewer.openUrl('SampleImages/Hamlet.pdf', ''); return false;" />
	<div id="_toolbar1"></div>
	<div id="_containerViewer" style="width: 710px; height: 600px; display: inline-block;"></div>   

This will make your Default.axpx look a bit like this:

and when you run it you will have some (admittedly ugly, but functional) buttons at the top of the page..

Well, the first two work but when you try and open the PDFs the viewer will go blank... So that brings us to the final improvement for this app..

Add PDF support

PDF is a very common file format and DotImage has a lot of really awesome PDF related tools and features. However, PDF viewing is not part of the base SDK.. it requires an add-on license for our PdfReader component. It also requires that you explicitly add PDF support to applications you want to be able to view PDFs

You may have noticed in the earlier stages, we added references to several PDF related dlls (Atalasoft.dotImage.Pdf.dll, Atalasoft.dotImage.PdfDoc.Bridge.dll, Atalasoft.dotImage.PdfReader.dll, Atalasoft.PdfDoc.dll). We did so because the WebControls dll requires them as dependencies.. becuase these dlls are integral to support for text searching for PDFs .. an "out of the box" feature of the control we won't be directly covering in this paper.

So, first thing, if you have not added those references please revisit the earlier section on adding references to the dlls we need. This will assume you have either a valid license for our Pdf reader component or you have an active, valid evaluation license that includes the PdfIum license (in 11.0 and newer, your PdfReader addon license will create an Atalasoft.dotImage.PdfIum.lic file as this is our new pdf engine in 11.0 and newer)

Now we need to add support for PDF.. this will be the first actual server-side code we need to modify past the original creation of the WebDocViewerHandler.ashx.

The full updated handler will now look like this:

using System;
using System.IO;
using System.Web;
using Atalasoft.Imaging.Codec;
using Atalasoft.Imaging.Codec.Pdf;
using Atalasoft.Imaging.WebControls;

namespace SimpleWDVTestApp
    public class WebDocViewerHandler : WebDocumentRequestHandler
        static WebDocViewerHandler()
            RegisteredDecoders.Decoders.Add(new PdfDecoder() { Resolution = 200 });
        public WebDocViewerHandler()
        { }

Believe it or not, that's all it takes.. if you're licensed for PDF reader and have those dlls referenced and have this in your handler and run your app, the PDF open buttons should now work.




Up to this point, the whole setup has been bare minimum. This is intentional as we wanted to show you the minimum needed to just get WebDocumentViewer up and running and then add a bit of info for the most common first questions (how do I open other documents?, how do I save?, how do I add PDF support?).

There are MANY more things we could do from here, and in a future WDV whitepaper covering more advanced topics, we'll delve into those a bit more. However, many customers want /need a Thumbnail based viewer for their WDV.. they want a thumbnail control to let users see/scroll a quick high level presentation of their document and use it to trigger viewing of the selected page on the main big viewer.

So, we're going to start from scratch again to show you how to build an app using WebDocumentViewer (WDV) with WebDocumentThumbnailer (WDT). We won't be going quite as slowly (less screenshots) because most of this is review from the previous.. we will be concentrating here on some of the subtle changes needed to get that thumbnail viewer running and connected to the viewer.

Many of the advanced use cases that will be covered in more advanced papers will start from this base WDV with WDT sample app.

Alright. If you've followed everything this far, you should have a ready-to-run application. Go ahead and have Visual studio build and run. If everyting worked out right, it should look like this:

Congratulations! you've built the most basic working WebDocumentViewer With WebDocumentThumbnailer!

We've taken the liberty of enabling saving AND of enabling drag drop - so try this - go ahead and gran an image from the thumb viewer and drag it to a different position relative to other pages.. say take page 1 and move it below page 2... the thumbnail viewer will update, the main viewer will update, AND if you save.. the saved image will match the order in which you placed them in teh viewer!



If you notice, we didn't just drop in the buttons from our previous example. The openUrl works ALMOST the same but there's a key difference we wanted to highlight explicitly.. When using WDV with WDT, you do NOT openUrl on the _viewer (WDV) you must openUrl on the WDT (_thumbs)

You might have even noticed that we slipped something in there already - when we gave you the viewer initialization notice how the updated WDV initialization removed the documenturl and we added it instead to the _thumbs viewer? this was intentional.

So, knowing what you know now, it's really easy - we can add the same buttons from before and just change _viewer to _thumbs ...like this:

<form id="form1" runat="server">
    <input type="button" id="btn_open_DocCleanMultipage" value="Open DocCleanMultipage" 
        onclick="_thumbs.openUrl('SampleImages/DocCleanMultipage.tif', ''); return false;" />
	<input type="button" id="btn_open_GettysburgAddress" value="Open GettysburgAddress" 
	    onclick="_thumbs.openUrl('SampleImages/GettysburgAddress.tif', ''); return false;" />
	<input type="button" id="btn_open_dcm" value="Open DCM (pdf)" 
	    onclick="_thumbs.openUrl('SampleImages/DCM.pdf', ''); return false;" />
	<input type="button" id="btn_open_hamlet" value="Open Hamlet (pdf)" 
	    onclick="_thumbs.openUrl('SampleImages/Hamlet.pdf', ''); return false;" />
    <div style="width: 900px;">
        <div id="_toolbar1"></div>
        <div id="_containerThumbs" style="width: 180px; height: 600px; display: inline-block;"></div>
        <div id="_containerViewer" style="width: 710px; height: 600px; display: inline-block;"></div>


It is our hope that you've been following along with the tutorial and have successfully built your solution. However, if you've run into issues or if you want a working reference app, we've implemented both the SimpleWDVTestApp and SimpleWDVWDTTestApp for you to download and run if needed. They also make great test harnesses for any experimental WDV / WDT code you want to try out... letting you start from a known-working application.


In many respects we have barely even scratched the surface of the WebDocumentViewer and WebDocumentThumbnailer. This paper was meant as a very basic getting started that will serve you well as a step by step guide to just getting the viewer set up and working. Atalasoft support engineers use a very similar base "boilerplate" app that we used as our inspiration for this demo nearly every day .. as a quick test harness / repro base solution to quickly test customer cases/issues and to test out various coding ideas having to do with WDV/ WDT.

In order to keep this document to a manageable size, we will end here for now. There are plans in the works for more advanced tutorials.. all of those will focus on the starting apps we've done here.

If you're looking for a getting started for WingScan .. our Web Scanning SDK, please see Q10462 - INFO: WingScan Whitepaper - Getting Started with Web Scanning

v007a - 2019/05/23 - TD