IIS Settings

appRulesPortal — IIS Setup Guide

.NET 8 / Wisej 4 / Windows Server

Note: As of .NET 8, appRulesPortal runs as a self-hosted Kestrel Windows Service and does not require IIS to operate. IIS is optional and only needed if you want to use it as a reverse proxy in front of Kestrel — for example, to handle SSL termination on port 443 and forward traffic to Kestrel on port 8080, or to host multiple sites on the same server on port 80/443.

If you are deploying appRulesPortal as a standalone Windows Service (the default), skip this guide and see HostService Settings instead.

---

1. Server Prerequisites

Install the .NET 8 Hosting Bundle

The Hosting Bundle installs the .NET 8 runtime and the ASP.NET Core Module v2 (ANCM) into IIS. Without it, IIS cannot forward requests to the Kestrel process.

1. Download from: https://dotnet.microsoft.com/en-us/download/dotnet/8.0 → Look for ".NET 8 Hosting Bundle" (not the SDK, not the Runtime alone)

2. Run the installer as Administrator

3. After installation, run the following to confirm ANCM is registered:

   %windir%\system32\inetsrv\appcmd list modules | findstr AspNetCore

   Expected output:

   MODULE "AspNetCoreModuleV2" (image:...aspnetcorev2.dll)

4. If IIS was already running before the install, restart it:

   iisreset /restart

Enable IIS Features (Windows Server)

Open Server Manager → Add Roles and Features → Web Server (IIS) Ensure these features are enabled:

Feature	Path	Required for
Web Server	Web Server (IIS)	Base IIS
Static Content	Common HTTP Features	Serving JS, CSS, fonts
Default Document	Common HTTP Features	Serving Default.html
HTTP Errors	Common HTTP Features	Error pass-through
Request Filtering	Security	Request size limits
WebSocket Protocol	Application Development	Wisej real-time sync
ASP.NET 4.x	Application Development	Not required — but harmless

⚠️ WebSocket Protocol is mandatory for Wisej. Without it, Wisej falls back to long-polling — all users will experience significantly degraded performance and higher server CPU.

To enable WebSocket via PowerShell (run as Administrator):

Install-WindowsFeature Web-WebSockets
# or on Windows 10/11:
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebSockets

---

2. Create the Application Directory

mkdir C:\inetpub\appRulesPortal
mkdir C:\inetpub\appRulesPortal\logs

Copy the full Release build output to this folder. When using IIS as a reverse proxy, the physical path points to the site root (one level above bin\), not to bin\ itself. The Kestrel service still serves the actual requests — IIS only forwards them. See RELEASE_DEPLOYMENT.md for the complete file/folder structure.

---

3. Create the Application Pool

Open IIS Manager → Application Pools → Add Application Pool

Setting	Value
Name	appRulesPortal
.NET CLR Version	No Managed Code
Managed Pipeline Mode	Integrated

After creation, select the pool → Advanced Settings:

Setting	Value	Reason
Start Mode	AlwaysRunning	Wisej must always be running — do not lazy-start
Idle Time-out (minutes)	0	Disable — idle shutdown kills active user sessions
Regular Time Interval (minutes)	0	Disable periodic recycling during business hours
Identity	ApplicationPoolIdentity or domain account	See permissions below

⚠️ Never enable idle timeout or periodic recycling for a Wisej application. Recycling the App Pool disconnects all active browser sessions immediately. If recycling is required for memory management, schedule it outside business hours using a Specific Time recycle instead.

---

4. Set Folder Permissions

The App Pool identity must have the following permissions on the site root:

REM Replace "IIS AppPool\appRulesPortal" with your domain account if applicable
icacls "C:\inetpub\appRulesPortal"       /grant "IIS AppPool\appRulesPortal:(OI)(CI)R"
icacls "C:\inetpub\appRulesPortal\logs"  /grant "IIS AppPool\appRulesPortal:(OI)(CI)M"
icacls "C:\inetpub\appRulesPortal\App_Data" /grant "IIS AppPool\appRulesPortal:(OI)(CI)M"

Folder	Permission	Reason
Site root (\)	Read	Serve static files, load config
bin\	Read	Load assemblies
logs\	Modify	ANCM writes stdout logs
App_Data\	Modify	Application data read/write

---

5. Create the IIS Site

Option A — IIS Manager (GUI)

1. Open IIS Manager → Sites → Add Website

2. Fill in:

Field	Value
Site name	appRulesPortal
Application pool	appRulesPortal (created above)
Physical path	C:\inetpub\appRulesPortal
Binding type	http (add https binding separately)
Port	80 (or your designated port)
Host name	yourserver.yourdomain.com

1. Click OK

Option B — PowerShell

Import-Module WebAdministration

New-WebAppPool -Name "appRulesPortal"
Set-ItemProperty IIS:\AppPools\appRulesPortal managedRuntimeVersion ""
Set-ItemProperty IIS:\AppPools\appRulesPortal startMode "AlwaysRunning"
Set-ItemProperty IIS:\AppPools\appRulesPortal processModel.idleTimeout "00:00:00"

New-Website -Name "appRulesPortal" `
            -PhysicalPath "C:\inetpub\appRulesPortal" `
            -ApplicationPool "appRulesPortal" `
            -Port 80 `
            -HostHeader "yourserver.yourdomain.com"

---

6. Configure HTTPS (Recommended)

Bind an SSL Certificate

1. In IIS Manager, select the server node → Server Certificates

2. Import your certificate (PFX) or request one via IIS

3. On the site → Bindings → Add:

Field	Value
Type	https
Port	443
Host name	yourserver.yourdomain.com
SSL certificate	(select your certificate)

Force HTTPS Redirect

Add to web.config inside <system.webServer>:

<rewrite>
  <rules>
    <rule name="HTTP to HTTPS" stopProcessing="true">
      <match url="(.*)" />
      <conditions>
        <add input="{HTTPS}" pattern="off" ignoreCase="true" />
      </conditions>
      <action type="Redirect" url="https://{HTTP_HOST}/{R:1}"
              redirectType="Permanent" />
    </rule>
  </rules>
</rewrite>

Requires IIS URL Rewrite Module: https://www.iis.net/downloads/microsoft/url-rewrite

---

7. Verify the Deployment

Check ANCM is handling requests

Browse to http://yourserver/ — you should see Default.html (the Wisej login page).

Quick verification checklist

Test	Expected Result
GET /	Wisej login page loads
GET /Default.html	Same login page
GET /appsettings.json	HTTP 403 Forbidden
GET /Default.json	HTTP 200 (Wisej config — intentionally public)
Login with valid credentials	Main portal opens
Open browser DevTools → Network	WebSocket connection established (101 Switching Protocols)

Confirm WebSocket is working

In browser DevTools (F12) → Network tab → filter by WS:

• You should see a WebSocket connection to ws://yourserver/...

• Status should be 101 Switching Protocols

• If you see repeated XHR polling requests instead, WebSocket is not working — check the IIS WebSocket Protocol feature

---

8. Startup Failure Diagnosis

If the site returns HTTP 500.30 or a blank page:

1. Temporarily enable stdout logging in web.config:

   stdoutLogEnabled="true"

2. Ensure .\logs\ folder exists and is writable by the App Pool identity

3. Recycle the App Pool:

   %windir%\system32\inetsrv\appcmd recycle apppool /apppool.name:"appRulesPortal"

4. Browse to the site to trigger the failure

5. Check .\logs\stdout_*.log for the exception

6. Set stdoutLogEnabled="false" immediately after — stdout logging is unbounded and will fill disk

Common causes

Error	Cause	Fix
500.19	Malformed web.config	Validate XML syntax
500.30	App failed to start	Check stdout log
500.35	ANCM in-process handler load failure	Reinstall .NET 8 Hosting Bundle
403.14	Directory browsing	Set default document to Default.html
Blank page / no Wisej	Wrong arguments path in web.config	Confirm .\bin\appRulesPortal.dll exists
Long-polling instead of WebSocket	WebSocket feature not installed	Enable IIS WebSocket Protocol
License warning banner	Wrong or missing Wisej license key	Check Default.json → Wisej.LicenseKey
Sessions drop on recycle	App Pool idle timeout or recycling	Set idle timeout to 0, disable periodic recycle

---

9. Maintenance

Recycling the App Pool (planned)

REM Graceful recycle — active sessions will disconnect
%windir%\system32\inetsrv\appcmd recycle apppool /apppool.name:"appRulesPortal"

Schedule maintenance windows outside business hours.

---

Reference

Item	Value
.NET 8 Hosting Bundle	https://dotnet.microsoft.com/en-us/download/dotnet/8.0
IIS URL Rewrite Module	https://www.iis.net/downloads/microsoft/url-rewrite
Wisej deployment docs	https://docs.wisej.com/deployment/targets/iis
Wisej self-hosting docs	https://docs.wisej.com/deployment/targets/self-hosting
ANCM troubleshooting	https://learn.microsoft.com/en-us/aspnet/core/test/troubleshoot-azure-iis