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.

C#

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

VB.NET

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.