Windows Service Wrapper

This project creates a wrapper executable that can be used to host any executable as an Windows service.

The binaries are available here for download.

Usage

At design time...

1. Rename winsw.exe to a sensible filename (such as myapp.exe)
2. Write myapp.xml (see Configuration Syntax for more details)
3. Place those two files side by side when you deploy your application, because that's how winsw.exe discovers its configuration.

At runtime, use the following command-line options...

• To install a service, run myapp.exe install
• To start a service, run myapp.exe start
• To stop a service, run myapp.exe stop
• To restart a service, run myapp.exe restart
• To uninstall a service, run myapp.exe uninstall

This applet will report any error messages to stderr. Otherwise, these commands do no produce any output and exit with ErrorLevel=0.

In addition, you can also run myapp.exe status to have it print out the current status of the service to stdout. Again, any error encountered during the processing would cause output to be reported to stderr.

Deferred File Operations

To support self updating services, winsw offers a mechanism to perform file operations before a service start up. This is often necessary because Windows prevents files from overwritten while it's in use.

To perform file operations, write a text file (in the UTF-8 encoding) called myapp.copies, and for each operation add one line. i.e. to move a file, write "src>dst". If the 'dst' file already exists it will be overwritten. The success or failure of the operation will be recorded in the event log.

XML Configuration File Structure

 

id

Specifies the ID that Windows uses internally to identify the service. This has to be unique among all the services installed in a system, and (while I haven't verified this) this must consist entirely out of alpha-numeric characters.

name

Short display name of the service, which can contain spaces and other characters. This shouldn't be too long, like <id>, and this also needs to be unique among all the services in a given system.

description

Long description of the service.

executable

This element specifies the executable to be launched. It can be either absolute path, or you can just specify the executable name and let it be searched from PATH (although note that the services often run in a different user account and therefore it might have different PATH than your shell does.)

depend

Delayed loading of the service is possible with multiple optional <depend> elements referring to other service ids.

logging

Optionally set a different logging directory with <logpath> and startup <logmode>: reset (clear log), roll (move to *.old) or append (default).

arguments

This element specifies the arguments to be passed to the executable. To pass in multiple arguments, separate them with whitespace, like `<arguments>foo bar zot</arguments>`

To make it easier to comment for example debug arguments you can use multiple optional <argument> elements.

If you need different startup and shutdown arguments, such as catalina.bat run vs catalina.bat stop, you can supply them with multiple optional <startargument> and <stopargument> elements.

Note: when <argument>, <startargument> or <stopargument> elements are used the </arguments> element is ignored/no longer required.

env

This optional element can be specified multiple times if necessary to specify environment variables to be set for the child process. The syntax is:

<env name="HOME" value="c:\abc" />  

interactive

If this optional element is specified, the service will be allowed to interact with the desktop, such as by showing a new window and dialog boxes. If your program requires GUI, set this like the following:

<interactive />  

Example

<service>
  <id>fisheye</id>
  <name>dev.net FishEye</name>
  <description>FishEye</description>
  <executable>%FISHEYE_HOME%\bin\fisheyectl.bat</executable>
  <logpath>P:\dev\logs\os\windows\services</logpath>
  <logmode>roll</logmode>
  <depend>Spooler</depend>
  <startargument>run</startargument>
  <stopargument>stop</stopargument>
</service>
              

Environment variable expansion

All the text values in this XML can include environment variable expansions of the form %NAME%, like Windows batch files. Such an expression is replaced by the actual value of the environment variable.

Also, the service wrapper sets the environment variable BASE by itself, which points to a directory that contains the renamed winsw.exe. This is useful to refer to other files in the same directory. Since this is an environment variable by itself, this value can be also accessed from the child process launched from the service wrapper.