Class

ServiceApplication

Description

Used to create a Windows service application, which runs in the background without a user interface.

Methods

Name

Parameters

Returns

Shared

Daemonize

Boolean

DoEvents

[milliseconds As Integer]

Events

Name

Parameters

Returns

DontDaemonize

Boolean

Pause

Resume

Run

Args() As String

Integer

Stop

ShuttingDown As Boolean

UnhandledException

error As RuntimeException

Boolean

Property descriptions

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

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

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

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

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

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

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

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

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

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

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

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

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

ServiceApplication.DontDaemonize

DontDaemonize As Boolean

Returning True prevents the application from being daemonized.

ServiceApplication.Pause

Pause

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

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

ServiceApplication.Resume

Resume

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

The Resume event is not called unless the ServiceApplication is paused. Use this event to continue running your ServiceApplication.

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

ServiceApplication.Stop

Stop(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.

ServiceApplication.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 Service application is a special type of ConsoleApplication that is designed to run without any interface and even if are no users logged in. A Service application should not require any user interaction since it's possible that no user is logged in while your application is running. Typical examples of service applications are FTP servers, HTTP servers, and other types of servers that have no user interface.

Console applications rely on the Print and Input commands for communicating with the user. Services behave much the same (depending on how the service is installed, and on what operating system). For example, if your service is run as a daemon on macOS or Linux using the inet.d scripts, then Print and Input will actually correspond to a socket that the system has already attached for you. This means that the Write method of the StandardOutputStream class will actually behave just like a socket and the Read method of the StandardInputStream class will as well.

It is worth noting that this behavior is not guaranteed for all operating systems. If you plan on deploying your service on multiple OS's, it is best to use a TCPSocket directly instead of relying on standard input and output being hooked up to a socket for you.

To create a service application, you must first create a regular console application. Choose File > New Project and choose the Console Application item. A console application has a single project item called App whose super class is ConsoleApplication. Change App's super to ServiceApplication.

The ServiceApplication class is a subclass of ConsoleApplication class, so all the ConsoleApplication events and methods are available. In addition to the ConsoleApplication's events, there are three new events for a ServiceApplication. Some of these events will be fired only on operating systems that support them-and the only OS that supports them currently is Windows.

Installing a service application on windows

If you use an installer, check if it can create the service for you automatically. If you would rather do it by hand, the Windows command sc (service controller) is used to install services.

sc create RSWebSvc type= own start= auto binpath= c:\Path\To\Exe\WebApp.exe

Do not leave out the spaces after each = sign in the above command.

After the service is installed, you will see it in the Services Manager where you can start, pause or stop it. The following can also be used to start the service:

sc start RSWebSvc

Note: The sc command should be run with Administrator privileges in order to function correctly.

Compatibility

All project types on all supported operating systems.