# Configuration

Wisej.NET applications are standard Web Projects in Visual Studio. All standard `Web.config` settings remain valid.

In addition to `Web.config`, Wisej.NET applications use individual JSON configuration files. A single project can define multiple Wisej.NET applications with one configuration file for each.

## Web.config

Beyond the standard [Web.config](https://msdn.microsoft.com/en-us/library/ff400235\(v=vs.100\).aspx) settings handled by IIS, Wisej.NET supports:

* **`Wisej.LicenseKey`**

  The **server license key** required to activate the server. Located under `appSettings`.
* **`Wisej.DefaultTheme`**

  The default theme name (without extension: e.g. Blue-1) used by the Wisej.NET Designer and all project applications. Each application can override this in its JSON configuration file. Located under `appSettings`.
* **`<compilation debug="true" targetFramework="4.8">`**

  Wisej.NET reads the "debug" value to determine javascript library minification. When debug is `false`, Wisej.NET automatically bundles and minifies all required javascript libraries, including core libraries, extension libraries, and custom application libraries.

Wisej.NET requires the module and handler settings in `Web.config`. We recommend increasing allowed content size to maximum:

```markup
<system.webServer>
    <modules>
      <add name="Wisej" type="Wisej.Core.HttpModule, Wisej.Framework"/>
    </modules>
    <handlers>
      <add name="wx" verb="*" path="*.wx" type="Wisej.Core.HttpHandler, Wisej.Framework"/>
    </handlers>
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="1073741824"/>
      </requestFiltering>
    </security>   
    ...
</system.webServer>

  <system.web>
    <httpRuntime targetFramework="4.6" maxRequestLength="1048576"/>
    <compilation debug="true" targetFramework="4.6">
      <assemblies>
      </assemblies>
    </compilation>
  </system.web>
```

All default Wisej.NET settings are predefined in the `Web.config` file added by Wisej.NET project templates.

## Default.json

Each Wisej.NET application defines its configuration using JSON format. The default application uses `Default.json`.

Configuration settings explained:

* **`startup`**

  Full name of the startup static method. Example: "*MyApp.Program.Main, MyApp*". Wisej.NET calls this when creating a new session. Define either a simple method without arguments or one with a single `NameValueCollection` argument to receive URL arguments. Optional - you can use `mainWindow` instead. If defined, you must create a component to show the user in the Main method: a main page, desktop, or window.

{% tabs %}
{% tab title="C#" %}

```csharp
static class Program
{
    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    static void Main()
    {
      var form1 = new Form1();
    }

    // 
    // You can use the entry method below
    // to receive the parameters from the URL in the args collection.
    // 
    //static void Main(NameValueCollection args)
    //{
    //}
}
```

{% endtab %}

{% tab title="VB.NET" %}

```visual-basic
Public Module Program

	''' <summary>
	''' The main entry point for the application.
	''' </summary>
	''' <remarks></remarks>
	Public Sub Main()

		Application.MainPage = New Page1()

	End Sub

	' ''' <summary>
	' ''' You can use the entry method below
	' ''' to receive the parameters from the URL in the args collection.
	' ''' </summary>
	' ''' <param name="args"></param>
	' ''' <remarks></remarks>
	'Public Sub Main(args As NameValueCollection)

	'End Sub

End Module
```

{% endtab %}
{% endtabs %}

* **`mainWindow`**

  Full name of a view (Page or Form) created at startup. Example: "*MyApp.MainView, MyApp*". Wisej.NET automatically loads, creates, and shows the window class - either a `Wisej.Web.Form` or `Wisej.Web.Page`.

  If both `startup` and `mainWindow` are specified, Wisej.NET creates the main window and calls the startup method.
* **`theme`**

  Theme name to load at startup (without extension). Optional - overrides the `Web.config` theme setting at runtime.
* **`url`**

  The application's page URL. Optional - if omitted, users must type the page URL (e.g., <http://server.com/admin.html>), unless using Default.html with `defaultDocument` in `Web.config`.

  When specified, users can type the application name without extension (e.g., <http://server.com/admin>).
* **`allowedResourceTypes`** <mark style="color:green;background-color:green;">Since 4.0.8</mark>

  Comma-separated list of allowed embedded resources in addition to the built-in types. Example: "pdf,docx,myfile".
* **`allowedRoutes`**

  Defines URL routes separated by semicolons. Example: "api;admin;query/users".

  When specified, the application processes the main URL and child paths starting with specified routes. URL changes trigger the `Application.ApplicationRefresh` event. Check current URL using `Application.Url`.

{% hint style="danger" %}
allowedRoutes has a known issue with applications having a "." in the project or solution name.
{% endhint %}

* **`debug`**

  Enables logging to client browser console. Default: `false`. When enabled, Wisej.NET logs events in the browser's console.
* **`culture`**

  Application's default culture. Default: "auto" (detects browser culture).

  Specify a [language](https://msdn.microsoft.com/en-us/library/ee825488\(v=cs.20\).aspx) to override browser/OS settings.
* **`rightToLeft`**

  Controls Right to Left mode. Default: "auto". Set `true` to force RTL mode, "auto" to detect from current culture. See [RightToLeft](https://docs.wisej.com/docs/concepts/righttoleft).
* **`sessionTimeout`**

  Session timeout in seconds. Default: 120. Minimum: 60.

  Time without user activity before firing `Application.SessionTimeout`. If unhandled, shows built-in timeout countdown window.

  **Note:** Session expiration occurs either when the timeout window completes or after **twice** the `sessionTimeout` value (minimum 60 seconds).

  Handle `Application.SessionTimeout` with `e.Handled = true` to prevent expiration. Use `Application.Exit()` to terminate manually.

{% hint style="danger" %}
`Application.ApplicationExit` is the only event fired on session expiration - this is unrecoverable as the session is already terminated.
{% endhint %}

* **`sessionStorage`**

  Session ID storage location: "local" (`localStorage`) or "session" (`sessionStorage`). Default: "session".

  * "session": Clears when browser closes, abandoning user session
  * "local": Persists in browser storage, attempts session restoration on browser reopen

{% hint style="danger" %}
"local" storage limits browser to 1 session, sharing across tabs/windows. Wisej.NET refreshes tabs on activation to ensure latest state.
{% endhint %}

* **`responseTimeout`**

  Wisej.NET ajax request timeout in seconds. Default: 300. Minimum: 300.

  Increase for applications with long-running task responses to prevent timeouts.

{% hint style="info" %}
Only applies to initial load with WebSocket connections, as WebSocket doesn't timeout.
{% endhint %}

* **`pollingInterval`**

  Automatic polling interval in milliseconds. Default: 0 (disabled). Minimum: 1000.

  Ignored with WebSocket connections. Use `Application.StartPolling` and `Application.EndPolling` for manual polling control.
* **`autoReload`**

  Automatically reloads application on session expiration or `Application.Exit()`. Default: `false`.
* **`secure`**

  Forces SSL usage. Default: `false`. Changes HTTP to HTTPS and WebSocket to WSS protocol.
* **`impersonate`**

  Enables automatic user identity impersonation at request start. Default: `false`.

  Use with `<authentication mode="Windows">` for user credential resource access.
* **`showLoader`**

  Controls Wisej.NET ajax loader display. Default: `true`. When `false`, shows HTML content during library loading.
* **`loader`**

  Name of the loader resource (i.e. gif, svg, png) to show at startup to replace the built-in loader.
* **`loaderTimeout`**

  Ajax loader appearance delay in milliseconds. Default: 5000. Set 0 to disable.

{% hint style="info" %}
Ajax loader gif uses themed image named "ajax-loader".
{% endhint %}

* **`notAvailableUrl`**

  URL for page shown when server cannot create new session. Default: "resource.wx/NotAvailable.html,Wisej.Core".

  Wisej.NET checks `maxSessions` value and license concurrent user limits.
* **`notSupportedUrl`**

  URL for page shown when browser is unsupported. Default: "resource.wx/NotSupported.html,Wisej.Core".

  Wisej.NET verifies `XMLHttpRequest` support and custom checks via `browserCheck`.
* **`browserCheck`**

  Custom javascript expression returning `true` for supported browsers. Example:

```javascript
"browserCheck": "navigator.platform == 'Win32'"
```

* **`enableWebSocket`**

  Enables WebSocket connections when supported. Default: `true`.
* **`webSocketCompressionThreshold`** <mark style="color:green;background-color:green;">Since 3.5.5</mark>

  Response size (bytes) triggering server-side compression. Default: 2048. Use -1 to disable, 0 to always compress.
* **`maxSessions`**

  Maximum concurrent active sessions before redirecting to `notAvailableUrl`. Default: -1 (unlimited).

{% hint style="info" %}
Setting `maxSessions` to 0 disables the application, always redirecting to `notAvailableUrl`.
{% endhint %}

* **`maxModalStack`**

  Maximum nested modal states (dialogs/message boxes). Default: 10.
* **`validateClient`**

  Enables client request validation using browser's unique client ID. Default: `true`. Helps prevent session hijacking.
* **`validateResources`** <mark style="color:green;background-color:green;">Since 3.5.5</mark>

  Verifies that resource requests are received from the user's authorized browser. Prevents reusing a resource URL from an unauthorized requests. Default: `false`.&#x20;

{% hint style="warning" %}
When `validateResources` is `true`, requests not coming from the client receive 404 response. Be aware that external viewers/processors (e.g., Google Doc PDF Viewer) will not be able to download any document from the application.
{% endhint %}

* **`maxSessionsPerClient`**  <mark style="color:green;background-color:green;">Since 3.5.23</mark>

  Limits the number of sessions that can be associated with a client. Use this configuration
  &#x20;option to protect again potential [DoS attacks](https://docs.wisej.com/docs/security#dos-attacks) attempting to flood a server with session requests. Default 0 (unlimited).

{% hint style="danger" %}
`maxSessionsPerClient` offers only basic, secondary protection. It **cannot fully prevent DoS/DDoS attacks**. Real DoS protection must be handled at the **network or server infrastructure level**, which is **outside the scope of any web framework**.
{% endhint %}

* **`dropDuplicateClicks`**

  Drops "execute" client events during pending requests. Default: `false`. Prevents multiple executions from rapid clicking while maintaining other pointer events.
* **`disableClientObjectModel`**

  Prevents creation of [JavaScript Object Model](https://docs.wisej.com/docs/concepts/javascript-object-model) for named controls. Default: `false`.
* **`disableMinification`** <mark style="color:green;background-color:green;">Since 3.5.7</mark>

  When true, dynamic minification is turned off also in release mode. Default: `false`.
* **`enablePWA`**

  Includes built-in worker process javascript in initial loader. Default: `false`. Preloads/caches Wisej.NET core scripts and **\Offline** folder files.

  Use **PWA Application** template with `manifest.json` or add it to enable PWA support.
* **`offlineUrl`**

  Navigation URL on connection failure. Default: "". Set to "Offline/Default.html" with `enablePWA` for cached offline pages.

  When unset, shows localizable "Offline" toast on connection loss. See [Localization](https://docs.wisej.com/docs/concepts/localization).
* **`threadPool`**

  Configures thread pool without `machine.config` changes. Format: {minWorkerThreads, minCompletionPortThreads, maxWorkerThreads, maxCompletionPortThreads}. Uses system defaults for omitted values.

{% hint style="info" %}
Typically only adjust `minWorkerThreads` to CPU cores × expected simultaneous requests. Example: 120 for 12 cores handling 100 simultaneous requests from 1,000 users.
{% endhint %}

* **`embeddedResourcesCacheControl`** <mark style="color:green;background-color:green;">Since 2.5.23</mark>

  Cache-Control for embedded resources. Default: "browser" (1-month browser cache). Options:

  * "server": Server-side [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) caching
  * Custom [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) string (e.g., "private, max-age=600")
* **`options`**

  Platform-specific options map. Example: {debug: true, nativeScrollBars: true}. Recognized by client-side [qooxdoo](http://qooxdoo.org) framework.
* **`settings`**

  Custom application settings map. Example: {jquery: "<http://cdn>...", rootPath: "c:\users..."}. Access via `Application.Configuration.Settings`.

## \[Application Name].json

Additional Wisej.NET applications use their own configuration files named `[ApplicationName].json`, using the same settings described above.


---

# Agent Instructions: 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:

```
GET https://docs.wisej.com/docs/concepts/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.