Class

WebApplication

Description

WebApplication is the base class for web apps. It stores information about the app such as its version number, the name of the built app, the ports it uses, etc. A Web app project has an object called App whose super class is WebApplication.

Events

Name

Parameters

Returns

Closed

HandleURL

Request As WebRequest, Response As WebResponse

Boolean

Opening

args() As String

Pausing

Resumed

Stopping

shuttingDown As Boolean

UnhandledException

error As RuntimeException

Boolean

Property descriptions

WebApplication.AcceptingConnections

AcceptingConnections As Boolean

Allows you to Start/Stop a web app's ability to accept connections. Setting this property to False will stop the server(s) and disconnect all active sockets immediately.

Stop allowing connections:

App.AcceptingConnections = False

WebApplication.ApplicationIdentifier

ApplicationIdentifier As String

A unique string to identify your WebApplication. Typically written in reverse domain name order: com.example.webappname.

This property is read-only.

Note

ApplicationIdentifier must be specified in order for your web app to work.

WebApplication.AutoQuit

AutoQuit As Boolean

If True, the server will shutdown automatically when all sessions have ended, which is the default when running from the debugger. If False, the server will not shutdown. This is the default for deployed web apps.

In the App.Opening event handler, you can change this behavior:

App.AutoQuit = False

WebApplication.AutoQuitTimeout

AutoQuitTimeout As Integer

The number of seconds after the last WebSession ends that the application will quit. The default value is 60.

This property is read-only.

The web app is only quit if AutoQuit is True.

Change the timeout to 30 seconds:

App.Timeout = 30

WebApplication.BugVersion

BugVersion As Integer

The Bug version of the ConsoleApplication. This can only be set in the IDE, but you can read the value in your code.

This property is read-only.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Put all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = MajorVersion.ToString + "." + MinorVersion.ToString + "." + BugVersion.ToString + "." + NonReleaseVersion.ToString

WebApplication.Copyright

Copyright As String

Copyright information of the DesktopApplication.

This property is read-only.

Copyright usually contains the application name, version number and copyright information.

Logs the app version:

System.DebugLog("Copyright: " + App.Copyright)

WebApplication.Description

Description As String

The description of the application, corresponding to the version information.

This property is read-only.

This property can be set only in the IDE.

WebApplication.ExecutableFile

ExecutableFile As FolderItem

Points to the actual executable file even if it is inside a bundle.

This property is read-only.

To get the app executable name:

Var appName As String = App.ExecutableFile.Name

WebApplication.HTMLHeader

HTMLHeader As String

The HTML in the Header area. This property is design-time only. The developer can read the value of the property in code, but cannot change it.

This property is read-only.

WebApplication.LastSessionIndex

LastSessionIndex As Integer

The index of the last active session.

This property is read-only.

WebApplication.MajorVersion

MajorVersion As Integer

The major version of the ConsoleApplication, corresponding to the version information. The range is from 0 to 255. This can only be set in the IDE, but you can read the value in your code.

This property is read-only.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Put all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = MajorVersion.ToString + "." + MinorVersion.ToString + "." + BugVersion.ToString + "." + NonReleaseVersion.ToString

WebApplication.MinorVersion

MinorVersion As Integer

Minor version of the ConsoleApplication, corresponding to the version information. The range is from 0 to 255. This can only be set in the IDE, but you can read the value in your code.

This property is read-only.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Put all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = MajorVersion.ToString + "." + MinorVersion.ToString + "." + BugVersion.ToString + "." + NonReleaseVersion.ToString

WebApplication.NonReleaseVersion

NonReleaseVersion As Integer

The NonRelease version of the ConsoleApplication, corresponding to the version information. Sometimes referred to as the build number. This can only be set in the IDE, but you can read the value in your code.

This property is read-only.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

If AutoIncrementVersionInformation is checked, the IDE increases NonReleaseVersion by one each time you build your project, but not when you run it.

Put all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = MajorVersion.ToString + "." + MinorVersion.ToString + "." + BugVersion.ToString + "." + NonReleaseVersion.ToString

WebApplication.Port

Port As Integer

The port number used to communicate with the standalone web app when it is built and deployed.

This property is read-only.

In addition to being set in the Build Settings for the web app, this value can also be set at launch time by appending the --port command line parameter.

Usage: MyApp --port=9000

On macOS and Linux, port numbers below 1024 (including the common port 80) require elevated permissions, so you will have to start the web app using the "sudo" command.

WebApplication.RegionCode

RegionCode As Integer

The Region Code of the application, corresponding to the version information. Not supported on Windows. This property can be set only in the IDE.

This property is read-only.

WebApplication.Security

Security As WebSecurityOptions

Controls whether or not a web app can appear in an <iframe> tag on another html page or allows you to change the SSL connection type that is used.

This property is read-only.

The following enumerations can be used to set the FrameOption property:

Name

Description

WebAppSecurityOptions.FrameOptions.Deny

Does not allow a web application to appear in an <iframe> in another html page, regardless of the domains involved.

WebAppSecurityOptions.FrameOptions.Allow

Allows a web application to appear in an <iframe> of another html page, regardless of its domain.

WebAppSecurityOptions.FrameOptions.SameOrigin

(Default) Allows the web application to appear in an <iframe> of another html page, as long as the domains exactly match.

To change the ConnectionType property:

Enumeration

Description

WebAppSecurityOptions.ConnectionTypes.SSLv23

A TLS/SSL connection established with this enum may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. If extensions are required (for example server name) a client will send out TLSv1 client hello messages including extensions and will indicate that it also understands TLSv1.1, TLSv1.2 and permits a fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best choice when compatibility is a concern.

WebAppSecurityOptions.ConnectionTypes.TLSv1

TLS (Transport Layer Security) version 1.

WebAppSecurityOptions.ConnectionTypes.TLSv11

TLS (Transport Layer Security) version 1.1

WebAppSecurityOptions.ConnectionTypes.TLSv12

(Default) TLS (Transport Layer Security) version 1.2

Prior to 2014r3, the default behavior was equivalent to WebAppSecurityOptions.FrameOptions.Allow. If you need to restore that behavior, you can add the code from the example below to your project.

In 2014r2, this value was hard coded to the equivalent of WebAppSecurityOptions.FrameOptions.SameOrigin, but was reverted to the previous behavior in 2014r2.1.

By default, the ConnectionType uses TLSv12.

To allow a web app to appear in an <iframe> on any web page from any server, you can set the Allow option in the Opening event of the app:

Self.Security.FrameEmbedding = WebAppSecurityOptions.FrameOptions.Allow

To use an older connection type (not recommended):

Self.Security.ConnectionType = WebAppSecurityOptions.ConnectionTypes.TLSv1

WebApplication.SessionTimeout

SessionTimeout As Integer

The number of seconds after a browser disconnects that the session will actually be removed from memory. The default is 180.

This property is read-only.

This is the period of time that a Session stays around to avoid the overhead of starting up a new Session, should the user come "right back". Use this property to adjust this time up or down based on your system and user requirements. It should not be set too low. Since it defines the amount of time that passes since the last communication from the browser to when the Session is actually closed, setting it too low could disconnect active users.

In most cases you should not need to change this property.

WebApplication.SSLPort

SSLPort As Integer

The port number that will be used to communicate securely with the web app.

This property is read-only.

SSL options are only valid for stand-alone web apps. The Certificate must be located next to the app and its name must match the app name. For example, if the web app is called "MyApp" then the certificate must be called "MyApp.crt".

If you are setting this in code, be sure to set it in the Opening event handler.

The SSLPort value can also be set at launch time by appending the --secureport command line parameter.

Usage:

MyApp --secureport=9000

WebApplication.StageCode

StageCode As Integer

Stage Code of the application, corresponding to the version information.

This property is read-only.

Use the four Application class constants to set/get the Stage. Stage can be set only in the IDE.

Value

Description

0

Development

1

Alpha

2

Beta

3

Final

WebApplication.Version

Version As String

Version of the ConsoleApplication.

This property is read-only.

This property can be set only in the IDE.

Typically version numbers are written as 1.2.3.4.

Version is displayed by the file information windows on macOS (Finder, Get Info) and Windows (Windows Explorer, Properties).

Method descriptions

WebApplication.Daemonize

Daemonize As Boolean

Converts the app from a regular console app to a daemon process that runs in the background on macOS or Linux.

Since daemonized console apps cannot be run from the IDE, you should build and test as a non-daemonized console app and then daemonize it when you build. Use System.Log to handle debugging.

Although you can also use the Daemonize method on macOS, Apple would rather you use launchd to start daemon processes.

To create a background console application on Windows, you need to use ServiceApplication.

A typical use of the Daemonize method is as follows:

#If Not DebugBuild Then ' Do not try to daemonize a debug build
If (args(1) = "start" Or args(1) = "-d") Then ' Check for command-line parameter to daemonize
  If Not App.Daemonize Then
    System.Log(System.LogLevelCritical, "Could not daemonize the app.")
    Return -1
  End If
End If
#Endif

WebApplication.DefaultPage

DefaultPage As WebPage

Returns the page set via the Default Web Page popup menu in the Inspector. This page is displayed each time a new session is created.

WebApplication.DoEvents

DoEvents(milliseconds As Integer = 10)

Yields time back to your app so that it can handle other events.

' In the Run event of your console application

Var consoleTimer As New MyTimerSubclass
consoleTimer.RunMode = Timer.RunModes.Multiple  ' Don't forget this one
consoleTimer.Period = 1000  ' Call every second

Do
  App.DoEvents
Loop

WebApplication.Quit

Quit(errorCode As Integer = 0)

Quits the web app.

Works the same as calling the global Quit method.

WebApplication.SessionAt

SessionAt(index As Integer) As Session

The WebSession referred to by the passed Index.

This code in a Button on a page will display a Message Box on the current page for all connected Sessions:

For i As Integer = 0 To App.SessionCount - 1
 Var sessionContext As New WebSessionContext(App.SessionAt(i))
 MessageBox("The app will be shutting down in 5 minutes.")
Next

WebApplication.SessionCount

SessionCount As Integer

Returns the number of active sessions.

Each session corresponds to a user that is connected to the web app. Each session uses 2 or more sockets. Typically 4 sockets are used when setting up the initial session and then 2 sockets are used thereafter.

By default a web app allows for a maximum of 200 sockets. This means a maximum of 50 to 100 users can be connected to a web app at one time, presuming the app is not doing significant processing and you have enough RAM on the server. If you want to enable additional concurrent users you can increase the maximum sockets using the command-line options described on the WebApplication page like this: MyApp --MaxSockets=300

If you are using SSL, you'll need to set the maximum secure sockets with a command like this: MyApp --MaxSecureSockets=300

This code in a Button on a page will display a Message Box on the current page for all connected Sessions:

For i As Integer = 0 To App.SessionCount - 1
  MessageBox("App shutdown.")
Next

WebApplication.SessionForControl

SessionForControl(ctl As WebControl) As Session

The WebSession referred to by the passed WebControl.

WebApplication.SessionForControlID

SessionForControlID(controlID As String) As Session

The WebSession referred to by the passed ControlID.

WebApplication.Sessions

Sessions As Iterable

Allows you to iterate through all the active sessions.

This example adds to a WebListBox the name of the current page for each active session:

For Each activeSession As WebSession In App.Sessions
  ListBox1.AddRow(activeSession.CurrentPage.Name)
Next

WebApplication.SessionWithIdentifier

SessionWithIdentifier(identifier As String) As Session

The WebSession referred to by the passed Identifier. A session identifier can be obtained from WebSession.Identifier.

Starting with 2015r4, Sessions are not disconnected when changing networks. This means that IP addresses are no longer associated with Sessions.

Event descriptions

WebApplication.Closed

Closed

The web app has closed.

Session is not available from this event handler.

WebApplication.HandleURL

HandleURL(Request As WebRequest, Response As WebResponse) As Boolean

This event fires when an http request comes to your app which would otherwise result in a 404 Page Missing response.

Return a custom 404 page:

' Don't override an empty request, or a session won't start.
If Not Request.Path.IsEmpty Then
  ' First, create the HTML answer
  Response.Write "<body>"
  Response.Write "Oops! You took a wrong turn. "
  Response.Write "Please put it in reverse and try again."
  Response.Write "</body>"

  ' Set the status code. The default value is 404,
  ' but if you leave it that way, some browsers
  ' will show their own. A value of 200 will make
  ' the browser show your text instead.
  Response.Status = 200

  ' You MUST return True if you want to override the output.
  Return True
End If

WebApplication.Opening

Opening(args() As String)

The web app has launched and is starting. The command-line parameters used to start the web app are in args.

Session is not available from this event handler.

You can add or modify the provided arguments by changing the contents of the args parameter.

For example, to increase the number of sockets:

args.Add("MaxSockets=300")

WebApplication.Pausing

Pausing

Occurs when the user selects Pause from the Service Control Manager on Windows.

When the user selects Pause, they expects the service to stop performing whatever action it was doing. It should continue to halt execution until the Resumed event is fired.

WebApplication.Resumed

Resumed

Occurs when the user selects Continue from the Service Control Manager on Windows, assuming that a Pausing event has already occurred.

The Resumed event is not called unless the WebApplication is paused. Use this event to continue running your WebApplication.

WebApplication.Stopping

Stopping(shuttingDown As Boolean)

Occurs in two situations: When the user selects Stop from the Service Control Manager on Windows or when the computer is shutting down.

If the user selected Stop, ShuttingDown is False.

If the computer is shutting down, ShuttingDown is True. This event occurs when you call the Quit method on any platform or when the service terminates. The ShuttingDown parameter is supported only on Windows.

WebApplication.UnhandledException

UnhandledException(error As RuntimeException) As Boolean

If a RuntimeException is not caught anywhere else (using Exception or Try), this event is called so you may handle the exception. Return True to suppress the quit behavior. Return False to use the default quit behavior.

If a RuntimeException is not caught anywhere else, this event is called so you may handle the exception. See the example.

This code in the UnhandledException event of the App class catches any unhanded exceptions and displays the name of the exception along with the error stack:

If error <> Nil Then
  Var type As String = Introspection.GetType(error).Name
  MessageBox(type + EndOfLine + EndOfLine + String.FromArray(error.Stack, EndOfLine))
End If

Notes

App quit defaults:

  • Apps do not quit unless the Quit method is called (AutoQuit can be used to change this default).

Session is not available from WebApplication event handlers.

Note

ApplicationIdentifier must be specified in order for your web application to work.

Command-line parameters

When starting a stand-alone web application, you can supply these parameters on the command line:

Command

Description

--port

The port the web app listens to for a connection. This can be used to change the port that was used to build the web app.

--MaxSockets

The maximum number of allowed connected sockets. The default is 200. This is not the number of maximum users as the number of connections does not map one-to-one with the number of connected users. Do not set the value too high as it will increase memory and CPU usage.

--MinSockets

The minimum number of allowed connected sockets. The default is 20.

--SecurePort

The port the web app listens to for a secure connection. This can be used to change the port that was used to build the web app.

--SslType

(Available in 2016r1) Allows you to specify the type of security used. You can use these integer values: 3 (TLSv1), 4 (TLSv11), 5 (TLSv12, the default)

--MaxSecureSockets

The maximum number of allowed secure connected sockets. This is not the number of maximum users as the number of connections does not map one-to-one with the number of connected users. Do not set the value too high as it will increase memory and CPU usage.

--NetworkInterfaceIndex

The index value (of NetworkInterfaces) to use as the NIC for connections. 2017r2 or later also accept the value "Loopback" to allow listening only on the loopback interface.

--SecureNetworkInterfaceIndex

(Available with 2017r2) The index value (of NetworkInterfaces) to use as the NIC for secure connections. 2017r2 or later also accept the value "Loopback" to allow listening only on the loopback interface.

--Certificate

The path to the SSL certificate (available in 2015r2).

--Logging

The path to HTTP Log file.

--UploadPath

Changes the default path used to save files that are uploaded or other large requests. (New in 2020r1)

--urllength

Allows you to change the maximum number of characters allowed in a URL from 256 (the default) to a maximum of 2048.

Using ssl with standalone web apps

Refer to the SSL for Web Apps topic for more details on how to set up a web app with SSL.

Compatibility

Web projects on all supported operating systems.

See also

ServiceApplication parent class; WebSession, Session, WebPage classes; App function; Web Application Structure, SSL for Web Apps topics