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

### IIS Configuration

Out of the box, this project is configured for use with Kestrel for the .NET Core version and IIS Express for the .NET framework version.

If using IIS Express: Ensure 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
    - .NET Core Hosting Bundle
  - 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 appsettings.json (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: Host ASP.NET Core on Windows with IIS

The project is also configured to use XML Documentation. This may require the "DocumentService.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

For the .NET framework non-NuGet project, the 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 ../src. 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.

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

.NET 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 Startup.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 appsettings.json 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.