Class

ConsoleApplication

Description

Used by console (or command-line) applications on Windows, macOS, and Linux.

Methods

Name

Parameters

Returns

Shared

Daemonize

Boolean

DoEvents

[milliseconds As Integer]

Events

Name

Parameters

Returns

Run

Args() As String

Integer

UnhandledException

error As RuntimeException

Boolean

Property descriptions

ConsoleApplication.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

ConsoleApplication.BuildDateTime

BuildDateTime As DateTime

Contains the date and time when the application was built.

This property is read-only.

You can also access the CreationDateTime property of the application's FolderItem by calling App.ExecutableFile.CreationDate.

ConsoleApplication.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)

ConsoleApplication.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.

ConsoleApplication.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

ConsoleApplication.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

ConsoleApplication.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

ConsoleApplication.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

ConsoleApplication.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.

ConsoleApplication.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

ConsoleApplication.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

ConsoleApplication.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 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

ConsoleApplication.DoEvents

DoEvents([milliseconds As Integer])

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

Event descriptions

ConsoleApplication.Run

Run(Args() As String) As Integer

Code in this event is run when the console app starts running. The console app ends when this event finishes.

Args is an array of command line parameters that get passed to the application. The first parameter will always be the application itself. The return value will be passed to the operating system as the return value for the entire application. The encoding of Args() is operating system-specific. On NT-based systems, it is UTF-16. On Linux, it will be UTF-8, and so forth.

On macOS and Linux, the Args() array contains the passed arguments as unescaped and unquoted values:

  • Unescaped: some characters need to be escaped to be passed on a terminal command line, i.e. preceded by a backslash character. Args() values contain the character without the leading backslash.

  • Unquoted: instead of escaping some characters, single-quotes or double-quotes can be used. Quotes are removed in Args() values.

For example, passing the following command line from a terminal:

/path/to/my/application -a --name="A quoted string parameter" --file=~/Anescapedpath

results in the following Args() array:

#

Description

0

/path/to/my/application

1

-a

2

--name=A quoted string parameter   (Double-quotes are removed)

3

--file=~/An escaped path   (Characters are unescaped)

If your app has concluded successfully, it should return 0 from this event. If not, it should return some kind of non-zero error code.

ConsoleApplication.UnhandledException

UnhandledException(error As RuntimeException) As Boolean

Occurs when a RuntimeException occurs that is not otherwise handled.

This event allows you to do any last-minute clean-up, but the application does not resume after this event. The application terminates after this event.

The UnhandledException event returns a Boolean. By default, the application writes an error message to stderr. Return True to suppress output to stderr.

Notes

A console application differs from a desktop application in that it contains no graphical user interface and works only from the command line. In macOS, a console application runs within the Terminal application; on Windows, it runs from the command line prompt, and on Linux it runs from the command line or a Terminal window.

To create a console application, choose File => New Project and choose Console Application from the New Project Chooser window. This will create a new project without items for the default window and menubar. The Navigator will only have the App class, which is subclassed from ConsoleApplication instead of DesktopApplication or WebApplication.

Because a console application has no windows or menus of its own, it communicates with the user through the Print and Input commands or the StandardInputStream and StandardOutputStream classes, which provide equivalent functionality.

When you create a Desktop application, the program execution begins in the Opening event of the DesktopApplication class and halts when you call the Quit method or the user quits your application by choosing File => Quit. Your program will stay loaded in memory and running until a Quit command is received.

A console application behaves differently from a desktop application. The program execution begins in the Run event of the ConsoleApplication class and terminates when you exit the Run event or call the Quit method. In other words, the entire application executes inside of the Run event. Press Control-C for force a console app to quit.

Note

By design, console applications do not have a main event loop. It implies that classes relying on such event loop will not work as expected, like Timers or sockets. See the DoEvents method to see how to use Timers and sockets in a console application.

If you would like your application to behave in a more GUI-like way, where it continues to run until the user interacts with it, then you can do that by placing a While loop in the Run event.

A ServiceApplication is a special type of console application that is designed to run without user intervention of any kind. The typical type of service application is a an internet server, such as an HTTP, FTP, or WebDAV server, which is capable of running without any user logged into the machine.

On Linux, a console application does not require GTK, GDK, or CUPS.

The Daemonize method

A typical use of the Daemonize method is as follows:

If (args(1) = "start" Or args(1) = "-d") Then
  If Not App.Daemonize Then
    System.Log(System.LogLevelCritical, "Could not daemonize the application")
    Return -1
  End If
End If

Compatibility

All project types on all supported operating systems.