Configuration

Wisej applications are standard Web Projects in Visual Studio. All the standard Web.config settings are valid.

In addition to Web.config, Wisej applications use individual configuration files using the JSON format. A single project can define multiple Wisej applications and one configuration file for each application.

Web.config

In addition to the standard Web.config settings that are mostly handled by IIS, Wisej supports:

• Wisej.LicenseKey

  This is the server license key that you have received required to activate the server. It is located under appSettings.

• Wisej.DefaultTheme

  This is the name of the default theme (without the extension: i.e. Blue-1) that is used by the Wisej Designer and by all the applications in the project. Each application can override the application's theme in its JSON configuration file - see below. It is located under appSettings.

• <compilation debug="true" targetFramework="4.8">

  Wisej reads the "debug" value of the <compilation> to determine whether to minify the javascript libraries. When debug is set to false, Wisej automatically bundles and minifies all the javascript libraries that are required by the application, including Wisej's core libraries, all extension libraries, and all custom libraries that may have been added by the application.

Wisej requires the module and the handler settings to be present in Web.config, and we recommend to increase the size of the allowed content to the maximum, as follows:

<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 the default Wisej settings in Web.config are predefined in the Web.config file added by the Wisej project templates.

Default.json

Each Wisej application in a project defines its own configuration file using the JSON format. The default application uses Default.json.

The explanation for each setting is also included in the template configuration file:

• startup

  Full name of the startup static method. i.e. "MyApp.Program.Main, MyApp". Wisej calls this method when a new session is created. You can define either a simple method without arguments or you can define a method with a single NameValueCollection argument that will receive the arguments typed after the application's URL. This setting is optional, you can use the mainWindow setting instead. If you define the startup method, it is your responsibility to create a component to show to the user in the Main method: a main page, or a desktop, or a 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 automatically at startup. i.e. "MyApp.MainView, MyApp". Wisej will automatically load, create, and show the window class. It can be either a Wisej.Web.Form or a Wisej.Web.Page.

  If both startup and mainWindow are specified, Wisej will create the main window and call the startup method.

• theme

  Name of the theme to load at startup, without the extension. This setting is optional and overrides the theme setting in Web.config at runtime.

• url

  The URL of the page that corresponds to the application. This setting is optional. If omitted, users have to type the page URL: i.e. http://server.com/admin.html, unless the application uses Default.html and has defined the defaultDocument in Web.config.

  When the URL setting is specified, users can type the name of the application without the extension and Wisej will load the HTML page specified: i.e.: http://server.com/admin.

• allowedRoutes

  Allows the application to recognize different URL routes separated by a semicolon. i.e. "api;admin;query/users".

  When the allowedRoutes property is specified, the application will process the main URL and any child path that starts with one of the specified routes. Any change to the URL will fire the Application.ApplicationRefresh event. The application can check the current URL using the property Application.Url.

allowedRoutes has a known issue that prevents applications with a "." in the project or solution name from working properly.

• debug

  Enables logging on the client browser console. Default: false. If you enable this setting, Wisej will log all sorts of events in the browser's console.

• culture

  The default culture of the application. Default: "auto" (or omitted) to detect the culture from the browser.

  If you want to force a specific language regardless of the language of the user's browser and OS, you can specify it using this setting.

• rightToLeft

  Enables or disables Right to Left mode. Default: "auto". Set to "true" forces the application to operate as if the current language was a right-to-left language. Set to "auto" (default) allows the application to automatically read the right-to-left mode from the current culture. See RightToLeft for more information.

• sessionTimeout

  Specifies the timeout of the session in seconds. Default: 120. Minimum: 60.

  This is the time that Wisej will wait (in seconds) when there is no activity from the user before firing the Application.SessionTimeout event. If the event is not handled by the application, Wisej displays the built-in timeout countdown window.

  This is not when the session expires. The session expires and it is removed (an unrecoverable event) either when the built-in timeout window reaches the end of the counter, or after twice the value of sessionTimeout (minimum 60 seconds).

  You can control what happens when the session times out by handling the Application.SessionTimeout. If you set e.Handled = true, the session will not expire. To terminate the session you have to explicitly call Application.Exit().

The only event fired when the session has expired and disposed it's Application.ApplicationExit. This is an unrecoverable event, at this point the session has already expired and the application terminated

• sessionStorage

  The location of the session ID can be "local" for localStorage or "session" for sessionStorage. Default: "session".

  When sessionStorage is set to "session" (default), the session ID is saved in the browser's sessionStorage which is cleared when the browser is closed, resulting in the abandonment of the user session.

  When sessionStorage is set to "local", the session ID is saved in the browser's localStorage which is never cleared. When the browser is reopened, it will try to restore the previous session. If the sessionTimeout is set to a value high enough (or to 0 = never expires), the user can open the application exactly where it left it when the browser was closed.

When using "local", the browser can only handle 1 session at a time resulting in the session being shared among browser tabs or browser windows. In this case, Wisej will automatically refresh the browser tab when it's activated to make sure that the state loaded in the browser is always the latest.

• responseTimeout

  Specifies the timeout of Wisej ajax requests in seconds. Default: 300. Minimum: 300.

  If your application may process long-running tasks in response to regular events (button clicks, for example) increase this value. Otherwise, Wisej may timeout while waiting for a response.

If the session is using WebSocket, this setting only applies to the initial load since the WebSocket connection doesn't time out.

• pollingInterval

  Interval for the automatic polling in milliseconds. Default: 0 (disabled). Minimum: 1000.

  This setting is ignored when the client is connected using a WebSocket connection. You can also call Application.StartPolling and Application.EndPolling when you want Wisej to periodically send poll requests to the server. Both methods are ignored when the client is using a WebSocket connection.

• autoReload

  When true, the application is automatically reloaded when the session expires or Application.Exit() is called. Default: false.

• secure

  Forces the client to use SSL. Default: false. When this setting is set to true, Wisej changes the request from HTTP to HTTPS. The underlying WebSocket connection (if available) also uses the wss: secure protocol.

• impersonate

  When set to true (default is false), Wisej will automatically impersonate the user identity at the start of every request.

  Use this option with <authentication mode="Windows"> to allow the server application to access resources using the user's credentials.

• showLoader

  Loads the Wisej ajax loader. Default: true. When this setting is set to false, Wisej will not show anything while it loads the startup libraries and shows the HTML content (if any) in the application's HTML page.

• loaderTimeout

  Timeout before the appearance of the Ajax loader in milliseconds. Default: 5000. Set to 0 to disable the automatic ajax loader.

The ajax loader gif is themed using the image named ajax-loader.

• notAvailableUrl

  URL of a page to display when the server cannot create a new session. Default: "resource.wx/NotAvailable.html,Wisej.Core" (built-in default page).

  Wisej checks the maxSessions value and the concurrent users limit set in the license.

• notSupportedUrl

  URL of a page to display when the browser is not supported. Default: "resource.wx/NotSupported.html,Wisej.Core" (built-in default page).

  Wisej checks that the browser supports at least XMLHttpRequest. In addition to this basic requirement, you can add a custom version-check javascript function using the browserCheck expression.

• browserCheck

  A custom javascript expression that returns true if the browser is supported, or false if it's not supported. The expression must be declared as a string and it can include regular expressions.

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

• enableWebSocket

  Enables WebSocket connections, if supported. Default: true.

• webSocketCompressionThreshold Since 3.5.5

  Size of the response (in bytes) that triggers the compression of the payload on the server. Default: 2048. A value of -1 disables the compression, while a value of 0 always compresses the response.

• maxSessions

  The maximum number of active sessions (users) before redirecting to NotAvailableUrl. Default: -1 (unlimited).

Setting maxSessions to 0 disables the application and always redirects to NotAvailableUrl.

• maxModalStack

  The maximum number of nested modal states (dialogs and message boxes). Default: 10.

• validateClient

  Enables the validation of client requests using the browser's unique client id generates by Wisej. Default: true. Validating the client minimizes the risk of session hijacking. Default: true.

• validateResources Since 3.5.5

  Enables the validation of image, downloads, and resource requests (i.e. pdf files) blocking requests not coming from the same browser. Default: false.

When validateResources is set to true, all requests not coming from the user's browser receive the response code 404 (not found). If your application uses external viewers or document processors (i.e. Google Doc Pdf Viewer) they will stop working.

• dropDuplicateClicks

  When set to true, Wisej will drop all “execute” client events while there is a pending request. The “execute” events generate Click events on the server and are usually related to the execution of business logic. This option minimizes the that users keep clicking a button and cause the multiple execution of the same action. All other pointer events are still queued and executed. Default: false.

• disableClientObjectModel

  When set to true, Wisej will NOT create the JavaScript Object Model that corresponds to the server-side controls with a valid name. Default: false.

• enablePWA

  When set to true, Wisej will include a request for the built-in worker process javascript in the initial loader. The worker process script is created and cached dynamically to preload and store locally the core Wisej scripts and all the files in the \Offline folder inside the application. Default: false.

  Use the new PWA Application project template with the required manifest.json file or add a manifest.json to an existing application in order to properly enable PWA support.

• offlineUrl

  Sets the URL to navigate to when the connection to the application fails. If you set it to Offline/Default.html and enablePWA is set to true, it will show the offline pages that are pre-cached locally using the PWA service worker. Default: "".

  When offlineUrl is not set, and the application loses connectivity, Wisej will show a localizable simple Wisej.Web.Toast widget at the top with the text "Offline", localizable using the $Offline key in the resource file. See Localization.

• threadPool

  Allows a Wisej application to configure the thread pool without having to modify the machine.config file or to add startup code that changes the ThreadPool. The value is a map: {minWorkerThreads, minCompletionPortThreads, maxWorkerThreads, maxCompletionPortThreads}. All values are options. If omitted, Wisej will use the default values from the system.

Usually, you only need to set the minWorkerThreads value to a multiple of the CPU cores that is closer to the number of simultaneous requests that you expect to receive.

For example, if you have 1,000 users and want to improve the performance of the server when it receives 100 simultaneous requests, we suggest setting minWorkerThread to 120 on a 12-core CPU.

• embeddedResourcesCacheControl Since 2.5.23

  Cache-Control for embedded resources. The default is "browser" to cache the embedded resources on the browser for 1 month. Other allowed values are: "server" to cache the resource on the server using the ETag cache header, or any other valid Cache-Control string (i.e.: "private, max-age=600").

• options

  Map of platform-specific options. i.e. {debug: true, nativeScrollBars: true, ...} These are options that are recognized by the client-side javascript platform, and specifically the qooxdoo web framework.

• settings

  Map of application settings. i.e. {jquery: "http://cdn...", rootPath: "c:\\users\\...", ...} These are custom settings that you can handle in your application using Application.Configuration.Settings.

[Application Name].json

Additional applications in a Wisej project use their own configuration file using the application name and the json extension.

The settings are the same described in the previous section.