winsw/README.md

winsw: Windows service wrapper in less restrictive license
=========================

[![Build status](https://ci.appveyor.com/api/projects/status/i94752yal9iy77in?svg=true)](https://ci.appveyor.com/project/oleg-nenashev/winsw)

WinSW is an executable binary, which can be used to wrap and manage a custom process as a Windows service.
Once you download the installation package, you can rename `winsw.exe` to any name, e.g. `myService.exe`.

### Why?

See the [project manifest](MANIFEST.md).

### Download
Right now the project uses [Jenkins](https://jenkins.io/index.html) Maven repository as a main storage of release files. 
Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/). 

Some releases (e.g. alpha- and beta-versions) can be also downloaded from the project's GitHub page. 
This source of releases is not an **official one**.

### Usage

WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE Config file](doc/exeConfigFile.md).

Your renamed `winsw.exe` binary also accepts the following commands:

* `install` to install the service to Windows Service Controller.
  This command requires some preliminary steps described in the [Installation Guide](doc/installation.md).
* `uninstall` to uninstall the service. The opposite operation of above.
* `start` to start the service. The service must have already been installed.
* `stop` to stop the service.
* `restart` to restart the service. If the service is not currently running, this command acts like `start`.
* `status` to check the current status of the service. This command prints one line to the console. `NonExistent` to indicate the service is not currently installed, `Started` to indicate the service is currently running, and `Stopped` to indicate that the service is installed but not currently running.

### Supported .NET versions

WinSW `1.x` Executable is being built with a .NET Framework `2.0` target, and by defaut it will work only for .NET Framework versions below `3.5`.
On the other hand, the code is known to be compatible with .NET Framework `4.0` and above.
It is possible to declare the support of this framework via the `exe.config` file.
See the [Installation Guide](doc/installation.md) for more details.

WinSW `2.x` offers two executables, which declare .NET Frameworks `2.0` and `4.0` as targets.
Naming and download sources for these binaries are currently in flux.

### Documentation

* [Installation Guide](doc/installation.md) - Describes the installation process for different systems and .NET versions
* [Release notes](CHANGELOG.md)
* Configuration:
 * [Main XML Configuration file](doc/xmlConfigFile.md)
 * [EXE Configuration File](doc/exeConfigFile.md)
 * [Logging and Error Reporting](doc/loggingAndErrorReporting.md)
 * [Extensions](doc/extensions/extensions.md)
* Use-cases:
 * [Self-restarting services](doc/selfRestartingService.md)
 * [Deferred File Operations](doc/deferredFileOperations.md)
* Configuration Management:
 * [Puppet Forge Module](doc/puppetWinSW.md)

### Release lines

#### WinSW 2.x

This is a new release line under active development.

Major changes since 1.x:
* New executable package targeting the .NET Framework `4.0`. .NET Framework `2.0` is still supported.
* Migration of the logging subsystem to `Apache log4net`
* Internal [extension engine](doc/extensions/extensions.md), which allows extending the wrapper's behavior.

See the full changelog in the [release notes](CHANGELOG.md#20).

The version `2.x` is **fully compatible** with the `1.x` configuration file format, 
  hence the upgrade procedure just requires replacement of the executable file.

#### WinSW 1.x

This is an old baseline of WinSW.
Currently it is in the maintenance-only state.
New versions with fixes may be released on-demand.

### Build Environment

* IDE: [Visual Studio Community 2013](http://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx) (free for open-source projects)
* `winsw-key.snk` should be available in the project's root in order to build the executable
 * You can generate the certificate in "Project Settings/Signing"
 * The certificate is in <code>.gitignore</code> list. Please do not add it to the repository
adding doc 2013-03-01 23:55:22 +00:00			`winsw: Windows service wrapper in less restrictive license`
			`=========================`

Fixes #142 - Deploy the automatic build on Appveyor (#144) * First configuration stub * Get rid of the old winsw_cert.pfx references, adjust docs * Fix the corrupted log4net reference, we use 2.0.3 * Generate stub SNK file * Signing: Try full SDK path to generate SNKs * Fix the path * Signing: Sign all assemblies being packed into WinSW * Tests: Try enabling tests * Tests and artifacts: Use absolute paths * Artifact path must be relative * The test DLL is the NUnit one * nunit-console does not require loggers * NUnit: Try picking all DLLs in the output folder * NUnit console: No wildcards * Tests: Fix the test project to make it properly working with the new project structure * Docs: Clarify the specifics of external extension usage * Add AppVeyor badge to README.md 2016-12-04 08:34:19 +00:00			`[![Build status](https://ci.appveyor.com/api/projects/status/i94752yal9iy77in?svg=true)](https://ci.appveyor.com/project/oleg-nenashev/winsw)`

Update the readme file 2016-11-25 22:26:12 +00:00			`WinSW is an executable binary, which can be used to wrap and manage a custom process as a Windows service.`
			Once you download the installation package, you can rename `winsw.exe` to any name, e.g. `myService.exe`.

Docs: Decouple the project manifest to a standalone page 2016-11-25 22:28:42 +00:00			`### Why?`

			`See the [project manifest](MANIFEST.md).`

Update the readme file 2016-11-25 22:26:12 +00:00			`### Download`
			`Right now the project uses [Jenkins](https://jenkins.io/index.html) Maven repository as a main storage of release files.`
			`Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/).`

			`Some releases (e.g. alpha- and beta-versions) can be also downloaded from the project's GitHub page.`
			`This source of releases is not an official one.`

			`### Usage`
Docs: Fix links 2016-11-25 20:56:39 +00:00
Add a simple documentation stub for the EXE Config File 2016-11-25 22:36:39 +00:00			`WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE Config file](doc/exeConfigFile.md).`
Docs: Fix links 2016-11-25 20:56:39 +00:00
Update the readme file 2016-11-25 22:26:12 +00:00			Your renamed `winsw.exe` binary also accepts the following commands:
Docs: Fix links 2016-11-25 20:56:39 +00:00
			* `install` to install the service to Windows Service Controller.
			`This command requires some preliminary steps described in the [Installation Guide](doc/installation.md).`
moving more text from Wiki 2013-03-02 00:11:27 +00:00			* `uninstall` to uninstall the service. The opposite operation of above.
			* `start` to start the service. The service must have already been installed.
			* `stop` to stop the service.
			* `restart` to restart the service. If the service is not currently running, this command acts like `start`.
			* `status` to check the current status of the service. This command prints one line to the console. `NonExistent` to indicate the service is not currently installed, `Started` to indicate the service is currently running, and `Stopped` to indicate that the service is installed but not currently running.

.NET4 - Document supported .NET versions in README.md (solves #102) 2016-12-04 11:20:54 +00:00			`### Supported .NET versions`

			WinSW `1.x` Executable is being built with a .NET Framework `2.0` target, and by defaut it will work only for .NET Framework versions below `3.5`.
			On the other hand, the code is known to be compatible with .NET Framework `4.0` and above.
			It is possible to declare the support of this framework via the `exe.config` file.
			`See the [Installation Guide](doc/installation.md) for more details.`

			WinSW `2.x` offers two executables, which declare .NET Frameworks `2.0` and `4.0` as targets.
			`Naming and download sources for these binaries are currently in flux.`

Decouple the documentation to several pages 2016-11-24 03:02:30 +00:00			`### Documentation`
moving more text from Wiki 2013-03-02 00:11:27 +00:00
Docs: Fix links 2016-11-25 20:56:39 +00:00			`* [Installation Guide](doc/installation.md) - Describes the installation process for different systems and .NET versions`
Docs: Add changelog 2016-11-25 21:00:30 +00:00			`* [Release notes](CHANGELOG.md)`
Decouple the documentation to several pages 2016-11-24 03:02:30 +00:00			`* Configuration:`
			`* [Main XML Configuration file](doc/xmlConfigFile.md)`
Add a simple documentation stub for the EXE Config File 2016-11-25 22:36:39 +00:00			`* [EXE Configuration File](doc/exeConfigFile.md)`
Decouple the documentation to several pages 2016-11-24 03:02:30 +00:00			`* [Logging and Error Reporting](doc/loggingAndErrorReporting.md)`
Document the extension engine and exisitng extensions (#141) * Document the extension engine and exisitng extensions * Add the link to Extensions in ToC 2016-12-02 12:59:26 +00:00			`* [Extensions](doc/extensions/extensions.md)`
Decouple the documentation to several pages 2016-11-24 03:02:30 +00:00			`* Use-cases:`
			`* [Self-restarting services](doc/selfRestartingService.md)`
			`* [Deferred File Operations](doc/deferredFileOperations.md)`
Add Documentation for the Puppet Module (#140) * Update Main ReadMe to include CM and Puppet doc link Add a link to a page built to describe the module in the Puppet Forge * Initial Creation * Adds Content for Puppet Module * Remove accidental asterik * Syntax Error for Link * Typo On Link * Updates to a documentation spec 2016-11-30 18:54:07 +00:00			`* Configuration Management:`
			`* [Puppet Forge Module](doc/puppetWinSW.md)`
Descibe the build environment Follow-up to #62 Also resolves #5 2015-01-28 13:40:12 +00:00
Docs: Update WinSW 1/2 in README 2016-11-25 12:34:50 +00:00			`### Release lines`

			`#### WinSW 2.x`

			`This is a new release line under active development.`

			`Major changes since 1.x:`
Add compatibility notes to the documentation 2016-12-09 21:41:06 +00:00			* New executable package targeting the .NET Framework `4.0`. .NET Framework `2.0` is still supported.
			* Migration of the logging subsystem to `Apache log4net`
			`* Internal [extension engine](doc/extensions/extensions.md), which allows extending the wrapper's behavior.`

			`See the full changelog in the [release notes](CHANGELOG.md#20).`

			The version `2.x` is fully compatible with the `1.x` configuration file format,
			`hence the upgrade procedure just requires replacement of the executable file.`
Docs: Update WinSW 1/2 in README 2016-11-25 12:34:50 +00:00
			`#### WinSW 1.x`

			`This is an old baseline of WinSW.`
			`Currently it is in the maintenance-only state.`
			`New versions with fixes may be released on-demand.`
Added some info about the project status 2015-02-04 12:18:01 +00:00
Descibe the build environment Follow-up to #62 Also resolves #5 2015-01-28 13:40:12 +00:00			`### Build Environment`

Get rid of the bottom links 2016-11-24 00:32:26 +00:00			`* IDE: [Visual Studio Community 2013](http://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx) (free for open-source projects)`
Fixes #142 - Deploy the automatic build on Appveyor (#144) * First configuration stub * Get rid of the old winsw_cert.pfx references, adjust docs * Fix the corrupted log4net reference, we use 2.0.3 * Generate stub SNK file * Signing: Try full SDK path to generate SNKs * Fix the path * Signing: Sign all assemblies being packed into WinSW * Tests: Try enabling tests * Tests and artifacts: Use absolute paths * Artifact path must be relative * The test DLL is the NUnit one * nunit-console does not require loggers * NUnit: Try picking all DLLs in the output folder * NUnit console: No wildcards * Tests: Fix the test project to make it properly working with the new project structure * Docs: Clarify the specifics of external extension usage * Add AppVeyor badge to README.md 2016-12-04 08:34:19 +00:00			* `winsw-key.snk` should be available in the project's root in order to build the executable
Descibe the build environment Follow-up to #62 Also resolves #5 2015-01-28 13:40:12 +00:00			`* You can generate the certificate in "Project Settings/Signing"`
			`* The certificate is in <code>.gitignore</code> list. Please do not add it to the repository`