2020-07-20 13:40:05 +00:00
# Windows Service Wrapper in a permissive license
2013-03-01 23:55:22 +00:00
2018-11-29 16:00:00 +00:00
[](https://github.com/winsw/winsw/releases)
2020-08-30 00:56:18 +00:00
[](https://github.com/winsw/winsw/releases)
2018-11-29 16:00:00 +00:00
[](https://www.nuget.org/packages/WinSW/)
2019-09-17 16:00:00 +00:00
[](https://dev.azure.com/winsw/winsw/_build?definitionId=1& _a=summary)
2020-07-20 13:40:05 +00:00
[](https://dev.azure.com/winsw/winsw/_release?_a=releases& view=mine& definitionId=1)
2018-11-29 16:00:00 +00:00
[](https://gitter.im/winsw/winsw?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge)
[](LICENSE.txt)
2016-12-04 08:34:19 +00:00
2020-08-10 23:54:32 +00:00
WinSW wraps and manages any application as a Windows service.
2016-11-25 22:26:12 +00:00
2020-08-30 00:56:18 +00:00
**We are actively developing WinSW 3. Please refer to the [v2 ](https://github.com/winsw/winsw/tree/master ) branch for previous version documentation.**
2020-07-20 13:40:05 +00:00
2018-11-27 16:00:00 +00:00
## Why?
2016-11-25 22:28:42 +00:00
See the [project manifest ](MANIFEST.md ).
2020-04-10 21:29:34 +00:00
## Supported platforms
2020-07-28 00:35:18 +00:00
WinSW 3 can run on Windows platforms with .NET Framework 4.6.1 or later versions installed.
2023-01-30 04:52:56 +00:00
For systems without .NET Framework, the project provides native 64-bit and 32-bit executables based on .NET 7.
2020-04-10 21:29:34 +00:00
More executables can be added upon request.
2020-08-10 23:54:32 +00:00
[.NET Framework system requirements ](https://docs.microsoft.com/dotnet/framework/get-started/system-requirements )\
2020-08-30 00:56:18 +00:00
Preinstalled since Windows 10, version 1511 and Windows Server 2016.\
Installable since Windows 7 SP1 and Windows Server 2008 R2 SP1.
2020-08-10 23:54:32 +00:00
2023-01-30 04:52:56 +00:00
[.NET 7 system requirements ](https://github.com/dotnet/core/blob/main/release-notes/7.0/supported-os.md )\
Supported since Windows 10, version 1607, Windows Server (Core) 2012 R2 and Nano Server, version 1809.
2020-08-10 23:54:32 +00:00
2018-11-27 16:00:00 +00:00
## Download
2016-11-25 22:26:12 +00:00
2020-08-10 23:54:32 +00:00
Latest release and pre-release WinSW binaries are available on [GitHub Releases ](https://github.com/winsw/winsw/releases ).
2016-12-09 22:58:28 +00:00
2020-04-10 21:29:34 +00:00
Alternative sources:
2020-08-10 23:54:32 +00:00
* CI builds are available on [Azure Pipelines ](https://dev.azure.com/winsw/winsw/_build?definitionId=1 ).
* [NuGet ](https://www.nuget.org/packages/WinSW/ ). (2.x)
* [Maven packaging ](https://github.com/jenkinsci/winsw-maven-packaging ) for executables, hosted by the [Jenkins project ](https://jenkins.io/ ).
Binaries are available [here ](https://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/ ). (2.x)
2016-11-25 22:26:12 +00:00
2020-12-23 19:12:15 +00:00
## Get started
### Use WinSW as a global tool
1. Take *WinSW.exe* or *WinSW.zip* from the distribution.
1. Write *myapp.xml* (see the [XML config file specification ](docs/xml-config-file.md ) and [samples ](samples ) for more details).
1. Run [`winsw install myapp.xml [options]`](docs/cli-commands.md#install-command) to install the service.
1. Run [`winsw start myapp.xml` ](docs/cli-commands.md#start-command ) to start the service.
1. Run [`winsw status myapp.xml` ](docs/cli-commands.md#status-command ) 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* ).
1. Write *myapp.xml* (see the [XML config file specification ](docs/xml-config-file.md ) and [samples ](samples ) for more details).
1. Place those two files side by side, because that's how WinSW discovers its co-related configuration.
1. Run [`myapp.exe install [options]`](docs/cli-commands.md#install-command) to install the service.
1. Run [`myapp.exe start` ](docs/cli-commands.md#start-command ) 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:
```xml
< 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 ](docs/xml-config-file.md ).
You can find more samples [here ](samples ).
2018-11-27 16:00:00 +00:00
## Usage
2016-11-25 20:56:39 +00:00
2020-07-20 13:40:05 +00:00
WinSW is being managed by the [XML configuration file ](docs/xml-config-file.md ).
2016-11-25 20:56:39 +00:00
2018-11-29 16:00:00 +00:00
Your renamed *WinSW.exe* binary also accepts the following commands:
2016-11-25 20:56:39 +00:00
2020-08-10 23:54:32 +00:00
| Command | Description |
| ------- | ----------- |
2020-12-23 19:12:15 +00:00
| [install ](docs/cli-commands.md#install-command ) | Installs the service. |
2020-07-28 00:35:18 +00:00
| [uninstall ](docs/cli-commands.md#uninstall-command ) | Uninstalls the service. |
| [start ](docs/cli-commands.md#start-command ) | Starts the service. |
| [stop ](docs/cli-commands.md#stop-command ) | Stops the service. |
| [restart ](docs/cli-commands.md#restart-command ) | Stops and then starts the service. |
| [status ](docs/cli-commands.md#status-command ) | Checks the status of the service. |
| [refresh ](docs/cli-commands.md#refresh-command ) | Refreshes the service properties without reinstallation. |
2020-08-10 23:54:32 +00:00
| [customize ](docs/cli-commands.md#customize-command ) | Customizes the wrapper executable. |
| dev | Experimental commands. |
Experimental commands:
2020-08-30 00:56:18 +00:00
| Command | Description |
| ------- | ----------- |
| [dev ps ](docs/cli-commands.md#dev-ps-command ) | Draws the process tree associated with the service. |
| [dev kill ](docs/cli-commands.md#dev-kill-command ) | Terminates the service if it has stopped responding. |
| [dev list ](docs/cli-commands.md#dev-list-command ) | Lists services managed by the current executable. |
2013-03-02 00:11:27 +00:00
2020-08-10 23:54:32 +00:00
Most commands require Administrator privileges to execute. WinSW will prompt for UAC in non-elevated sessions.
2020-04-19 07:04:50 +00:00
2018-11-27 16:00:00 +00:00
## Documentation
2013-03-02 00:11:27 +00:00
2020-10-22 13:28:16 +00:00
* [Migrate to WinSW 3.x ](docs/migrate-to-3-x.md )
2016-11-24 03:02:30 +00:00
* Configuration:
2020-07-28 00:35:18 +00:00
* [XML configuration file ](docs/xml-config-file.md )
2020-02-03 16:00:00 +00:00
* [Logging and error reporting ](docs/logging-and-error-reporting.md )
* [Extensions ](docs/extensions/extensions.md )
2020-07-28 00:35:18 +00:00
* Use cases:
2020-02-03 16:00:00 +00:00
* [Self-restarting services ](docs/self-restarting-service.md )
* [Deferred file operations ](docs/deferred-file-operations.md )
2015-01-28 13:40:12 +00:00
2020-04-10 21:29:34 +00:00
## Contributing
2016-12-09 21:41:06 +00:00
2020-04-10 21:29:34 +00:00
Contributions are welcome!
2020-02-03 16:00:00 +00:00
See the [contributing guidelines ](CONTRIBUTING.md ) for more information.
2016-11-25 12:34:50 +00:00
2018-11-29 16:00:00 +00:00
## License
WinSW is licensed under the [MIT ](LICENSE.txt ) license.
