Load Balancing

The features described on this page may not be available for all Wisej.NET Server license editions. For more details, please review the license details.

Wisej.NET applications are standard web applications that work seamlessly with load balancers.

However, Wisej.NET goes a step further and gives you additional features to manage the load across several servers. You can configure each server running a Wisej.NET application to accept a 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.

Wisej.NET applications use WebSocket connections, which may require configuring your load balancer for TCP rather than HTTP routing. More details below.

Prepare your Wisej.NET App

Preparing Wisej.NET apps for load balancing mainly involves configuring healthcheck parameters. These determine when a server instance should return an error code signaling the load balancer to route requests elsewhere.

To configure healthcheck:

1. Use Add New Item and select Healthcheck from templates, or

2. Copy the configuration settings below, or

3. Download the default HealthCheck.json

Place the file in your application's root folder and set "Copy to Output Directory" to "Copy if newer". The file must be in the /bin directory to be recognized.

/**
 * Health Check
 *
 * You can modify the default health check configuration by
 * placing a HealthCheck.json file in the /bin directory of the
 * application.
 *
 * HealthCheck Properties:
 *
 *  maxMemory:    Maximum percentage of allocated memory. Default: 70; 0 = skip.
 *  maxSessions:  Maximum number of active sessions: Default: 100; 0 = skip.
 *  maxCPU:       Maximum CPU load in percentage: Default: 100; 0 = skip.
 *  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.
 */
{
    "enabled": true,
    "maxMemory": 70,
    "maxSessions": 100,
    "maxCPU": 100,
    "returnCode": 503,
    "retryAfter": 10
}

920B

HealthCheck.json

Configuration

Wisej.NET requires client requests to route consistently to the same server instance. Configure your load balancer to use either:

• Sticky Sessions

• Other routing that ensures user-server instance consistency

Some load balancers need TCP mode configuration for WebSocket connections. Reverse proxies like NGINX have built-in WebSocket support - see NGINX as a WebSocket Proxy.

Session

Wisej.NET requires load balancer session affinity: each user/session must route to the same server. This typically uses:

• Sticky session cookies

• Client IP hash

• Other consistent routing methods

Healthcheck

Load balancers periodically verify server instance availability using a "healthcheck" URL. Options:

• Custom HTML/ASPX page

• healthcheck.wx to verify Wisej.NET routing component status

HealthCheck.json

Wisej.NET applications automatically respond to initial Default.html (or subapplication URL) requests by either returning the page or returning "503 Service Unavailable" (configurable in HealthCheck.json).

The following properties in HealthCheck.json control server availability. Wisej.NET uses all configured properties in this order:

maxSessions

Maximum live sessions a Wisej.NET server can accept before refusing more. Returns "503 Service Unavailable" (or HTML page from Default.json) to new users instead of risking server overload.

Set to 0 to disable this check.

maxMemory

Maximum memory percentage before returning "503 Service Unavailable". Example: Value 70 means the server returns 503 when memory usage is 70% or higher during main page request.

Set to 0 to disable this check.

maxCPU

Maximum CPU load percentage before returning "503 Service Unavailable". Example: Value 100 means the server returns 503 when CPU usage is 100% during main page request.

Set to 0 to disable this check.

returnCode

HTTP status code returned by /healthcheck.wx when server can't accept new sessions. Default is 503. See Status Code Definitions.

503: The server is currently unable to handle the request due to temporary overloading or maintenance. This condition should be temporary. If known, the delay length MAY be indicated in a Retry-After header. Without Retry-After, the client SHOULD handle the response as a 500 response.

retryAfter

Minutes value for the Retry-After header sent with "503 Service Unavailable" response.

Note: Most load balancers currently ignore this header.

HealthCheck.IsServerAvailable

You can install a custom static method called by the healthcheck handler. Return true if the server should be available to the load balancer, false to return 503 (unavailable).

The IsServerAvailable method can check any values to determine server availability:

static class Program 
{
    // static constructor
    static Program() 
    {
        Wisej.Core.HealthCheck.IsServerAvailable = Program.IsServerAvailable;
    }

    static bool IsServerAvailable() 
    {
        // this server can be used only on Mondays...
        return DateTime.Now.DayOfWeek == DayOfWeek.Monday;
    }
}