winsw

Windows Service Wrapper in a permissive license

WinSW wraps and manages any application as a Windows service.

Project status

• Development of WinSW 3.x happens on the default branch v3.
• GitHub Releases contains stable 2.x releases and 3.x pre-releases. NuGet and Maven packages currently correspond to 2.x.
• For WinSW 2.x documentation, refer to the v2 branch.

Why?

See the project manifest.

Supported platforms

WinSW 3 can run on Windows platforms with .NET Framework 4.6.1 or later versions installed. For systems without .NET Framework, the project provides native 64-bit and 32-bit executables based on .NET 7.

More executables can be added upon request.

.NET Framework system requirements\ Preinstalled since Windows 10, version 1511 and Windows Server 2016.\ Installable since Windows 7 SP1 and Windows Server 2008 R2 SP1.

.NET 7 system requirements\ Supported since Windows 10, version 1607, Windows Server (Core) 2012 R2 and Nano Server, version 1809.

Download

Latest release and pre-release WinSW binaries are available on GitHub Releases.

Alternative sources:

• CI builds are available on Azure Pipelines.
• NuGet. (2.x)
• Maven packaging for executables, hosted by the Jenkins project. Binaries are available here. (2.x)

Get started

Use WinSW as a global tool

1. Take WinSW.exe or WinSW.zip from the distribution.
2. Write myapp.xml (see the XML config file specification and samples for more details).
3. Run winsw install myapp.xml [options] to install the service.
4. Run winsw start myapp.xml to start the service.
5. Run winsw status myapp.xml to see if your service is up and running.

Use WinSW as a bundled tool

1. Take WinSW.exe or WinSW.zip from the distribution, and rename the .exe to your taste (such as myapp.exe).
2. Write myapp.xml (see the XML config file specification and samples for more details).
3. Place those two files side by side, because that's how WinSW discovers its co-related configuration.
4. Run myapp.exe install [options] to install the service.
5. Run myapp.exe start to start the service.

Sample configuration file

You write the configuration file that defines your service. The example below is a primitive example being used in the Jenkins project:

<service>
  <id>jenkins</id>
  <name>Jenkins</name>
  <description>This service runs Jenkins continuous integration system.</description>
  <env name="JENKINS_HOME" value="%BASE%"/>
  <executable>java</executable>
  <arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
  <log mode="roll"></log>
</service>

The full specification of the configuration file is available here. You can find more samples here.

Usage

WinSW is being managed by the XML configuration file.

Your renamed WinSW.exe binary also accepts the following commands:

Command	Description
install	Installs the service.
uninstall	Uninstalls the service.
start	Starts the service.
stop	Stops the service.
restart	Stops and then starts the service.
status	Checks the status of the service.
refresh	Refreshes the service properties without reinstallation.
customize	Customizes the wrapper executable.
dev	Experimental commands.

Experimental commands:

Command	Description
dev ps	Draws the process tree associated with the service.
dev kill	Terminates the service if it has stopped responding.
dev list	Lists services managed by the current executable.

Most commands require Administrator privileges to execute. WinSW will prompt for UAC in non-elevated sessions.

Documentation

• Migrate to WinSW 3.x
• Configuration:
  • XML configuration file
  • Logging and error reporting
  • Extensions
• Use cases:
  • Self-restarting services
  • Deferred file operations
  • Troubleshooting

Contributing

Contributions are welcome! See the contributing guidelines for more information.

License

WinSW is licensed under the MIT license.

Similar projects

• srvany.exe
• nssm
• srvany-ng
• shawl