Tutorial 3: Hosting Web APIs in IIS

PowerServer Web APIs can be directly hosted inside of an IIS Application pool and run in the same process as its IIS worker process (w3wp.exe); this is known as in-process hosting. This is different from the out-of-process hosting which runs the PowerServer Web APIs in a process separate from the IIS worker process and forwards the requests made to the IIS reverse proxy to the Kestrel server.


This tutorial talks about the in-process hosting. The configuration of IIS reverse proxy server for the out-of-process hosting will be discussed in Configuring IIS reverse proxy server.

To implement the in-process hosting of PowerServer Web APIs in IIS, you will need to publish Web APIs to IIS using the following methods:

  • Web Deploy -- directly publishes Web APIs to the specified IIS website. You can deploy to the IIS website on the local or remote server.

    To deploy to an IIS website on the local server (e.g. IIS on Windows 10), you will need to set up the server in this way:

    1. Install IIS

    2. Create an IIS website

    3. Install Web Deploy 3.6 (or later) & ASP.NET Core Hosting Bundle 3.1

    To deploy to an IIS website on the remote server (e.g. IIS on Windows Server 2019), you will need to set up the server in this way:

    1. Install IIS

    2. Create an IIS website

    3. Configure IIS

    4. Install Web Deploy 3.6 (or later) & ASP.NET Core Hosting Bundle 3.1

  • File System -- publishes Web APIs to a local folder. You need to manually copy the published folders and files to the web root of the IIS website later.

    This will require you to set up the server in this way:

    1. Install lIS

    2. Create an IIS website

    3. Install ASP.NET Core Hosting Bundle 3.1

Preparations

In this tutorial, we will set up a server running on IIS in an independent machine, and then publish and host the Web APIs in the IIS running on this server.

Step 1: Set up the server with the following OS and software (install the software in the order listed).

  • Windows Server 2019 (64-bit)

  • Microsoft IIS

    Follow the section below to install and configure IIS.

  • Web Deploy 3.6 (or later)

    Download and install from https://www.microsoft.com/download/confirmation.aspx?id=43717.

    IMPORTANT: Make sure to select the Complete setup type when installing Web Deploy.


    When the installation is complete, select Control Panel > System and Security > Administrative Tools > Services, and make sure the "Web Deployment Agent Service" service is running.

    Important

    Web Deploy must be installed after IIS is installed. If you have installed Web Deploy before IIS, uninstall Web Deploy and then choose the Complete setup type to install it again; do not use the Modify feature to re-install Web Deploy.

  • ASP.NET Core Hosting Bundle 3.1

    Download and install from https://dotnet.microsoft.com/download/dotnet/thank-you/runtime-aspnetcore-3.1.13-windows-hosting-bundle-installer.

Step 2: Make sure the API server can connect to the NuGet site: https://www.nuget.org (for installing PowerServer NuGet packages) and the following Appeon sites: https://apips.appeon.com, https://apipsoa.appeon.com, https://apipsinfo.appeon.com, and https://api.appeon.com (for validating the PowerServer license).

Step 3: Configure Windows Defender Firewall on the API server to allow the API server port (81 in this tutorial or any port number you choose). The section "Configuring Windows Defender Firewall" has detailed instructions.

Installing IIS

Windows Server OS

The following steps take Windows Server 2019 as an example:

Step 1: In Windows Server 2019, open Server Manager, and then select Add roles and features.

Step 2: In the Add Roles and Features Wizard, click Next several times until the Server Roles section displays.

Step 3: Select the check box of Web Server (IIS); and then click Add Features when asked whether to add features required for Web server.


Step 4: Make sure the Web Server (IIS) check box is selected, and click Next.


Step 5: Click Next until the Role Services section displays. Make sure the following role services are selected.

IMPORTANT: Management Service must be selected and installed otherwise the IIS remote management will not be supported. If IIS remote management is not supported, then you will not be able to deploy to IIS from a remote computer; you will only be able to deploy to IIS from the local computer.

Management Service is only available on Windows Server OS; and is not available on Windows Desktop OS (such as Windows 10); which means if you have installed IIS on Windows 10, you can only do a local deployment (instead of remote deployment) to IIS.


Step 6: Click Next and then click Install.

After IIS is installed, a Default Web Site is automatically created.

Windows Desktop OS

The following steps take Windows 10 as an example:

Step 1: In Windows 10, navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off (left side of the screen).

Step 2: Expand the Internet Information Services node, and then expand the Web Management Tools node and select the check box for IIS Management Console.

Step 4: Select the check box for World Wide Web Services.

Step 5: Accept the default features for World Wide Web Services or customize the IIS features.


Creating an IIS website

Step 1: In IIS Manager, open the server's node in the Connections panel. Right-click the Sites folder. Select Add Website from the contextual menu.

Step 2: Specify the following values and the click OK to create the site.

  • Site name: testsite in this example

  • Physical path: C:\inetpub\testsite_root in this example. This is where the folders and files of Web APIs will be published.

  • Port: 81 in this example.


The IIS website is created and started.


Open a Web browser and run the following URLs to access the new website.

http://localhost:81/

http://your_server_ip:81/

If the IIS welcome screen displays, then the website is working properly.

Configuring IIS

This section is to configure IIS to support remote deployment. You can skip this section if you will deploy to IIS from the local computer, for example, if you want to deploy to IIS on Windows 10 which supports only local deployment, or if you want to deploy to a local folder first and then manually copy the published files to IIS.

Step 1: Enable remote connections for the IIS server.

  1. In IIS Manager, select the server's node in the Connections panel, and then double click Management Service on the Features View.

    Note: The Management Service feature is available only when you select the Management Service feature when installing IIS.


  2. Select the check box of Enable remote connections, and then click Apply and Start in the Actions pane to start the management service.

    If Management Service is already running, click Stop in the Actions pane to stop the service first before you can make changes to it.


  3. Select Control Panel > System and Security > Administrative Tools > Services, and make sure the "Web Management Service" service is running.

Step 2: Configure the IIS website to allow the Windows user to connect to the site.

  1. In IIS Manager, select the website in the Connections panel, and then double click IIS Manager Permissions on the Features View.


  2. Click Allow User on the Actions pane. In the Allow User dialog, click Select.


  3. Enter the Windows user name, click Check Names and then click OK.

    IMPORTANT: Make sure to use a Windows user that has Full Control over the site's root folder so that it can create files and folders underneath.


    The Windows user is added to IIS Manager Permissions. This Windows user is allowed to connect to the "testsite" site now.


Publishing Web APIs to IIS

The following uses the Web Deploy method to publish Web APIs to IIS:

Step 1: On the development machine, open the PowerServer Web API solution in SnapDevelop. Log in to SnapDevelop if required.

Click the Open C# Solution in SnapDevelop button () in the toolbar to launch the Web API solution in SnapDevelop. Or go to the location where the Web API solution is generated; and double click PowerServerApp.sln to launch the solution in SnapDevelop.

At startup, the solution will install/update the dependencies. Wait until the Dependencies folder completes the install/update. (Make sure the machine can connect to the NuGet site: https://www.nuget.org in order to successfully install PowerServer NuGet packages).

Step 2: In the Solution Explorer, right click on the ServerAPIs project node, and select Publish.

Step 3: In the window that appears, select Web Deploy, and click Start.

Step 4: Configure the Web deploy profile, and click Next.

The following figure shows the settings for deploying to an IIS website on a remote server.

Note: Input the Windows user name that you have configured to allow to connect to the site.


The following figure shows the settings for deploying to an IIS website on the local machine.

It is not necessary to input username and password when connecting to a local site.


Step 5: Keep the others as default settings and click Finish.


Publishing begins automatically. If any error or failure is reported in the Output window, click the link provided at the end to view more details and possible solutions.

Step 6: Make sure publishing was successful as shown in the figure below.

After that you can specify the URL (for example, http://172.16.100.83:81) as the Web API URL in the Web APIs tab of the PowerServer project and then build and deploy the project again.

If you use the SQL Anywhere database or ASE database, also set up the corresponding ODBC data source in the server where Web APIs are published and running.


When you run the installable cloud application later, the following two processes will be started in the server and they will launch the PowerServer Web API automatically.