IIS Configuration - Publishing - Extra Assemblies - Linked Files - Code Analysis - Service Exceptions - JSON Serialization - CORS

### 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:

1. Open either IIS Manager or the folder for your deployment under \inetpub\wwwroot.
2. Open the "Properties" dialog for the folder, and go to the "Security" tab. (you may get a Windows Security warning before continuing.)
3. Click the "Edit..." button beside "To change permissions, click Edit."
4. Click "Reorder".
5. Apply the changes.
6. 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.

### Extra Assemblies

The LEADTOOLS service makes use of extra assemblies that are not referenced directly by the project. Instead, they are loaded dynamically at runtime based on a certain request (OCR, for example).

ExtraAssemblies.targets is a file listing those assemblies, which are copied from the proper path (debug or release, x86 or x64) to the bin as part of the "AfterBuild" target. If you are receiving unexpected results from the service, check that you are copying the assemblies correctly.

### Linked Files

Some files in this project are linked from /Examples/JS/Common and /Examples/JS/Resources. These files are linked so that they receive changes to the source file; however, they naturally will not be physically present in their directory. For this reason, a post-build event is added to copy all linked files from their link sources.

### Code Analysis

Code Analysis files are added and available at CodeAnalysis. Using Code Analysis can help detect issues with development.

### Service Exceptions

Exception handling is important in this Web Api service. The classes within Tools/Exceptions Contribute to detailed exception reporting back to the client. A request / response debugger like Telerik's Fiddler may be helpful in understanding the ServiceException returned from the service when an error occurs.

In Controllers, each action may have a ServiceErrorAttribute that determines the generic exception message returned. Additional controller methods should take advantage of this attribute.

### JSON Serialization

Web Api 2 uses JSON.NET for JSON serialization. JSON.NET has different functionality than other serializers, so server-side code is included to ensure that LEADTOOLS objects are properly serialized. Most of the relevant code is located in App_Start/WebApiConfig.cs.

### CORS

This project comes with CORS already configured via Enabling Cross-Origin Requests in ASP.NET Web API 2. CORS options can be easily configured from the local.config file.

In order to serve requests for .data files in the cache (accessible from the Document.CacheUri property), the CacheModule class of the Document Service automatically allows all origins. For a production environment, consider restricting this access.