NOTE: this article refers to our .NET Imaging SDKs (DotImage, DotTwain, WingScan, and DotPdf)

Background

When you upgrade to a new version of DotImage - be that to the next hotfix or fixpack or even when upgrading after having skipped multiple releases, there are a few steps here that should help ensure you get a successful update.

Procedure

Install the SDK and Activate Updated Licenses (if needed)

First, you will need to ensure you've installed the new version of the SDK on your development machine. You CAN NOT just swap out our new DLLs for old ones in any compiled app and expect it to work - you have to rebuild/recompile your app, and so you need the updated DLLs and also an updated license for the new version if the jump in versions is "big enough"

You can get the latest DotImage installer from our Download Page (https://www.atalasoft.com/BeginDownload/DotImageDownloadPage) though keep in mind, sometimes that download page lags behind the latest - if we have just released a new update, and it's not "live" there yet, you may need to create a support case to ask for it.

Also note that our NuGet packages take up to 2 weeks to "go live" after a new version is released - unfortunately while support can get you the certified SDK installer as soon as the release has been certified by QA, the NuGet publish process has no shortcut/workaround - so users using that method to get our packages will have to wait until their needed version is live.

When Licenses Need Updating

When you activate a license you will be activating for a specific MAJOR.MINOR.. so DotImage 9.0 to 10.0 was a MAJOR version as would be 10.0 to 11.0 etc.. but what you may not know is that we require an updated license for minor version changes too (but not service packs, fixpacks and hotfixes).

Examples:

1) No upgrade needed

Lets say you're on 11.3.0.3.730 and lets say you're updating to a new fixpack but it's still 11.3 - so 11.3.0.4.742 (the final 11.3 release we made)

This would NOT require a new license if you're already licensed for 11.3

2) Upgrade required

Now, instead lets say you're on 11.3.0.4.742 and you need to move to an 11.4 release. The latest (as of October 2022) is 11.4.0.3.311 which is 11.4, Fixpack 3.
This would require new license FILES but you don't need to go get new licenses or contact sales - so long as you're under maintenance, you just need to activate your existing serials for 11.4.

HOWTO: Activate DotImage SDK or Server (Including Offline Activation)

When you run the activation wizard you just need to ensure you select 11.4 for the version and activate again

If you run into any errors/issues please create a support case, and make sure you provide the serial number(s) in question as well as the error message you received.

Update Your Project/Solution

DLLs (References)

NOTE: this needs to be applied to all projects within the solution as you can not mix versions of DotImage in the same solution (or in the same project)

When you install the new SDK, if you're moving in the same MAJOR.MINOR (so say going from one 11.3 release to a newer one that is still under 11.3, then the install OVERWRITES the previous version. However, when going up to a new MAJOR.MINOR such as moving from 11.3.x.y.zzz to 11.4.x.y.zzzz then the old 11.3 will not be touched - the install will happen and the new version will end up in its own Program Files directory - so for 11.3 it would be in C:\Program Files (x86)\Atalasoft\DotImage 11.3\ and the 11.4 would install to C:\Program Files (x86)\Atalasoft\DotImage 11.4\. Likewise, as mentioned above with new licenses, your license files end up in their own directory separated by version so when you activate an 11.4 license it will leave your 11.3 ones alone and overwrite any previous 11.4 licenses (which can be found in its default location - please see FAQ:Where Can I Find My Atalasoft License Files (https://www.atalasoft.com/kb2/KB/50417/FAQWhere-Can-I-Find-My-Atalasoft-License-Files) for more on specific locations.

Once the new SDK is installed, you need to go to your application and ensure that the referenced DLLs are now pointing to the new versions. Sometimes, old versions will "stick". So you can often fix this by removing and re-adding the references, to ensure it's pointing at the new version.

Another way to update is to manually edit your csproj / vbproj project file to change the hint paths

So, if you edit your csproj / vbproj file, look for the Atalasoft related items

Current Project File (partial):

<ItemGroup>
    <Reference Include="Atalasoft.dotImage">
      <Name>Atalasoft.dotImage</Name>
      <HintPath>C:\Program Files (x86)\Atalasoft\DotImage 11.3\bin\4.5.2\x86\Atalasoft.dotImage.dll</HintPath>
    </Reference>
    <Reference Include="Atalasoft.dotImage.Lib">
      <Name>Atalasoft.dotImage.Lib</Name>
      <HintPath>C:\Program Files (x86)\Atalasoft\DotImage 11.3\bin\4.5.2\x86\Atalasoft.dotImage.Lib.dll</HintPath>
    </Reference>
    <Reference Include="Atalasoft.Shared">
      <Name>Atalasoft.Shared</Name>
      <HintPath>C:\Program Files (x86)\Atalasoft\DotImage 11.3\bin\4.5.2\x86\Atalasoft.Shared.dll</HintPath>
    </Reference>
...
</ItemGroup>

Updated for 11.4:

<ItemGroup>
    <Reference Include="Atalasoft.dotImage">
      <Name>Atalasoft.dotImage</Name>
      <HintPath>C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\4.5.2\x86\Atalasoft.dotImage.dll</HintPath>
    </Reference>
    <Reference Include="Atalasoft.dotImage.Lib">
      <Name>Atalasoft.dotImage.Lib</Name>
      <HintPath>C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\4.5.2\x86\Atalasoft.dotImage.Lib.dll</HintPath>
    </Reference>
    <Reference Include="Atalasoft.Shared">
      <Name>Atalasoft.Shared</Name>
      <HintPath>C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\4.5.2\x86\Atalasoft.Shared.dll</HintPath>
    </Reference>
...
</ItemGroup>

If it's still not "sticking" make sure you don't have a "reference paths" set. To check this:

• Go to Visual Studio Solution Explorer
• Right click on the project
• select "Properties"
• In the project properties tab that comes up go to Reference Paths.
• If there's an outdated value such as C:\Program Files (x86)\Atalasoft\DotImage 11.3\bin\4.5.2\x86\ click on it and edit it to C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\4.5.2\x86\ then click UPDATE

NOTE if there are more than one path in Reference Paths below, it will take the first valid path it finds so you can use the up /down arrows to select which version.

This is also useful for quickly switching versions without having to edit the csproj file - just switch which one is on top and check that your references are updated.

Remember to save the solution and rebuild the project for the new versions to be used.

ON NO ACCOUNT should you mix different versions of Atalasoft DLLs in the same project or even in different projects in the same solution - you can have multiple versions of DotImage in different solutions but do not mix them in the same project.

WebDocViewer Resources

If you're using our WebDocumentViewer and/or WebDocumentThumbnailer in your app, you need to update your WebDocViewer Resources, and verify if there are changes needed to the script version links.

In your app, you may have a folder named WebDocViewer (but it could be named anything ... Scripts,  WebDocviewerResources or anything else. In theory the scripts and css files could be anywhere but the need is the same: review the contents of the new WebDocViewer resources shipped in the new version

Example:

Version 11.4 shipped with the following contents of C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\WebResources\WebDocViewer\

atalaWebDocumentViewer.css
atalaWebDocumentViewer.d.ts
atalaWebDocumentViewer.js
clipboard.min.js
jquery-3.5.1.min.js
jquery-ui-1.13.1.min.css
jquery-ui-1.13.1.min.js
raphael-min.js
images\atala-ui-dragdropfile.png
images\atala-ui-icons-16.png
images\atala-ui-spinner.gif
images\ui-icons_444444_256x240.png
images\ui-icons_555555_256x240.png
images\ui-icons_777620_256x240.png
images\ui-icons_777777_256x240.png
images\ui-icons_cc0000_256x240.png
images\ui-icons_ffffff_256x240.png

What you want to do is replace the current ones in your solution with the ones from the update

When support builds sample apps, we keep the WebDocViewer folder the same so we just update the contents of that WebDocViewer with a direct copy over from the new C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\WebResources\WebDocViewer

NOTE: If you are upgrading from a previous version that has the same versions of jQuery and jQueryUI (3.5.1 and 1.13.1 respectively) then you may need to also update your script links (see below)

WebCapture Resources

If you're using our WebCapture (WingScan) components, then when updating to a new version, you need to update/replace all the WebCapture Resource files in your solution with the new ones

NOTE: they will have the same file names so it's critical to not assume they're unchanged - you MUST update

TO do this, you need to find the files in your solution that correspond to the WebCapture Resource files provided in our SDK.

Version 11.4 shipped with the following contents of C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\WebResources\WebCapture\

atalaWebCapture.js
Kofax.WebCapture.Installer.msi
Kofax.WebCapture.macOS.pkg

You will want to replace the files in your solution with the new ones

Special Note for Those Not Using WebDocumentViewer

Please note that the WebCapture components we use depend on the same version of jQuery that we use with WebDocViewer. If you're not using WebDocumentViewer with your WebCapture, make sure you at least copy over C:\Program Files (x86)\Atalasoft\DotImage 11.4\bin\WebResources\WebDocViewer\jquery-3.5.1.min.js

Script Dependencies

This was already somewhat covered above but we need to be explicit about it here...

We update our scripts every time and don't list versions in file names so in theory if you have updated the scripts underneath, then you don't need to change the links in your markup, but when the version of jQuery and jQueryUI update, we need to also be sure we're pointing to the right ones...

Example:

in 11.3.0.3, we changed from jQueryUI 1.12.1 to 1.13.1. So, the new files shipped will include
jquery-ui-1.13.1.min.js
and
jquery-ui-1.13.1.min.css

So, if you check your HTML markup where you're including scripts, you may need to update those as well:

Old:

<!-- Js scripts in correct order -->
<script src="WebDocViewer/jquery-3.5.1.min.js" type="text/javascript"></script>
<script src="WebDocViewer/jquery-ui-1.12.1.min.js" type="text/javascript"></script>
<script src="WebDocViewer/raphael-min.js" type="text/javascript"></script>
<script src="WebDocViewer/clipboard.min.js" type="text/javascript"></script>
<script src="WebDocViewer/atalaWebDocumentViewer.js" type="text/javascript"></script>

<!-- CSS files in correct order -->
<link href="WebDocViewer/jquery-ui-1.12.1.min.css" rel="Stylesheet" type="text/css" />
<link href="WebDocViewer/atalaWebDocumentViewer.css" rel="Stylesheet" type="text/css" />

New:

<!-- Js scripts in correct order -->
<script src="WebDocViewer/jquery-3.5.1.min.js" type="text/javascript"></script>
<script src="WebDocViewer/jquery-ui-1.13.1.min.js" type="text/javascript"></script>
<script src="WebDocViewer/raphael-min.js" type="text/javascript"></script>
<script src="WebDocViewer/clipboard.min.js" type="text/javascript"></script>
<script src="WebDocViewer/atalaWebDocumentViewer.js" type="text/javascript"></script>

<!-- CSS files in correct order -->
<link href="WebDocViewer/jquery-ui-1.13.1.min.css" rel="Stylesheet" type="text/css" />
<link href="WebDocViewer/atalaWebDocumentViewer.css" rel="Stylesheet" type="text/css" />

Additional Considerations (Advanced Concepts / Situations)

The above applies pretty much universally to DotImage regardless of version, However there are certain changes that were made (oftentimes, long ago) that may make breaking changes or require additional steps in upgrading

Barcode Engine

We changed our engine for BarCodeReader a few times throughout the years. Most notably, in 7.0b, we moved to a new engine with was valid / part of DotImage through the end of 9.0. In 10.0, we moved to a new engine again, and have been on that engine ever since

If you happen to be upgrading across major versions  - note that in 7.0a and older there was a dll named Atalasoft.dotImage.BarCodeReader.dll which, in 7.0b through 9.0.4.xxxx changed to Atalasoft.dotImage.Barcoding.dll. In 10.0 and newer it changed again to Atalasoft.dotImage.Barcoding.Reading.dll.

Additionally, serial numbers changed - very old 7.0a and older barcode serials start with BRD2,BRP2, or BRS2.

Any customers with those licenses under maintenance would have been issued replacement serials for 7.0b and newer which (again went through 9.0) with serials starting with BCRD, BCRP or BCRS.

As of 10.0 and through to today the serials start with BARD (you may see old, outdated BARP or BARS serials - those are all replaced with a BARD.

If you have any issues with outdated serials/licenses when upgrading, please create a support case and be sure to provide the versions you are/were using as well as the serial number(s) in question.

Assembly Restructuring (happened in 10.3)

In 10.3, we moved several key classes from old namespaces to new, We did not remove any features, but the namespace/dll where certain features lived was altered. This was an effort do reduce the number of Atalasoft dll dependencies required.

There is a full KB article on this topic. If you're moving from any version 10.2 or older to a newer one please review this KB article thoroughly

INFO: Assembly Restructuring Introduced In Version 10.3

Other Assembly / License Changes

We try diligently to avoid breaking changes but you may run into additional changes in terms of DLLs that were removed or renamed etc

PdfRasterizer (PdfReader)

This actually is covered in the 10.3 restructuring, but is such a common issue for customers to run into, we thought we'd note it here explicitly

As of 10.3 and newer Atalasoft.dotImage.PdfRasterizer.dll was removed and replaced with Atalasoft.dotImage.PdfReader.dll

Please see INFO: Assembly Restructuring Introduced In Version 10.3 for a full description of all 10.3 changes

Pdfium

As of 11.0 we ended our business relationship / contract with Foxit and switched to the Pdfium OCR engine. Customers moving from 10.7 and older to 11.0 and newer will not have to change away from Atalasoft.dotImage.PdfReader.dll that is still the current DLL name. However, their licenses starting with PRS2 / PRSX2 will be replaced/updated with licenses starting with PRP2 / PRPX2.

There is a complete KB article on that change available here:

INFO: Changes to PDF Rendering Library (Foxit to PdfIum)

Silverlight

We removed support for Sliverlight Web Apps in 11.2. As a result, you will no longer find an AnyCPU folder or a Siliverlight folder in our bin directory and will not be able to find or reference our Atalasoft.dotImage.Silverlight.dll. Support was removed for these components

OCR Engines

We have had several different OCR engines in various DotImage Versions. If you're using a specific engine that was removed in an older version, you must either stay with the last version where it was avilable or move to a new engine. In many cases, when we've ended a relationship with an OCR Engine, existing customers are grandfathered with a new license for the new engine. This most recently happened when we went from 11.2 to 11.3. 11.3 dropped support for our AbbyyEngine and introduced OmniPageEngine. Any existing customers with AbbyyEngine OCR licenses were granted equivelant OmniPageEngine licenses.

OCR Resources

Each OCR engine has unique (to it) OCR Resources that need to be provided to your app.

When you install the SDK , we include GlpyhReader, and Tesseract OCR resources under c:\Program Files (x86)\Atalasoft\DotImage 10.4\bin\OcrResources\ (example is for 11.4, version number will vary depending on installed version of DotImage)

We do not ship other resources such as RecoStar, Abbyy or OmniPage directly with the SDK installer due to the size of the downloads.

Since RecoStar and Abbyy are no longer part of DotImage, the only one that counts here would be OmniPage. Please see INFO: OmniPageEngine - Overview for details on the download location.

DotImage Document Imaging Includes Jbig2,Jpeg2000, Forms Processing, Dicom, and CADD components

If you have a DotImage Document Imaging (DID2 / DIDX2) license that is under active maintenance, it now includes licensing for Jbig2, Jpeg2000, DICOM, and CADD (DWG), as well as Forms Processing

This means you don't need to activate separate serials starting with JB22/JBX2, DJP2/DJPX2. DJS2/DJSX2, DICM/DICXM, CADD/CADXD, FOPS/FOPX2 respectively

For activation, we suggest you activate your DID2 / DIDX2 and leave out those other serials if you have them - if you get an error about a missing license file, then please make a support case with the serial(s) and we can triple check if you are covered under this.

Original Article:

Q10041 - HOWTO: Upgrade to a newer version of DotImage (Also, covers DotTwain, WingScan and DotPdf)