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

<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.

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)
    //{
    //}
}

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

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).
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.

allowedRoutes has a known issue with applications having a "." in the project or solution name.

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 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.
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.

Application.ApplicationExit is the only event fired on session expiration - this is unrecoverable as the session is already terminated.

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

"local" storage limits browser to 1 session, sharing across tabs/windows. Wisej.NET refreshes tabs on activation to ensure latest state.

responseTimeout
Wisej.NET ajax request timeout in seconds. Default: 300. Minimum: 300.
Increase for applications with long-running task responses to prevent timeouts.

Only applies to initial load with WebSocket connections, as WebSocket doesn't timeout.

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.
loaderTimeout
Ajax loader appearance delay in milliseconds. Default: 5000. Set 0 to disable.

Ajax loader gif uses themed image named "ajax-loader".

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:

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

enableWebSocket
Enables WebSocket connections when supported. Default: true.
webSocketCompressionThreshold Since 3.5.5
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).

Setting maxSessions to 0 disables the application, always redirecting to notAvailableUrl.

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 Since 3.5.5
Validates image, download, and resource requests. Default: false. Blocks non-browser requests.

When validateResources is true, non-browser requests receive 404 response. External viewers/processors (e.g., Google Doc PDF Viewer) will not work.

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 for named controls. 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.
threadPool
Configures thread pool without machine.config changes. Format: {minWorkerThreads, minCompletionPortThreads, maxWorkerThreads, maxCompletionPortThreads}. Uses system defaults for omitted values.

Typically only adjust minWorkerThreads to CPU cores × expected simultaneous requests. Example: 120 for 12 cores handling 100 simultaneous requests from 1,000 users.

embeddedResourcesCacheControl Since 2.5.23
Cache-Control for embedded resources. Default: "browser" (1-month browser cache). Options:
- "server": Server-side ETag caching
- Custom Cache-Control string (e.g., "private, max-age=600")
options
Platform-specific options map. Example: {debug: true, nativeScrollBars: true}. Recognized by client-side qooxdoo 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.

PreviousStartup NextLoad Balancing

Last updated 4 days ago