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.
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)
Run the installer as Administrator
After installation, run the following to confirm ANCM is registered:
%windir%\system32\inetsrv\appcmd list modules | findstr AspNetCoreExpected output:
MODULE "AspNetCoreModuleV2" (image:...aspnetcorev2.dll)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:
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):
2. Create the Application Directory
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
Name
appRulesPortal
.NET CLR Version
No Managed Code
Managed Pipeline Mode
Integrated
After creation, select the pool → Advanced Settings:
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:
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)
Open IIS Manager → Sites → Add Website
Fill in:
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
Click OK
Option B — PowerShell
6. Configure HTTPS (Recommended)
Bind an SSL Certificate
In IIS Manager, select the server node → Server Certificates
Import your certificate (PFX) or request one via IIS
On the site → Bindings → Add:
Type
https
Port
443
Host name
yourserver.yourdomain.com
SSL certificate
(select your certificate)
Force HTTPS Redirect
Add to web.config inside <system.webServer>:
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
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 ProtocolsIf 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:
Temporarily enable stdout logging in
web.config:Ensure
.\logs\folder exists and is writable by the App Pool identityRecycle the App Pool:
Browse to the site to trigger the failure
Check
.\logs\stdout_*.logfor the exceptionSet
stdoutLogEnabled="false"immediately after — stdout logging is unbounded and will fill disk
Common causes
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)
Schedule maintenance windows outside business hours.
Reference
.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
Last updated