Tutorial: Hosting CData OData Connectors in IIS



CData OData Connectors by default run hosted in a stand-alone server, which provides an easy way to perform administrative tasks, such as enabling SSL or running the OData Connector as a service, especially if you do not already have experience with IIS. Alternatively, you can host the OData Connector in Microsoft Internet Information Services (IIS) and Java containers.

This guide will show you how to host the OData Connector using IIS. It gives instructions for several versions of IIS and Windows. If your version is not covered in this tutorial, or you have other questions, contact our support team for further assistance.

 

IIS 8 (Windows 8 or Windows Server 2012) or 8.5 (Windows Server 2012 R2)

In this section, you will configure the OData Connector in IIS 8.5 (Windows Server 2012 R2) or in IIS 8 (Windows Server 2012 and Windows 8).

Create a New Web Application

Host the OData Connector on your website.

  1. In the IIS Manager, expand the node for your server in the Connections panel.
  2. Expand the Sites node, right-click your website, and click Add Application. This tutorial uses the default website.
  3. In the Add Application dialog that is displayed, enter the following information:
    • Alias: The name for the application; for example, "cdata".
    • Application Pool: The application pool associated with the OData Connector. This tutorial uses "DefaultAppPool".
    • Physical Path: The path to the www directory, in the directory where the OData Connector was installed.

Configure Permissions

The OData Connector must be able to access the following folders, located in the installation directory.

  • www
  • data
  • logs

Allow the application pool permissions to access the folders used by the OData Connector.

  1. Right-click each folder and click Properties. On the Security tab, click Edit -> Add.
  2. In the "Enter the object names to select" box, enter the following: IIS AppPool\your-application-pool. For example, enter IIS AppPool\DefaultAppPool.
  3. In the folder properties dialog, ensure that the application pool has the following permissions:
    • Read
    • Write
    • Modify
    • Read & Execute
    • List Folder Contents

Note: You can also use the command line to allow access to the application pool. Use the icacls command on each of the folders listed previously. For example:

icacls "www" /grant "IIS APPPOOL\DefaultAppPool":(OI)(M)

Prevent Application Processes from Unloading

IIS can shut down a Web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool's resource use is too high. This may halt background tasks from occurring in your application. Ensure that the OData Connector stays running by modifying the following settings:

  1. Enable the optional Application Initialization feature.

    In Windows Server 2012 and Windows Server 2012 R2, open Server Manager and click -> Dashboard -> Quick Start -> Add Roles and Features. The Add Roles and Features Wizard is displayed. In the Server Roles step, click Web Server (IIS) -> Web Server -> Application Development -> Application Initialization.

    In Windows 8, open the Control Panel and click Programs and Features -> Turn Windows features on or off. Click Internet Information Services -> World Wide Web Services -> Application Development Features -> Application Initialization.

  2. In the IIS Manager, click Application Pools in the Connections pane.
  3. In the Features view, right-click the application pool and click Advanced Settings.
  4. In the General settings, set Start Mode to "AlwaysRunning". In the Process Model settings, set the Idle Timeout property to 0.

    If you are using IIS 8, you will also need to ensure that the Start Automatically property in the General settings is set to True.

  5. In the Connections pane, right-click the Web application associated with the OData Connector and click Manage Application -> Advanced Settings. In the Preload Enabled menu, select True.

Confirm Settings

To open the application, navigate to http://localhost/cdata. If you are getting any errors, see Troubleshooting.

 

IIS 7 (Windows Vista or Windows Server 2008) or IIS 7.5 (Windows 7 or Windows Server 2008 R2)

This section shows how to configure the OData Connector in IIS 7.5 (Windows 7) or in IIS 7 (Windows Vista or Windows Server 2008).

Create a New Web Application

Host the OData Connector on your website.

  1. In the Connections panel, expand the node for your server.
  2. Expand the Sites node, right-click your website, and click Add Application. This tutorial uses the default website.
  3. In the Add Application dialog that is displayed, enter the following information:
    • Alias: The name of the application; for example, "cdata".
    • Application pool: The application pool associated with the OData Connector. This tutorial uses "DefaultAppPool".
    • Physical path: The path to the www directory, in the directory where the OData Connector was installed.

Configure Permissions

The OData Connector must be able to access the following folders, located in the installation directory:

  • www
  • data
  • logs

Allow the application pool to access the folders used by the application:

  1. In Windows Explorer, right-click each folder and click Properties -> Security -> Edit -> Add.
  2. In the "Enter the object names to select" box, enter the following: IIS AppPool\your-application-pool. For example, IIS AppPool\DefaultAppPool.
  3. For each preceding folder, ensure that the application pool has the following permissions:

    • Modify
    • Read & Execute
    • List Folder Contents
    • Read
    • Write

Note: You can also use the command line to allow access to the application pool. Use the icacls command on each of the folders listed previously. For example:

icacls "www" /grant "IIS APPPOOL\DefaultAppPool":(OI)(M)

Prevent Application Processes from Unloading

IIS can shut down a Web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool's resource use is too high. This may halt background tasks from occurring.

IIS 7 does not have configuration settings to always keep the Web application running. In order to ensure that the application pool is always running so that background tasks will occur, you will need to configure a script to issue an HTTP request to the application periodically.

In IIS 7.5, you can ensure that the application stays running by modifying the following settings:

  1. Install the Application Initialization Extension for IIS 7.5.
  2. In the IIS Manager, click Application Pools in the Connections panel.
  3. In the Features view, right-click the application pool and click Advanced Settings.
  4. In the Process Model settings, set the Idle Timeout property to 0. In the General settings, ensure that Start Automatically is set to True.
  5. Modify the settings for the application pool entry in the ApplicationHost.config file, located in C:\Windows\System32\inetsrv\config\. Add startMode="AlwaysRunning" and autoStart="True" to the appropriate <applicationPools> entry. For example:
    <applicationPools>
      <add name="DefaultAppPool" managedRuntimeVersion="v4.0" startMode="AlwaysRunning" autoStart="true"/>
    </applicationPools>
  6. In your ApplicationHost.config, add the preloadEnabled attribute to the <application> element associated with the OData Connector. The application element is a child element of sites:
    <sites>
      <site name="Default Web Site" id="1">
        <application path="/cdata" applicationPool="DefaultAppPool"  preloadEnabled="true">
        ...

Confirm Settings

To log in to the OData Connector, navigate to http:/localhost/cdata. If you are getting any errors, see Troubleshooting.

 

IIS 6 (Windows Server 2003)

This section shows how to configure the OData Connector in IIS 6 (Windows Server 2003).

Create a Virtual Directory

Host the OData Connector on your website. This example uses the default website.

  1. In the IIS Manager, navigate to Console Root -> Local Computer -> Default Web Site.
  2. Right-click Default Web Site and click New -> Virtual Directory to open the Virtual Directory Creation Wizard. Enter the values below at the necessary stages:
    • Alias: The name of your application; for example, "cdata".
    • Directory: The directory where the OData Connector was installed.
    • Access Permissions: Enter the Read, Run, and Execute permissions:

Associate OData Connector File Types with IIS

Assign the ASP.NET executable to file types used by the OData Connector.

  1. If you do not know your version of ASP.NET, right-click the virtual directory for the OData Connector and then click Properties -> ASP.NET. The version is shown in the dialog that is displayed.
  2. Right-click the virtual directory for the OData Connector and click Properties -> Virtual Directory -> Configure.
  3. Add the two application extension mappings .rst and .rsb.
  4. Specify the path to the executable that handles these files. Adjust the path according to the version of ASP.NET that you are using; the OData Connector requires a minimum ASP.NET version of 2.0. The typical path used by version 2.0 is C:\WINDOWS\Microsoft.NET\Framework\v2.0\aspnet_isapi.dll. Note that if your system runs on a 64-bit CPU you will have a Framework64 directory in place of Framework.

Configure Permissions

The OData Connector must be able to access the following folders, located in the installation directory:

  • www
  • logs

Allow access to the service account that the application pool process runs under. The name of the service account is the same as the identity of the application pool. First, determine the application pool identity:

  1. In the IIS Manager, right-click on the virtual directory representing the OData Connector and then click Properties.
  2. In the Virtual Directory tab, note the value in the "Application pool" field. This value is typically DefaultAppPool.
  3. Cancel out of this dialog and expand the Application Pools node in the navigation panel. Right-click on the application pool you identified in the previous step and select Properties. Note the application pool identity.

You can then use Windows Explorer to grant access to the application pool identity:

  1. Right-click each directory and click Properties. On the Security tab, click -> Edit -> Add.
  2. In the "Select Users or Groups" dialog, enter the application pool identity.
  3. In the folder properties dialog, ensure the application pool identity has the following permissions:

    • Modify
    • Read & Execute
    • List Folder Contents
    • Read
    • Write

Prevent Application Processes from Unloading

IIS can shut down a Web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool's resource use is too high. This may halt background tasks from occurring.

This version of IIS does not have configuration settings to always keep the Web application running. In order to ensure that the application pool is always running so that background tasks will occur, you will need to configure a script to issue an HTTP request to the application periodically.

Confirm Settings

Navigate to http://localhost/cdata. If you are getting any errors, see Troubleshooting.

 

IIS 5 (on Windows XP)

This section shows how to configure the OData Connector in IIS 5 (on Windows XP).

Create a Virtual Directory

Host the OData Connector on your website. This example uses the default website.

  1. In the IIS Manager, in the Connections panel, navigate to Console Root -> Local Computer -> Default Web Site.
  2. Right-click Default Web Site, then click New Virtual Directory. This opens the Virtual Directory Creation Wizard. Enter these values at the necessary stages:
    • Alias: The name of the application; for example, "cdata".
    • Directory: The www directory of the OData Connector, located in the installation directory.
    • Access Permissions: Enter the Read, Run, and Execute permissions:

Associate OData Connector File Types with IIS

Assign the ASP.NET executable to file types used by the OData Connector.

  1. If you do not know which version of ASP.NET you are using, right-click the virtual directory for the OData Connector and then click Properties -> ASP.NET. The OData Connector requires a minimum ASP.NET version of 2.0.
  2. Right-click the virtual directory for the OData Connector and click Properties -> Virtual Directory -> Configure.
  3. Add the two application extension mappings .rst and .rsb and specify the path to the executable that handles these files. Adjust the path according to the version of ASP.NET you are using. A typical path for version 2.0 is C:\WINDOWS\Microsoft.NET\Framework\v2.0\aspnet_isapi.dll. If your system runs on a 64-bit CPU, the Framework64 folder replaces Framework.

Prevent Application Processes from Unloading

IIS can shut down a Web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool's resource use is too high. This may halt background tasks from occurring.

This version of IIS does not have configuration settings to always keep the Web application running. In order to ensure that the application pool is always running so that background tasks will occur, you will need to configure a script to issue an HTTP request to the application periodically.

Confirm Settings

You can now open http://localhost/cdata. If you are getting any errors, see the next section, "Troubleshooting."

 

Troubleshooting

The sections below provide resolutions for several common errors.

The OData Connector stops responding some time after I log out.

IIS is possibly unloading your application after it times out from inactivity. By default, IIS terminates the worker process assigned to the OData Connector after 20 minutes of inactivity.

In IIS 7.5 and above, you can ensure the application stays running by modifying configuration settings in the IIS Manager. The section "Prevent Application Processes from Unloading," in the steps to set up your version of IIS, explains how to override this feature.

Versions of IIS before IIS 7.5 do not have configuration settings to always keep the Web application running. To ensure that the application pool is always running so that background tasks will occur, you will need to configure a script to issue an HTTP request to the application periodically.

Visiting http://localhost/cdata results in a "Page Cannot Be Displayed" error (an HTTP 404 error).

This can happen if ASP.NET is not enabled. To confirm this visit, http://localhost/cdata/favicon.ico. If this page loads successfully then ASP.NET is not enabled.

If you are running IIS 7 or higher, open Control Panel -> Programs (or Programs and Features) -> Turn Windows features on or off -> Internet Information Services -> World Wide Web Services -> Application Development Features. Check the box next to ASP.NET.

If you are using Windows Server 2003, open the Internet Information Services Manager, expand the local computer node, and click Web Service Extensions -> ASP.NET -> Allow. You may also need to follow the steps below.

If you are running IIS 6 or earlier, open the Windows command prompt, navigate to the .NET Framework version installation, such as C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727, and run the command "aspnet_regiis -i". You may have to change "Framework" to "Framework64" if you are using a 64-bit processor. The output will resemble the following:

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727>aspnet_regiis -i
  Start installing ASP.NET (2.0.50727).
  ...
  Finished installing ASP.NET (2.0.50727).

Restart IIS by issuing the iisreset command. The output will resemble the following:

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727>iisreset

  Attempting stop...
  Internet services successfully stopped
  Attempting start...
  Internet services successfully restarted

Visiting http://localhost/odataconnector results in an IIS error message: The section is locked at a parent level. Locking is either by default (overrideModeDefault="Deny"), or set explicitly by a location tag with overrideMode="Deny" or the legacy allowOverride="false".

In IIS 8 and 8.5, this error can occur if ASP.NET is not installed: First, determine the version of the ASP.NET CLR that is used by your application pool. You will need to install the version of ASP.NET that ships the same ASP.NET CLR. For example, ASP.NET 4.5 uses CLR version 4.0. You can find the CLR version in the IIS Manager: Click Application Pools in the Connections panel. The .NET CLR Version property is displayed in the list of application pools.

In Windows Server 2012, open Server Manager and click Dashboard -> Quick Start -> Add roles and features. In the Add Roles and Features Wizard that is displayed, click Web Server (IIS) -> Web Server -> Application Development. Select the appropriate version of ASP.NET.

In Windows 8, open the Control Panel and click Programs and Features -> Turn Windows features on or off. Click Internet Information Services -> World Wide Web Services -> Application Development Features -> Application Development. Select the appropriate version of ASP.NET.

 
 
Downloads