Skip to content

Publishing in IIS

Jump to bottom
Steve Ives edited this page Mar 27, 2023 · 4 revisions

Harmony Core Logo

Publishing in IIS

This topic discusses the basic steps you'll need to follow to publish a Harmony Core web service to an IIS server:

  1. Make sure the target system has required libraries (prerequisites).
  2. Mixing .NET Core SDK 2.x with IIS Hosting Package 3.x.
  3. Create a deployment folder.
  4. Publish your application.
  5. Add Traditional Bridge files if necessary.
  6. Set environment variables.
  7. Create an IIS application.
  8. Configuring STDOUT Logging in IIS
  9. Example publish batch file

For an example that shows how a batch file can be used to prepare a new deployment of a Harmony Core application, see Example Publish Batch File below.

Prerequisites

The following must be installed on the target system:

These are required even when publishing a self-contained application.

Create a Deployment Folder

The first step is to create a folder where you'll deploy a runtime copy of your application on the target system. This could be the folder IIS runs the application from or an intermediate staging folder you'll copy from when you copy the files to your IIS directory.

Mixing .NET Core SDK 2.x with IIS Hosting Package 3.x

If you are still developing using a version of the .NET Core SDK earlier than 3.0, but using a 3.0 or later version of the IIS Hosting Package, which would be recommended, there is one additional step that is required. You must manually edit the Services.Host.synproj file and add two lines to the first <ItemGroup> in the file. The lines to add are these:

    <AspNetCoreModuleName>AspNetCoreModuleV2</AspNetCoreModuleName>
    <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>

After editing the file the first ItemGroup should look something like this (but don't edit any of the other code):

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <DefaultLanguageSourceExtension>.dbl</DefaultLanguageSourceExtension>
    <EnableDefaultItems>false</EnableDefaultItems>
    <Name>Services.Host</Name>
    <EnableCommonProperties>True</EnableCommonProperties>
    <ProjectGuid>{D382AB62-71F4-439D-9EE4-ECFCFFD29D9B}</ProjectGuid>
    <Prefer32Bit>False</Prefer32Bit>
    <AspNetCoreModuleName>AspNetCoreModuleV2</AspNetCoreModuleName>
    <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
  </PropertyGroup>

Publish Your Application

Once you have created a deployment folder on the target system, the next step is to publish the application to that folder. To do this, use the dotnet publish command at a Windows command prompt. Execute this command from the folder that contains the self-hosting program for your application. (If you used the harmonycore project template to create your solution, this will be the Services.Host project folder.) For example:

dotnet publish -c Debug -r win7-x64 -o %DeployDir%

Note that this example relies on the environment variable %DeployDir% to specify the location that deployed files will be copied to.

The publish command generates a lot of output, and it is normal to see various warning messages displayed in yellow. However, if you get errors (messages in red), you'll need to resolve the issues that caused them.

If the publish completes successfully, you should find a number of files in the specified folder (the %DeployDir% folder for the example above).

Mixed Environment Check

Once again, if you are still developing using a version of the .NET Core SDK earlier than 3.0, but using a 3.0 or later version of the IIS Hosting Package, you should check that the changes that were made to the Services.Host.synproj file earlier caused the correct changes. Look in the folder that you just published your application to, and edit the generated Web.config file which should look something like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\Services.Host.exe" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="OutOfProcess" />
    </system.webServer>
  </location>
</configuration>
<!--ProjectGuid: D382AB62-71F4-439D-9EE4-ECFCFFD29D9B-->

Verify these two things:

  1. The <add> node inside <handlers> should include an attribute modules="AspNetCoreModuleV2".
  2. The '' node should include an attribute hostingModel="OutOfProcess".

Add Traditional Bridge Files

If your project includes services that use Traditional Bridge, you must deploy the files required for this with your Harmony Core service:

  • Local Traditional Bridge - If your Harmony Core application includes Traditional Bridge files that are executed in process in the Windows environment, those files must be included in the deployment. How you do this depends on how you configured your Traditional Bridge environment. If you used the harmonycore project template as the basis for your development solution, your solution will include a DBR program that executes the traditional Synergy code, and it will include a batch file that is launched by the Harmony Core service when the service needs to create an instance of the Traditional Bridge host. In this scenario, the DBR and the batch file must be copied to the root directory of the deployment folder, along with all the files from the dotnet publish command.

  • Remote Traditional Bridge - If your service uses Traditional Bridge via the SSH mechanism to connect to and run code on a different server, you must implement a process to deploy updated code and configure the environment as necessary.

Set Environment Variables

If your application relies on runtime environment variables and does not set these variables in your own code, they will need to be set for the deployment by some other means. One way to do this is via the Harmony Core AppSettings.json file. See Synergy Logicals for more information.

Create an IIS Application

After successfully deploying your application for the first time, you'll need to create and configure an IIS web site to host the application. The basic steps are as follows:

  1. Open the Internet Information Services (IIS) Manager application.
  2. In the Connections pane, right-click the Sites folder and select Add Website from the context menu.
  3. In the Add Website window, enter a name for the site in the Site name field. Note that a new Application pool will be created with the same name.
  4. In the Physical path field, enter or browse to the folder containing the deployed copy of your application.
  5. In the Binding area, set the Type to https. And in the Port field, enter the number for the port you want IIS to listen on for HTTPS traffic. This is usually set to 443, but you can set it to another number if that port is already in use.
  6. In the SSL Certificate list, select a certificate for the service. If you are configuring a service for testing on your development system, you should be able to use the IIS Express Development Certificate. Otherwise you will need to obtain, install, and select the SSL certificate for the service.
  7. Clear the Start website immediately checkbox.
  8. Click OK. The new site will be created.
  9. In the Connections pane, select Application Pools.
  10. In the Application Pools pane, double-click the application pool that was just created for your service.
  11. In the Edit Configuration Pool dialog, change the value of .NET CLR version to No Managed Code. Then click OK.
  12. Under the Sites folder in the Connection pane, right-click the entry for your new website and select Manage Website > Start from the context menu.
  13. Open a web browser and attempt to navigate to the new IIS site.

If your application has a default HTML home page and you are using IIS on your local machine with the default HTTPS port, navigate to

https://localhost

If you are not using the default HTTPS port, try something like this:

https://localhost:456

If your application does not have a default HTML home page, try one of these:

https://localhost/odata
https://localhost/odata/v1

STDOUT Logging in IIS

To enable the logging of STDOUT messages when running under IIS:

  1. Go to the folder where your application is deployed to and create a logs folder inside that folder.

  2. Edit the web.config file that is provided by the publish mechanism and edit the token by changing the value of stdoutLogEnabled from false to true.

IIS should restart your application when it sees the web.config file change, but if you don't see a log file created then try manually restarting the IIS application and application pool.

Note: We have now modified the default Harmony Core project templates to cause the logs folder to be created automatically during a publish, so depending on the version of the project templates that were used to create your project you may find that the folder already exists.

Slow first request after 20 minutes of inactivity

By default IIS will shutdown the running harmony core application if no request has been made to it in the last 20 minutes. When this happens it means the next request will take several seconds to be served. Because a harmony core server is relatively cheap to keep running at all times, the recommended approach is to increase the IIS App Pool timeout to a large number or disable timeout entirely. Instructions for this are available here https://weblogs.asp.net/owscott/why-is-the-iis-default-app-pool-recycle-set-to-1740-minutes

Example Publish Batch File

The following shows how a batch file could be used to automate the process of preparing a new deployment of your application:

@echo off
setlocal

set DeployDir=%~dp0HarmonyCoreDemoIIS_PUBLISH\
if not exist %DeployDir%\. mkdir %DeployDir%

set SolutionDir=%~dp0HarmonyCoreDemoIIS\
pushd %SolutionDir%

pushd Services.Host
dotnet publish -c Debug -r win7-x64 -o %DeployDir%
popd

if not exist %DeployDir%\SampleData\. mkdir %DeployDir%\SampleData
copy SampleData\*.* %DeployDir%\SampleData

copy TraditionalBridge\bin\Debug\x64\launch.bat %DeployDir%
copy TraditionalBridge\bin\Debug\x64\TraditionalBridgeHost.dbr %DeployDir%

popd
endlocal
pause

As you can see, the batch file uses two environment variables:

  • SolutionDir, which points to the root folder of the development project
  • DeployDir, which points to the folder where a runtime copy of the application should be created
Clone this wiki locally