> For the complete documentation index, see [llms.txt](https://docs.appstrategy.com/apprules-r-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appstrategy.com/apprules-r-documentation/platform/self-hosting/software-installation/iis-setting.md).

# IIS Settings

### appRulesPortal — IIS Setup Guide

#### .NET 10 /  Wisej / Windows Server

> **Note:** 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 10 Hosting Bundle**

The Hosting Bundle installs the .NET 10 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/10.0> → Look for **".NET 10 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:

   ```bat
   iisreset /restart
   ```

**Install the .NET 10 Desktop Runtime**

The Hosting Bundle alone is **not sufficient**. appRulesPortal and the companion services target a Windows framework and additionally require `Microsoft.WindowsDesktop.App`, used by the Wisej.NET UI framework.

Download the **.NET 10 Desktop Runtime (x64)** from the same page and install it as Administrator.

Verify both runtimes:

```bat
dotnet --list-runtimes
```

`Microsoft.NETCore.App`, `Microsoft.AspNetCore.App` and `Microsoft.WindowsDesktop.App` must each show a 10.x version.

**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):

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

***

#### 2. Create the Application Directory

```bat
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          |

> **"No Managed Code" is correct and unrelated to the .NET version.** It tells IIS not to load the legacy .NET Framework CLR into the worker process. The application itself runs on .NET 10 in the Kestrel process, which ANCM starts.

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:

```bat
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`             |

3. Click **OK**

**Option B — PowerShell**

```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>`:

```xml
<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`:

   ```xml
   stdoutLogEnabled="true"
   ```
2. Ensure `.\logs\` folder exists and is writable by the App Pool identity
3. Recycle the App Pool:

   ```bat
   %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.31`                          | Required framework not found           | Install the .NET 10 Hosting Bundle **and** the .NET 10 Desktop Runtime; the stdout log names the missing framework |
| `500.35`                          | ANCM in-process handler load failure   | Reinstall the .NET 10 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                                                                    |

> **After upgrading appRules to a .NET 10 release,** install the .NET 10 runtimes and run `iisreset /restart` **before** browsing to the site. A worker process started before the upgrade still references the previous runtime.

***

#### 9. Maintenance

**Recycling the App Pool (planned)**

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

Schedule maintenance windows outside business hours.

**Upgrading the .NET runtime**

When a new .NET 10 servicing update is installed (for example 10.0.12 → 10.0.13), restart IIS so worker processes pick it up:

```bat
iisreset /restart
```

Do **not** uninstall older .NET runtimes that other applications on the server may still require; .NET runtimes install side by side.

***

#### Reference

| Item                    | Value                                                                       |
| ----------------------- | --------------------------------------------------------------------------- |
| .NET 10 Hosting Bundle  | <https://dotnet.microsoft.com/en-us/download/dotnet/10.0>                   |
| .NET 10 Desktop Runtime | <https://dotnet.microsoft.com/en-us/download/dotnet/10.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> |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.appstrategy.com/apprules-r-documentation/platform/self-hosting/software-installation/iis-setting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.