Login   Company   1-781-743-2119    

ASP.NET CORE WDV WHITEPAPER

SEE ALSO

Before we get started, it's important to note that this document is focusing only on the aspects of getting started with WDV in the context of ASP.NET Core web applications. We will discuss the differences between WDV / WDT in ASP.NET Core and standard ASP.NET, but we won't go into strenuous details about WDV and some of the more advanced things you can do with it.

This is because there is very little functional difference between WDV/WDT in ASP.NET Core versus ASP.NET. Herein we hope to give you the fundamentals you need to operate within the ASP.NET Core paradigm, and give you the tools to understand how to hook into the server side events and add server side code, but once you understand how to hook in / the analogy to what we call the "handler" in the ASP.NET version, Any of the implementation details are pretty much the same.

All of this means that you may want to have a look at our related papers/articles:

GETTING STARTED

When creating a new application using the WebDocumentViewer, 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 within the context of an ASP.NET Core web application targeting the .NET framework, and then walk through its creation, step by step.

 

TECHNICAL REQUIREMENTS

ASP.NET Core Support (not .NET Core)

It is of critical importance to note: e do not have a full .NET Core (sometimes referred to as .NET Core Native) component. Our SDK is a .NET SDK in terms of the meaning of that before ASP.NET Core and .NET Core... our SDK is for targeting the .NET framework.

Please consider reviewing Q10467 - FAQ: Support for ASP.NET Core / .NET Core before continuing with this whitepaper

For this solution we will be targeting ASP.NET Core 2.1 using .NET Framework 4.6.2. It is possible to target .NET 4.5.2 but only when using ASP.NET Core 1.1 or lower.

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 2017 or later. The samples will be using an HTML 5 approach in a non-MVC ASP.NET Core web application targeting .NET framework 4.6.2 targeting 64 bit application pool 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.

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.0 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. The particular ASP.NET Core solution we're supporting needs 4.6.2 or higher

If you have an existing ASP.NET Core 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.. our ASP.NET Core sample here is going to make use of our published packages (we may actually show options for the deprecated bower as well as using npm packages and manual adding of resources). It IS possible to update to newer versions if you like.. but whatever you choose, you should be aware of the MINIMUM required.

On installing the NuGet package for WebDocumentViewer the scripts will be delivered to they are placed in:
PATH HERE

As of 11.0, 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 11.0.0.10 as of September 2018)

We do not currently provide access for our ASP.NET Core components directly in the SDK install, so this tutorial will be using our NuGet packages.

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

 

STANDARD TROUBLESHOOTING

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

 

INSTALLATION AND LICENSING

You may have already installed our SDK from the download site latest version of Atalasoft DotImage SDK, and activated a paid or eval license. If so that's fine. The licensing can be done using our licensing component NuGet package...

NOTE: The current version is 11.0.0.10 as of the creation of this document (September 2018) 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 WdvAspNetCoreSample hosted in IIS under:
c:\inetpub\wwwroot\WdvAspNetCoreSample\

Then you'd copy your licenses from:
C:\users\YOUR_USERNAME\AppData\Local\Atalasoft\DotImage 11.0\
to
c:\inetpub\wwwroot\WdvAspNetCoreSample\bin\

 

EXAMPLE 1

BUILDING A MINIMAL WEB VIEWING APP

We're going to be creating a very minimal WebDocumentViewer (WDV) based application which will also make use of our WebDocumentThumbnailer (WDT).

While this may seem not too useful, it's the fundamental minimum you need to get the WDV running with ASP.NET Core. Don't worry, you can easily get more fancy (we have other documents and whitepapers that go into more advanced use cases), but this tutorial will give you the basic hooks to see how to get it running. For now, we're going to start with the basics.

The first step assumes you've licensed yourself as instructed above or by installing the SDK and running the license wizard to either request a 30 day evaluation or activate paid license for DotImage Document Imaging.

We will be using Visual Studio 2017. You can use later versions of Visual Studio (as available), however for the purpose of this project, 2017 is the platform we will be following. From there, you will create a new ASP.Net web application. Lets also target .NET 4.6.2 as our target framework, since it is the minimum version that this particular use case can support.

Starting the Project

Prerequisites (NuGet Packages)

Prerequisites (Clientside Scripts)

We need to add rquired scripts, images, and css for WebDocumentViewer. The official documentation has used a bower repository, but bower has been deprecated by its creators. There are a few means of getting packages downloaded/installed.. we will provide 3 different approaches.. choose the one that works best for you.. the options are:

  1. Manual copying/install of files
    Easiest to understand, but manual work required. We've provided a convenience distribution for the files for 11.0.0.10 and may update them in the future, and will include ful manual description
  2. Bower Package
    Easiest to implement but based on a distribution method that may be removed from future Visual Studio versions
  3. npm Pagkage
    Most stable and future-proof, but requires the most 'extra work' to implement

Manual Installation

As we mentioned, this may be the most "understandable" as it has no "man behind the curtain" It's all just you copying and renaming a few files from our SDK distribution.

Bower Packages

Bower was the original "official" way we distributed these components. The issue is that bower was deprecated by its creators as the development community felt that it was just an extra complication on top of npm and was too "visual studio-centric". Bower is technically still available for maintenance and since it's easy to use, we'll preserve our instructions here until Visual Studio stops supporting it.

npm Packages

This is probably the most involved process, but it is likely to be the official future-proof way to distribute packages. In ASP.NET Core apps, there are some limitations on what package installers can put into the project files directly so we have to use a couple additional packages and the setup is a bit more complex.