HOW TO: Deploy the Documents Service to IIS

IIS Configuration:

Out of the box, this project is configured for use with IIS Express. Just make sure that the IIS Express bitness value matches that of the current configuration. This can be accessed from your Visual Studio by going to Tools/Options/Projects Solutions/Web Projects and checking/unchecking the value of "Use the 64 bit version of IIS Express for web sites and projects" accordingly. The value must be unchecked for the Any CPU and x86 configuration and checked for the x64 configuration.

If you intend to develop with IIS, make sure the following settings are correct:

• IIS 6.0 or later is installed.
  
• In the "Windows Features" dialog, the following boxes are checked:
  
  • .NET Framework 4.6 Advanced Series
    
    • ASP.NET 4.6
  • Internet Information Services
    
    • Web Management Tools
      
      • IIS 6 Management Compatibility
        
        • IIS Metabase and IIS 6 configuration compatibility
      • IIS Management Console
    • World Wide Web Services
      
      • Application Development Features
        
        • .NET Extensibility 4.6
          
        • ASP
          
        • ASP.NET 4.6
          
        • ISAPI Extensions
          
        • ISAPI Filters
      • Common HTTP Features
        
        • Default Document
          
        • Directory Browsing
          
        • HTTP Errors
          
        • Static Content
      • Health and Diagnostics
        
        • Custom Logging
          
        • HTTP Logging
          
        • Request Monitor
          
        • Tracing
      • Performance Features
        
        • Static Content Compression
      • Security
        
        • Request Filtering

After ensuring these settings are correct and creating the virtual directory in IIS, Application Pool settings must be updated as follows:

• Make sure the new Application Pool has Enable 32-Bit Applications set to True if you are developing for x86. Also make sure the .NET CLR Version is at least v4.0.
  
• Ensure that the Application Pool identity has read and write access to the cache directory set in local.config (the value of the lt.Cache.Directory setting).

If you do not modify these options, then IIS will use the built-in DefaultAppPool. This uses ApplicationPoolIdentity which by default does not have write access to the local hard drive and running the service with these options will result in errors.

We recommend creating a new Application Pool instead of changing the options of an existing one.

Publishing:

Reference: Web Deployment Overview for Visual Studio and ASP.NET

When publishing with Web Deploy, an error may appear citing This access control list is not in canonical form and therefore cannot be modified. This is an IIS error and requires the following steps to be taken as an Administrator before the deployment is a success:

• Open either IIS Manager or the folder for your deployment under \inetpub\wwwroot.
  
• Open the "Properties" dialog for the folder, and go to the "Security" tab. (you may get a Windows Security warning before continuing.)
  
• Click the "Edit..." button beside "To change permissions, click Edit."
  
• Click "Reorder".
  
• Apply the changes.
  
• Re-publish the project. (All of your settings should remain unchanged.)

The project is also configured to use XML Documentation. This may require the "App_Data\XMLDocument.xml" documentation file to be published (and included in the project). If you do not wish to include the documentation file, remove the references to it in the project properties.

LEADTOOLS Configuration:

The Documents Service uses a configuration file named local.config to control all file paths or settings. This allows the service to be configured without requiring the DLL to be rebuilt.
When copying the required files to the deployment directory, ensure any/all settings within this file are valid. If any are blank (the default for most), you'll need to supply a valid value based on the comment above the field.

Additionally, any runtime files (such as the OCR runtimes) will need to be in an accessible folder, with their path provided within local.config. For the LEAD OCR engine (the default for the Documents Service) those runtime files can be found in the following folder: LEADTOOLS23\Bin\Common\OcrLEADRuntime

Most of the settings within local.config will be usable out-of-the-box, though there are a few properties that will require manual adjustment:

• License information:
  The two keys relevant for runtime license information are lt.License.FilePath and lt.License.DeveloperKey. These will need to be the absolute (or relative) path to your LIC and KEY files respectively. The developer key also supports specifying the contents rather than the file path.
  
• OCR runtime files:
  You will need to modify the lt.Ocr.RuntimeDirectory setting to be the absolute (or relative) path to the OCR runtimes folder.

"Bad Image Format" Error:

When deploying the application to IIS Express through Visual Studio, the project will automatically configure IIS Express to look for 32-bit or 64-bit DLLs based on the project settings. However, when either deploying to IIS through Visual Studio, or manually copying the files to inetpub\wwwroot you will have to configure this manually. If you haven't done so, you will most likely receive a "Bad Image Format" error.

There is a remark in the IIS section above about the "Enable 32-bit Applications" option, though more explicitly:

• When deploying with AnyCPU selected in Visual Studio:
  
  • If "Prefer 32-bit" is checked in the project build settings, you will need to have "Enable 32-bit Applications" checked within IIS
    
  • If "Prefer 32-bit" is not checked, do not check the IIS option
• When deploying with x64 selected, the IIS option should not be checked (note, not being checked is the default)
  
• When deploying with x86 selected, the IIS option will need to be checked

Edited by moderator Wednesday, December 27, 2023 2:46:33 PM(UTC)  | Reason: Added information for handling the "Bad Image Format" exception