winsw

一、WinSW介绍

官方介绍如下：

WinSW is an executable binary, which can be used to wrap and manage a custom process as a Windows service.

现实生活中，我们使用windows系统的电脑的时候，可能会遇到这么一种情况：想把一些应用程序添加为开机启动项。对于有图形界面的应用程序，一般不存在问题。但是如果想运行命令行应用程序，就不是那么方便了。一种笨办法就是写个bat，放到启动文件夹里，就可以开机启动了。开机之后，你就会发现，这样会一直显示着一个CMD窗口，而且这个窗口不能关，关了程序就停了。

其实Windows系统自带后台程序管理的功能，也就是我们经常用到的服务。但是Windows的服务只有程序的开发者在写程序的时候引用到这个功能，我们才能利用服务来控制程序的启动和关闭。对于一般的命令行程序来说，没办法利用服务。

今天要介绍的WinSW，它就是一个可以将Windows上的任何一个程序注册为服务的工具。同样也可以进行卸载该服务。

二、WinSW使用

1、工具下载

这个工具可以在GitHub上【https://github.com/kohsuke/winsw/releases】进行下载。当然，在GitHub上也可以获取到工具的源码【https://github.com/kohsuke/winsw】。

下载完之后最好把文件改成一个比较短小的名字，例如：WinSW.exe 方便后面输入命令时使用。

2、修改配置文件

我们需要编写一个和程序同名的XML文件作为WinSW的配置文件。大体的格式如下：

这里只是简单介绍使用WinSW的流程，配置项实际也不止那么几个，在第三部分有关于配置文件的详细解释。

3、注册服务

配置文件编写完之后，将配置文件与WinSW.exe放在同一目录中。注意对应WinSW.exe的配置文件名称应该是WinSW.xml。此时，WinSW.exe、WinSW.xml以及你的应用程序应该都是在同一目录中。然后用管理员权限打开一个命令提示符窗口，cd进入到应用程序所在目录，可以通过输入下面的命令来进行控制应用程序对应的服务：

winsw install 安装服务

winsw uninstall 卸载服务

winsw start 开启服务

winsw stop 停止服务

winsw restart 重新启动服务

winsw status 检查服务的当前状态

安装服务命令执行后，如果返回值为0，就表示服务已经安装成功。此时在windows服务的窗口，就能看到你刚才安装的服务了。

三、WinSW配置说明（翻译xmlConfigFile.md）

1、配置文件的文件结构

配置文件是一个XML格式文件，其根元素必须是“service”节点。

2、配置文件中的环境变量表达式

XML配置文件中，可以包含形如“%Name%”的环境变量表达式。如果发现这种情况，将会自动被变量的实际值替换掉。如果引用未定义的环境变量，则不会进行替换。

此外，服务包装器本身定义了一个名为“BASE”的环境变量，它指向一个包含重命名为“winsw.exe”的文件的目录。这在引用同一目录中的其他文件的时候是很有用的。由于这本身就是一个环境变量，所以这个值也可以从服务包装器启动的子进程中访问。

3、配置项说明

（1）id

指定在Windows系统内部使用的识别服务的ID。在系统中安装的所有服务中，这必须是唯一的，它应该完全由字母数字字符组成。

（2）name

服务的简短名称，它可以包含空格和其他字符。尽量简短，就像“id”一样，在系统的所有服务名称中，也要保持唯一。

（3）description

该服务可读描述。当选中该服务时，它将显示在Windows服务管理器中。

（4）executable

该元素指定要启动的可执行文件。它可以是绝对路径，也可以指定可执行文件的名称，然后从环境变量“PATH”中搜索（需要注意的是，服务经常在不同的用户账户中运行，因此它可能需要有不同于你设置在环境变量Path中的路径）。

（5）startmode

该元素指定Windows服务的启动模式。它可以是下列值之一：开机、系统、自动或手动。有关详细信息，请参阅MSDN【https://msdn.microsoft.com/en-us/library/aa384896%28v=vs.85%29.aspx】。默认值是“Automatic”。

（6）delayedAutoStart

这个布尔选项允许在定义“自动”启动模式时延时启动。关于延时启动模式，可参阅【https://blogs.technet.microsoft.com/askperf/2008/02/02/ws2008-startup-processes-and-delayed-automatic-start】。

请注意，延时启动模式在早于Windows 7和Windows Server 2008的操作系统中可能失效。在这种情况下，Windows服务安装可能会失败。

（7）depend

指定该服务所依赖的其他服务的id。当服务“X”依赖于服务“Y”时，“X”只能在“Y”运行后运行。可以使用多个元素来指定多个依赖项。

（8）logging

关于服务进程的日志以及错误信息，有单独的一个配置说明文档【WinSW Logging and Error Reporting】，咱们下次再详细说。

（9）argument

该元素指定要传递给可执行文件的参数。

如果有必要，Winsw会给每一个参数外加引号（“”），所以为了避免双重引号，尽量不要在参数中使用引号。

为了向后兼容，可以使用“arguments”来指定单个元素中的整个命令行。

（10）stopargument/stopexecutable

请求停止服务时，winsw通过调用终止进程的API函数来立即终结服务。然而，如果存在“stopargument”元素，winsw将通过使用”stopargument“作为参数，来启动“executable“元素（或者是”stopexecutable“元素）中配置的进程，来代替调用终止进程的API函数。期望通过这种方式来优雅的关闭服务进程。

然后，Winsw将等待两个进程自行退出，然后向Windows报告该服务已经终止。

当你使用“stopargument”元素时，你必须使用“startargument”元素代替“argument”元素。参见下面的完整示例：

catalina.sh

jpda

run

catalina.sh

stop

注意，元素的名称是“startargument”，而不是“startarguments”。因此，要指定多个参数，你必须指定多个元素。

（11）stoptimeout

当服务被要求停止时，winsw首先尝试调用GenerateConsoleCtrlEvent 方法（类似于Ctrl+C），然后等待长达15秒的时间，让进程自行退出。

如果这样做了，进程关闭还是失败了（或者如果进程没有控制台），

然后winsw会调用终止进程的API函数来立即终止服务。

这个可选元素允许您改变这个“15秒”的值，这样您就可以控制winsw等待服务进程自行关闭的时间。

如何指定时间期限，可参考下面的“onfailure”元素的设置：

10sec

（12）env

如果有必要，可以使用这个可多次指定的可选元素，为子进程设置环境变量。其语法是:

（13）interactive

如果指定了这个可选的元素，那么该服务将被允许与桌面交互，比如显示一个新的窗口和对话框。

如果你的程序需要GUI，那么设置如下：

请注意，自从引入UAC（Windows Vista及之后的版本）以来，服务不再被允许与桌面交互。

在这些操作系统中，所有这一切都是为了允许用户切换到一个单独的窗口来与服务交互。

（14）beeponshutdown

这个可选元素是为了在服务关闭时发出简单的音调。

这个特性应该只用于调试，因为一些操作系统和硬件不支持这种功能。

（15）download

这个可选元素可以多次指定，让服务包装器从URL检索资源，并将其作为文件放置在本地。这个操作是在服务启动时运行的，在“executable”指定的应用程序启动之前。

对于需要身份验证的服务器，必须根据认证的类型指定一些参数。只有基本身份验证需要额外的子参数。支持的身份验证类型是:

none：默认类型，不能指定

sspi：微软认证，包括Kerberos、NTLM等。

basic：基本身份认证，子参数包括：

1）user=“UserName”

2）password=“Password”

3）unsecureAuth=“true”：default=“false”

当传输协议是未加密的HTTP数据传输时，参数“unsecureAuth”才生效。这是一个安全漏洞，因为凭证是用明文发送的！对于SSPI认证，这是不相关的，因为身份验证令牌是加密的。

对于使用HTTPS传输协议的目标服务器这是必须的，因为服务器发出的CA证书是客户端信任的。这通常是服务器在Internet上的情况。当一个组织在内网中使用自发布的CA时，情况可能不是这样。在这种情况下，有必要将CA导入到Windows客户端的证书MMC。可以看一下微软的说明（https://technet.microsoft.com/en-us/librar/cc754841.aspx）。自发布CA必须被导入到计算机的受信任的根证书颁发机构。

默认情况下，如果操作失败（例如，无效的下载地址），“download”命令也不会在服务启动时失败。为了在这种情况下强制下载失败，可以指定“failOnError”布尔属性。示例如下：

这是开发自动更新服务的另一个有用的构建块。

（16）onfailure

这个可选的可重复元素控制了winsw启动的进程失败后的行为（例如，执行带有非零退出码的退出操作）。

例如，上面的配置使服务在第一次故障后10秒内重新启动，在第二次失败后20秒重新启动，如果服务再次失败，Windows将重新启动。

每个元素都包含一个强制的“action”属性，它控制着Windows SCM将要做什么，以及可选的“延迟”属性，它控制着延迟，直到采取行动为止。“action”属性的值包含以下几种：

restart：重启服务

reboot：重启系统

none：什么也不做，就让服务那么停着

延迟属性的可能后缀是sec/secs/min/mins/hours/day/days。如果未设置，延迟属性默认为0。

如果服务持续失败的次数超出了配置的“onfailure”的数量，那么最后的操作将会被重复。因此，如果只是想要自动重启服务，只需指定一个“onfailure”元素即可：

（17）resetfailure

这个可选元素控制了Windows SCM重新设置故障计数的时间。

例如，如果指定``，并且您的服务持续运行超过一个小时，那么故障计数将重置为零。

这会影响故障操作的行为（见上面的“onfailure”）。

换句话说，这是你认为服务已经成功运行的持续时间。

默认值为1天。

（18）Service account

有可能需要指定服务运行所需要的的useraccount（和密码）。要做到这一点，可以按照下面的方法指定一个“serviceaccount”元素：

YOURDOMAIN

useraccount

Pa55w0rd

true

“”是可选的。如果设置为“true”，则会自动给上面列出的用户设置“Allow Log On As A Service”的权限。

可以使用（组）管理服务帐户 附加'$'到帐户名称，并删除'password'元素：

YOURDOMAIN

gmsa_account$

true

（19）Working directory

有些服务需要使用指定的工作目录运行。

要做到这一点，要指定一个像这样的“workingdirectory”元素：

C:\application

（20）priority

可选地指定服务流程的调度优先级（类似于Unix）。可能的值有“idle”、“belownormal”、“normal”、“abovenormal”、“high”、“realtime”（大小写不敏感）。

idle

指定高于正常值的优先级会产生意想不到的后果。请参阅MSDN文章ProcessPriorityClass Enumeration来了解详细信息。

这个特性主要是为了在较低的优先级上启动一个进程，以避免干扰计算机的交互使用。

（21）stopparentprocessfirst

可选地指定服务关闭的顺序。

如果“true”，父进程首先关闭。

当主进程是一个控制台时，这是很有用的，它可以响应Ctrl+C命令，并优雅地关闭子进程。

true