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