Load Balancing

How to configure Load Balancing with Wisej.

Wisej applications are standard web applications and work very well with load balancers. However, Wisej goes a step further and gives you additional features to manage the load across several servers.

You can configure each server running a Wisej application to accept a maximum number of sessions, or to be available for the load balancer only if the CPU load is below a certain percentage and/or the memory usage is below a certain level.

Sticky Sessions

Wisej needs the requests from clients to always be routed to the same server instance. This is usually achieved by configuring your load balancer to either use Sticky Sessions, or another type of routing that guarantees that a specific server instance is assigned to a user.

Sticky Sessions is also called "Session Affinity".

There are several ways to configure the session affinity feature (sticky sessions):

  1. Cookie generated by the load balancer

  2. Cookie generate by the application and configure the load balancer to use that cookie

  3. Client IP hash

Refer to your load balancer documentation to learn how to enable Session Affinity.

Wisej generates a unique client fingerprint id to recognize the same client that creates a session. However, when concatenating load balancers the server may receive the request from different IPs causing the fingerprint check to fail and the loss of the session. To solve this problem, add "validateClient": false.


Most load balancers don't enable WebSocket support by default. You have to locate in the documentation how to turn on WebSocket support.

Wisej works perfectly well in HTTP-only mode, it just loses the ability to push updated to the client without a request initiated by the browser.

See PollingInterval and Application.StartPolling to learn how to emulate push updated in HTTP-only mode.


This is a unique feature only available in Wisej. Through the healthcheck.json file and the HealthCheck.IsServerAvailable callback you can control when to take a specific server offline or return it to service.

Failover works by returning the 503 Server Unavailable status at the very first HTTP request for the application's HTML page (usually Default.html): the server has to "fail" at the very first request for the failover feature in the load balancer to kick in and resubmit the request to the next server in the rotation.

To implement this feature, Wisej processes the first HTTP request and, before dispatching the request to the application, checks in order:

  1. Wisej.Core.HealthCheck.Enabled to verify that the healthcheck system is enabled.

    • The default in the built-in healthcheck.json file is false.

  2. The return value from Wisej.Core.HealthCheck.IsServerAvailable() as returned by the custom function that you may have installed.

  3. If HealthCheck.IsServerAvailable is null, it checks the MaxSessions, MaxMemory and MaxCPU values as configured in the application's HealthCheck.json or set by the code by assigning directly the values of the Wisej.Core.HealthCheck class.

If the final result is false, the server will return the error code configured in HealthCheck.ReturnCode (the default is 503 Server Unavailable).


Add a custom HealthCheck.json to your application using Add -> New Item -> Wisej 2 -> HealthCheck.

You can also create the file manually. The default file is created and initialized like this:

 * HealthCheck
 * Place the HealthCheck.json file in the /bin directory of the
 * application to enable the enhanced load balancing features.
 * Properties:
 *  enabled:      Enables the enhanced load balancing healthcheck.
 *  maxMemory:    Maximum percentage of allocated memory. Default: 70; 0 = unlimited.
 *  maxSessions:  Maximum number of active sessions: Default: 0; 0 = unlimited.
 *  maxCPU:       Maximum CPU load in percentage: Default: 100; 0 = unlimited.
 *  returnCode:   Http return code to signal that this server is not available. Default: 503.
 *  retryAfter:   Value for the Retry-After header in minutes. Default: 10.
 *  returnUrl:    Url to redirect the client when the server is not available. Default: null.
  "enabled": false,
  "maxSessions": 0,
  "maxMemory": 70,
  "maxCPU": 100,
  "returnCode": 503,
  "retryAfter": 10,
  "returUrl": null

Values set in HealthCheck.json are also available, to read and to write, in the static class Wisej.Core.HealthCheck.

Please note that in Wisej 3 the property maxMemory will change to represent an absolute value in MB.


This is a placeholder for a custom function that you can install simply by assigning the property to a function. Usually the best place is Program.Main, but you can assign it or change it at any time.

// Assign custom IsServerAvailable
Wisej.Core.HealthChecl.IsServerAvaiable = () => 
    // Add custom logic and return true (available) or false.
    return true;

Wisej will call this method before loading the application allowing your app to decide whether a particular server can take the incoming session.

Don't forget that most balancers don't support the failover feature. Refer to the load balancer's documentation.


Most load balancers use a "healthcheck" URL to probe whether a server is available in order to update their rotation list. Wisej provides a blank URL named healthcheck.wx that simply returns the 202 status.

When configuring your load balancer's healthcheck URL simply use your application's URL + "/healthcheck.wx".

Heathcheck.wx is the same URL used by the offline/online automatic detection in Wisej.

Last updated