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.
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
milliseconds As Integer = 10 |
|||
index As Integer |
|||
ctl As WebControl |
|||
controlID As String |
|||
identifier As String |
|||
milliseconds as Integer |
|||
Events
Name |
Parameters |
Returns |
---|---|---|
Request As WebRequest, Response As WebResponse |
||
args() As String |
||
shuttingDown As Boolean |
||
error As RuntimeException |
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
WebApplication.AutoQuitTimeout
AutoQuitTimeout As Integer
WebApplication.BaseURL
BaseURL As String
The application will use the specified folder/directory as the entry point to serve its web pages and resources, allowing the web application to coexist with other applications under the same domain.
BaseURL will be automatically configured based on the hostname, port, and other variables in the application's setup.
This property is read-only.
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.
Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).
This property is read-only.
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 WebApplication.
Copyright usually contains the application name, version number and copyright information.
This property is read-only.
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 can be set only in the IDE.
This property is read-only.
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.
Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).
This property is read-only.
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.
Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).
This property is read-only.
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.
Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).
This property is read-only.
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 WebAppSecurityOptions
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.
This example, in the App.Opening event, allows a web app to appear in an
<iframe>
on any web page from any server:Self.Security.FrameEmbedding = WebAppSecurityOptions.FrameOptions.AllowThis example, in the App.Opening event, uses 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 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.
This property is read-only.
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.URL
URL As String
The base URL of the running web application
This property is read-only.
Var baseURL As String baseURL = WebApplication.URL
WebApplication.Version
Version As String
Version of the ConsoleApplication.
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).
This property is read-only.
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 WebSession
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.
WebApplication.SleepCurrentThread
SleepCurrentThread(milliseconds as Integer)
Pauses the current thread for the specified number of milliseconds.
WebApplication.YieldToNextThread
YieldToNextThread
Yields execution to the next thread in the application. This is useful for applications that require background tasks to maintain responsiveness by ensuring time is distributed among active threads.
This method does not take any parameters and does not return a value. Here's an example:
' Perform a background calculation While backgroundTask.IsRunning App.YieldToNextThread Wend
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 |
---|---|
--BaseURL |
The application will use the specified folder/directory as the entry point to serve its web pages and resources, allowing the web application to coexist with other applications under the same domain. |
--Certificate |
The path to the SSL certificate. |
--Logging |
The path to where the HTTP Log file is or will be created. |
--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. The default is 200. |
--MaxSockets |
The maximum number of allowed connected sockets for unsecured connections. 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. The default is 200. If you do not want any unsecured connections, set this value to 0. |
--MinSockets |
The minimum number of allowed connected sockets. The default is 20. |
--NetworkInterfaceIndex |
The index value (of NetworkInterfaces) to use as the NIC for connections. You can also use the value Loopback to allow listening only on the loopback interface. The default is to listen on all interfaces. |
--Port |
The standard (not secure) 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. |
--SecureNetworkInterfaceIndex |
The index value (of NetworkInterfaces) to use as the NIC for secure connections. You can also use the value Loopback to allow listening only on the loopback interface. |
--SecurePort |
The port the web app listens to for a secure connection. You must specify this port via the command-line in order for the web app to allow secure connections. |
--SslType |
Allows you to specify the type of security used. You can use these integer values: 3 (TLSv1), 4 (TLSv11), 5 (TLSv12, the default) |
--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
Project Types |
Web |
Operating Systems |
All |
See also
ServiceApplication parent class; WebSession, Session, WebPage classes; App function; Web Application Structure, SSL for Web Apps topics