mirror of https://github.com/winsw/winsw
Document the extension engine and exisitng extensions (#141)
* Document the extension engine and exisitng extensions * Add the link to Extensions in ToCpull/143/head
Oleg Nenashev
GitHub
parent
62b495f088
commit
0f354b42ac
10
CHANGELOG.md
10
CHANGELOG.md
|
|
@ -8,13 +8,13 @@ Below you can find release notes for the trunk version of WinSW.
|
|||
Release date: Coming Soon
|
||||
|
||||
Improvements:
|
||||
* Introduced a concept of WinSW extensions, which allows extending the wrapper's behavior
|
||||
* Introduced the [WinSW extension engine](doc/extensions/extensions.md), which allows extending the wrapper's behavior.
|
||||
([PR #42](https://github.com/kohsuke/winsw/pull/42)).
|
||||
* The extension binary backward comparability is not guaranteed
|
||||
* The engine does not support extensions in external DLLs (but you can repackage the executable if you want to extend WinSW)
|
||||
* `SharedDirectoriesMapper` extension for mapping shared directories when the Windows service starts
|
||||
* [SharedDirectoriesMapper extension](doc/extensions/sharedDirectoryMapper.md)
|
||||
([PR #42](https://github.com/kohsuke/winsw/pull/42)).
|
||||
* Migrate event logging to log4j
|
||||
* [RunawayProcessKiller extension](doc/extensions/runawayProcessKiller.md)
|
||||
([PR #133](https://github.com/kohsuke/winsw/pull/133)).
|
||||
* Migrate event logging to `log4j`
|
||||
([PR #73](https://github.com/kohsuke/winsw/pull/73)).
|
||||
|
||||
##### 1.19.1
|
||||
|
|
|
|||
|
|
@ -37,6 +37,7 @@ Your renamed `winsw.exe` binary also accepts the following commands:
|
|||
* [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)
|
||||
|
|
@ -53,7 +54,7 @@ API stability is not guaranteed till the first release, the project structure is
|
|||
Major changes since 1.x:
|
||||
* Rework of the project structure
|
||||
* Better logging
|
||||
* Internal plugin engine, which allows extending the WinSW behavior
|
||||
* [Internal extension engine](doc/extensions/extensions.md), which allows extending the WinSW behavior
|
||||
|
||||
#### WinSW 1.x
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,32 @@
|
|||
WinSW extensions
|
||||
===
|
||||
|
||||
Starting from WinSW `2.0`, the wrapper provides an internal extension engine and several extensions.
|
||||
These extensions allow to alter the behavior of the Windows service in order to setup the required service environment.
|
||||
|
||||
### Available extensions
|
||||
|
||||
* [Shared Directory Mapper](sharedDirectoriesMapper.md) - Allows mapping shared drives before starting the executable
|
||||
* [Runaway Process Killer](runawayProcessKiller.md) - Termination of processes started by the previous runs of WinSW
|
||||
|
||||
### Developer guide
|
||||
|
||||
In WinSW `2.x` the extension does not support inclusion of external extension DLLs.
|
||||
|
||||
#### Adding external extensions
|
||||
|
||||
The only way to create an external extension is to create a new extension DLL and
|
||||
then to merge this DLL into the executable using tools like `ILMerge`.
|
||||
See the example in `src/Core/ServiceWrapper/winsw.csproj`.
|
||||
|
||||
Generic extension creation guideline:
|
||||
* Extension DLL should reference the `WinSWCore` library.
|
||||
* The extension should extend the `AbstractWinSWExtension` class.
|
||||
* The extension then can override event handlers offered by the upper class.
|
||||
* The extension should implement the configuration parsing from the `XmlNode`.
|
||||
* The extension should support disabling from the configuration file.
|
||||
|
||||
WinSW engine will automatically locate your extension using the class name in the [XML Configuration File](../xmlConfigFile.md).
|
||||
See configuration samples provided for the extensions in the core.
|
||||
|
||||
Please note that in the current versions of WinSW `2.x` the binary compatibility of extension APIs *is not guaranteed*.
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
Runaway Process Killer Extension
|
||||
===
|
||||
|
||||
In particular cases Windows service wrapper may leak the process after the service completion.
|
||||
It happens when WinSW gets terminated without executing the shutdown logic.
|
||||
Examples: force kill of the service process, .NET Runtime crash, missing permissions to kill processes or a bug in the logic.
|
||||
|
||||
Such runaway processes may conflict with the service process once it restarts.
|
||||
This extension allows preventing it by running the runaway process termination on startup before the executable gets started.
|
||||
|
||||
Since: [WinSW 2.0](../../CHANGELOG.md).
|
||||
|
||||
### Usage
|
||||
|
||||
The extension can be configured via the [XML Configuration File](../xmlConfigFile.md). Configuration sample:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
<service>
|
||||
<id>sampleService</id>
|
||||
<name>Sample service</name>
|
||||
<description>This is a stub service.</description>
|
||||
<executable>%BASE%\sleep.bat</executable>
|
||||
<arguments></arguments>
|
||||
<logmode>rotate</logmode>
|
||||
|
||||
<extensions>
|
||||
<!-- This is a sample configuration for the RunawayProcessKiller extension. -->
|
||||
<extension enabled="true"
|
||||
className="winsw.Plugins.RunawayProcessKiller.RunawayProcessKillerExtension"
|
||||
id="killOnStartup">
|
||||
<!-- Absolute path to the PID file, which stores ID of the previously launched process. -->
|
||||
<pidfile>%BASE%\pid.txt</pidfile>
|
||||
<!-- Defines the process termination timeout in milliseconds.
|
||||
This timeout will be applied multiple times for each child process.
|
||||
After the timeout WinSW will try to force kill the process.
|
||||
-->
|
||||
<stopTimeout>5000</stopTimeout>
|
||||
<!-- If true, the parent process will be terminated first if the runaway process gets terminated. -->
|
||||
<stopParentFirst>false</stopParentFirst>
|
||||
</extension>
|
||||
</extensions>
|
||||
</service>
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
* The current implementation of the the extension checks only the root process (started executable)
|
||||
* If the runaway process is detected the entire, the entire process tree gets terminated
|
||||
* WinSW gives the runaway process a chance to the gracefully terminate.
|
||||
If it does not do it within the timeout, the process will be force-killed.
|
||||
* If the force kill fails, the WinSW startup continues with a warning.
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
Shared Directory Mapper extension
|
||||
====
|
||||
|
||||
By default Windows does not establish shared drive mapping for services even if it is configured in the Windows service profile.
|
||||
And sometimes it is impossible to workaround it due to the domain policies.
|
||||
|
||||
This extension allows mapping external shared directories before starting up the executable.
|
||||
|
||||
Since: [WinSW 2.0](../../CHANGELOG.md).
|
||||
|
||||
### Usage
|
||||
|
||||
The extension can be configured via the [XML Configuration File](../xmlConfigFile.md).
|
||||
Configuration sample:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
<service>
|
||||
<id>sampleService</id>
|
||||
<name>Sample service</name>
|
||||
<description>This is a stub service.</description>
|
||||
<executable>%BASE%\sleep.bat</executable>
|
||||
<arguments></arguments>
|
||||
<logmode>rotate</logmode>
|
||||
|
||||
<extensions>
|
||||
<extension enabled="true" className="winsw.Plugins.SharedDirectoryMapper.SharedDirectoryMapper" id="mapNetworDirs">
|
||||
<mapping>
|
||||
<map enabled="false" label="N:" uncpath="\\UNC"/>
|
||||
<map enabled="false" label="M:" uncpath="\\UNC2"/>
|
||||
</mapping>
|
||||
</extension>
|
||||
</extensions>
|
||||
</service>
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
* If the extension fails to map the drive, the startup fails
|
||||
Loading…
Reference in New Issue