WinSW チートシート

• WinSW とは
• ダウンロード
• 使い方
• 設定ファイル
  • 基本設定
  • 実行ファイル
  • サービス設定
  • ログ・障害復旧
  • その他

WinSW とは

任意のプロセスを Windows サービスとして管理するための実行バイナリ。

Jenkins を Windows サービスから管理するために使われている。

2025年時点の最新版は WinSW v2.12.0 となっている(v3.0.0 はアルファ版のまま2年間更新なし)。

ダウンロード

GitHub Releases からダウンロードできる。

以下のバイナリが提供されている。

バイナリ	説明
WinSW-x64.exe	64bit環境用バイナリ
WinSW-x86.exe	32bit環境用バイナリ
WinSW.NET2.exe	.NET Framework 2.0 環境用
WinSW.NET4.exe	.NET Framework 4.0 環境用
WinSW.NET461.exe	.NET Framework 4.6.1 環境用

32/64bit環境用バイナリは .NET 環境に依存しないが、バイナリのサイズが大きい(17M 程度で .NET 版は 1M 未満)。

.NET Framework 環境用は、利用環境にインストール済みの .NET 環境に応じたものを利用する。

.NET Framework 4.6.1 のサポートは既に終了済み(2022/04/26)であるが、.NET Framework 4.6.2 以降のランタイム上での動作が引き続きサポートされるため、通常は WinSW.NET461.exe か WinSW-x64.exe を使うことになる。

使い方

基本的には以下だけでよい

• ダウンロードしたバイナリを好きな名前にリネーム
• バイナリファイルの隣に任意の名前の設定ファイル(xml)を作成
• WinSW-x64.exe install でサービス登録(バイナリをリネームした場合はその名前)(管理者権限要)

その後は Windows サービス 側から操作できる。

WinSW-x64.exe uninstall で登録したサービスを削除できるが、普通に sc コマンドでやれば良い。

sc delete <サービスID>

設定ファイル

設定ファイルは WinSW の実行ファイルの隣に service.xml などとしておいておけば良い。

シンプルな例だと以下。

<service>
  <id>myapp</id>
  <name>myapp</name>
  <description>myapp</description>
  <executable>%BASE%\myExecutable.exe</executable>
</service>

name と description は任意で、Windows サービスのGUIに表示される。

%BASE% は WinSW.exe を含むディレクトリを指す。

コンソールから起動し、Ctrl+C で終了するアプリケーションの場合は stopparentprocessfirst を指定するべきである。

  <stopparentprocessfirst>true</stopparentprocessfirst>

stopparentprocessfirst を設定すると、メインのコンソールに割り込みシグナル(SIGINT)が送られることで正常終了できる。

Java で Executable jar を起動するには以下のような感じになる。

<service>
  <id>myJavaApp</id>
  <name>myJavaApp</name>
  <env name="APP_HOME" value="%BASE%" />
  <executable>java</executable>
  <arguments>-Xrs -Xmx256m -jar "%BASE%\myApp.jar"</arguments>
</service>

設定ファイルは sample-allOptions.xml を参照。項目が多いので、以下にまとめる。

基本設定

要素名	説明
id	Windowsが内部でサービスを識別するためのユニークなID(英数字のみ)
name	サービスマネージャーに表示される短い名前(システム内でユニーク)
description	サービスマネージャーで選択した際に表示される説明

実行ファイル

要素名	説明
executable	起動する実行ファイルのパス(絶対パスまたはPATH上の実行ファイル名を指定)
arguments	サービスの起動時に実行ファイルに渡す引数
startarguments	起動時引数(stopargumentsを使用する場合に指定
stopexecutable	停止時に使用する実行ファイル(停止時に executable とは別の実行ファイルを使用する場合
stoparguments	起動時引数(executable または stopexecutableに渡す引数)
env	サービスプロセスに渡す環境変数を指定

サービス設定

要素名	説明
startmode	サービスの開始モード(Boot, System, Automatic, Manual)(デフォルトは Automatic)
delayedAutoStart	startmodeが Automatic の場合、OS起動後の高負荷を避けるため、サービスの開始を遅らせる
workingdirectory	プロセスの作業ディレクトリ
priority	プロセスのスケジューリング優先度(idle, belownormal, normal, abovenormal, high, realtime)を指定
depend	このサービスが依存する他のサービスのIDを指定(複数指定可)
stoptimeout	強制終了するまでの待機時間(デフォルトは15秒)
stopparentprocessfirst	true にすると、停止時に親プロセスを先にシャットダウンする
interactive	サービスがGUI表示などデスクトップとの対話を許可するかどうか
serviceaccount	サービスを実行するアカウント情報を設定(デフォルト LocalSystem)
allowservicelogon	true にすると、指定したユーザーに「サービスとしてログオン」の権限を自動的付与

ログ・障害復旧

要素名	説明
logpath	ログを格納するディレクトリを指定
log	ログの記録方法を指定
onfailure	プロセスが失敗(コード終了ゼロ以外)した際の動作を定義。action[restart,reboot,none] と delay を指定でき、複数設定して段階的な復旧が可能
resetfailure	失敗カウントをリセットするまでの時間を指定(デフォルトは1 day)

<log> 要素でログローテーションなどを細かく指定できる。

<logpath>%BASE%\logs</logpath>
<log mode="roll-by-size">
  <sizeThreshold>10240</sizeThreshold>
  <keepFiles>4</keepFiles>
</log>

mode	説明	サブ要素
append	ログ追記(デフォルト)。ファイルサイズが大きくなる可能性あ	N/A
reset	サービスが開始するたびに、古いログファイルを空にする	N/A
none	ログ記録なし	N/A
roll	サービスが開始するたびに、古いログファイルをローテートする	N/A
roll-by-size	サイズによるローテーション	<sizeThreshold>: サイズ上限(KB) <keepFiles>: 保存するファイル数
roll-by-time	期間によるローテーション	<pattern>: yyyyMMdd のような日付パターン
roll-by-size-time	サイズと時間によるローテーション	<sizeThreshold>, <pattern>, <autoRollAtTime>

その他

要素名	説明
download	サービス起動前に、指定したURL(from) からファイルをダウンロードし、指定した場所(to) に保存
beeponshutdown	サービス停止時にビープ音を鳴らす(デバッグ目的)
securityDescriptor	サービスのセキュリティ記述子をSDDL形式で指定