From 03ae1ef8275dfccff00c08db2db3da53930eaab9 Mon Sep 17 00:00:00 2001 From: Next Turn <45985406+NextTurn@users.noreply.github.com> Date: Sun, 30 Aug 2020 08:56:18 +0800 Subject: [PATCH] Revise docs for 3.0.0-alpha.4 (#645) * Remove invalid start modes * since * Fix typos * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update release-drafter.yml * Update release-drafter.yml * Add commands * Add `autoRefresh` * Add link to v2 branch * Latest SemVar * Update build.yml * Update release-drafter.yml --- .github/release-drafter.yml | 15 ++++++------ CONTRIBUTING.md | 28 ++++++++++------------ README.md | 19 ++++++++------- docs/cli-commands.md | 22 ++++++++++++++++- docs/xml-config-file.md | 47 ++++++++++++++++++++++++------------- eng/build.yml | 10 ++++---- 6 files changed, 88 insertions(+), 53 deletions(-) diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index bb25443..dd5cc9d 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -1,12 +1,11 @@ -# Configuration for Release Drafter: https://github.com/toolmantim/release-drafter +# Configuration for Release Drafter: https://github.com/release-drafter/release-drafter name-template: WinSW v$NEXT_PATCH_VERSION tag-template: v$NEXT_PATCH_VERSION + # This repo follows the Semantic Versioning 2.0.0 approach: https://semver.org/ version-template: $MAJOR.$MINOR.$PATCH -template: | - - $CHANGES +template: $CHANGES # Emoji reference: https://gitmoji.carloscuesta.me/ categories: @@ -14,18 +13,18 @@ categories: label: removed - title: ⚠️ Deprecated label: deprecated - - title: ":tada: New features" + - title: 🎉 New features label: new-feature - title: 🚀 Enhancements label: enhancement - - title: 🐛 Bug Fixes + - title: 🐛 Bug fixes label: bug - - title: ":package: Packaging changes" + - title: 📦 Packaging changes label: packaging - title: 📝 Documentation updates label: documentation # Default label used by Dependabot - - title: ":arrow_up: Dependency updates" + - title: ⬆️ Dependency updates label: dependencies - title: 👻 Maintenance labels: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17d4044..68beca1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,30 @@ -# Contributing +# Contribute ## Prerequisites -You need to install either of the followings to develop .NET. +[.NET 5 SDK or later](https://dotnet.microsoft.com/download/dotnet/5.0) and your favorite code editor. -- [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) with *.NET desktop development* workload, which includes .NET SDK. -- .NET SDK and your favorite code editor. - - You can find .NET SDK installation instructions on the [Download .NET](https://dotnet.microsoft.com/download) page. - - You can try [Visual Studio Code](https://code.visualstudio.com/Download), which is an open source and cross-platform editor. +- [Visual Studio 2019 or later](https://visualstudio.microsoft.com/downloads/) with the **.NET desktop development** workload +- [Visual Studio Code](https://code.visualstudio.com/Download) with the [C# for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) extension -## Developing in Visual Studio +## Develop in Visual Studio -You can open `src\winsw.sln` and then build and run tests from within Visual Studio. +You can open *src\WinSW.sln* and then build and run tests from within Visual Studio. -## Developing with .NET SDK +## Develop with .NET CLI -### Building +### Build ```console -dotnet build src\winsw.sln +dotnet build src\WinSW.sln ``` -### Testing +### Test ```console -dotnet test src\Test\winswTests\winswTests.csproj +dotnet test src\WinSW.sln ``` -## Project Structure +## See also -You can find the project structure guideline [here](docs/developer/project-structure.md). +[How to: Debug Windows Service Applications](https://docs.microsoft.com/dotnet/framework/windows-services/how-to-debug-windows-service-applications) diff --git a/README.md b/README.md index 1f00e1f..c86df56 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Windows Service Wrapper in a permissive license [![Github All Releases](https://img.shields.io/github/downloads/winsw/winsw/total?style=flat-square)](https://github.com/winsw/winsw/releases) -[![GitHub Release](https://img.shields.io/github/v/release/winsw/winsw?include_prereleases&style=flat-square)](https://github.com/winsw/winsw/releases) +[![GitHub Release](https://img.shields.io/github/v/release/winsw/winsw?include_prereleases&sort=semver&style=flat-square)](https://github.com/winsw/winsw/releases) [![NuGet](https://img.shields.io/nuget/v/WinSW?style=flat-square)](https://www.nuget.org/packages/WinSW/) [![Build Status](https://img.shields.io/azure-devops/build/winsw/aabe43dd-6f6d-4660-b5dd-5b79e1e2ef4e/1?style=flat-square)](https://dev.azure.com/winsw/winsw/_build?definitionId=1&_a=summary) [![Deployment Status](https://img.shields.io/azure-devops/release/winsw/aabe43dd-6f6d-4660-b5dd-5b79e1e2ef4e/1/1?style=flat-square)](https://dev.azure.com/winsw/winsw/_release?_a=releases&view=mine&definitionId=1) @@ -10,7 +10,7 @@ WinSW wraps and manages any application as a Windows service. -**We are actively developing WinSW 3. Please refer to the v2 branch for previous version documentation.** +**We are actively developing WinSW 3. Please refer to the [v2](https://github.com/winsw/winsw/tree/master) branch for previous version documentation.** **Please help us prioritize items by voting or commenting on the issues!** @@ -26,11 +26,11 @@ For systems without .NET Framework, the project provides native 64-bit and 32-bi More executables can be added upon request. [.NET Framework system requirements](https://docs.microsoft.com/dotnet/framework/get-started/system-requirements)\ -Preinstalled on Windows 10, version 1511 and Windows Server 2016.\ -Installable on Windows 7 SP1 and Windows Server 2008 R2 SP1. +Preinstalled since Windows 10, version 1511 and Windows Server 2016.\ +Installable since Windows 7 SP1 and Windows Server 2008 R2 SP1. [.NET 5 system requirements](https://github.com/dotnet/core/blob/master/release-notes/5.0/5.0-supported-os.md)\ -Supported on Windows 7 SP1, Windows Server (Core) 2012 R2 and Nano Server, version 1809. +Supported since Windows 7 SP1, Windows Server (Core) 2012 R2 and Nano Server, version 1809. ## Download @@ -64,10 +64,11 @@ Your renamed *WinSW.exe* binary also accepts the following commands: Experimental commands: -| Command | Description | -| ------- | ----------- | -| dev ps | Draws the process tree associated with the service. | -| dev kill | Terminates the service if it has stopped responding. | +| Command | Description | +| ------- | ----------- | +| [dev ps](docs/cli-commands.md#dev-ps-command) | Draws the process tree associated with the service. | +| [dev kill](docs/cli-commands.md#dev-kill-command) | Terminates the service if it has stopped responding. | +| [dev list](docs/cli-commands.md#dev-list-command) | Lists services managed by the current executable. | Most commands require Administrator privileges to execute. WinSW will prompt for UAC in non-elevated sessions. diff --git a/docs/cli-commands.md b/docs/cli-commands.md index 914425e..e247f19 100644 --- a/docs/cli-commands.md +++ b/docs/cli-commands.md @@ -247,5 +247,25 @@ Draws the process tree associated with the service. ### Usage ```console -winsw dev [] ps +winsw dev ps [] +``` + +## `dev kill` command + +Terminates the service if it has stopped responding. + +### Usage + +```console +winsw dev kill [] [--no-elevate] +``` + +## `dev list` command + +Lists services managed by the current executable. + +### Usage + +```console +winsw dev list ``` diff --git a/docs/xml-config-file.md b/docs/xml-config-file.md index e11ed60..da3edf4 100644 --- a/docs/xml-config-file.md +++ b/docs/xml-config-file.md @@ -46,6 +46,11 @@ Specifies the ID that Windows uses internally to identify the service. This has to be unique among all the services installed in a system, and it should consist entirely out of alpha-numeric characters. +### executable + +This element specifies the executable to be launched. +It can be either absolute path, or you can just specify the executable name and let it be searched from `PATH` (although note that the services often run in a different user account and therefore it might have different `PATH` than your shell does.) + ### name Short display name of the service, which can contain spaces and other characters. @@ -56,15 +61,10 @@ This shouldn't be too long, like ``, and this also needs to be unique among Long human-readable description of the service. This gets displayed in Windows service manager when the service is selected. -### executable - -This element specifies the executable to be launched. -It can be either absolute path, or you can just specify the executable name and let it be searched from `PATH` (although note that the services often run in a different user account and therefore it might have different `PATH` than your shell does.) - ### startmode This element specifies the start mode of the Windows service. -It can be one of the following values: Boot, System, Automatic, or Manual. +It can be one of the following values: Automatic, or Manual. For more information, see the [ChangeStartMode method](https://docs.microsoft.com/windows/win32/cimwin32prov/changestartmode-method-in-class-win32-service). The default value is `Automatic`. @@ -237,12 +237,12 @@ This operation runs when the service is started, before the application specifie For servers requiring authentication some parameters must be specified depending on the type of authentication. Only the basic authentication requires additional sub-parameters. Supported authentication types are: -* `none`: default, must not be specified -* `sspi`: Windows [Security Support Provider Interface](https://docs.microsoft.com/windows/win32/secauthn/sspi) including Kerberos, NTLM etc. -* `basic`: Basic authentication, sub-parameters: - * `user="UserName"` - * `password="Passw0rd"` - * `unsecureAuth="true": default="false"` +- `none`: default, must not be specified +- `sspi`: Windows [Security Support Provider Interface](https://docs.microsoft.com/windows/win32/secauthn/sspi) including Kerberos, NTLM etc. +- `basic`: Basic authentication, sub-parameters: + - `user="UserName"` + - `password="Passw0rd"` + - `unsecureAuth="true": default="false"` The parameter `unsecureAuth` is only effective when the transfer protocol is HTTP - unencrypted data transfer. This is a security vulnerability because the credentials are send in clear text! For a SSPI authentication this is not relevant because the authentication tokens are encrypted. @@ -299,9 +299,9 @@ For example, the above configuration causes the service to restart in 10 seconds Each element contains a mandatory `action` attribute, which controls what Windows SCM will do, and optional `delay` attribute, which controls the delay until the action is taken. The legal values for action are: -* `restart`: restart the service -* `reboot`: reboot Windows -* `none`: do nothing and leave the service stopped +- `restart`: restart the service +- `reboot`: reboot Windows +- `none`: do nothing and leave the service stopped The possible suffix for the delay attribute is sec/secs/min/mins/hour/hours/day/days. If missing, the delay attribute defaults to 0. @@ -328,7 +328,7 @@ The security descriptor string for the service in SDDL form. For more information, see [Security Descriptor Definition Language](https://docs.microsoft.com/windows/win32/secauthz/security-descriptor-definition-language). ```xml - + ``` ### Service account @@ -434,3 +434,18 @@ Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `rea Specifying a priority higher than normal has unintended consequences. For more information, see [ProcessPriorityClass Enumeration](https://docs.microsoft.com/dotnet/api/system.diagnostics.processpriorityclass) in .NET docs. This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage. + +### Auto refresh + +```xml +true +``` + +Automatically refreshes the service properties when the service starts or the following commands are executed: + +- [start](cli-commands.md#start-command) +- [stop](cli-commands.md#stop-command) +- [restart](cli-commands.md#restart-command) +- [test](cli-commands.md#test-command) + +The default value is `true`. diff --git a/eng/build.yml b/eng/build.yml index 33733f4..28c9a1e 100644 --- a/eng/build.yml +++ b/eng/build.yml @@ -51,10 +51,6 @@ jobs: command: test projects: src\WinSW.Tests\WinSW.Tests.csproj arguments: -c $(BuildConfiguration) --collect "XPlat Code Coverage" --no-build - - task: NuGetToolInstaller@1 - displayName: Install Nuget - inputs: - checkLatest: true - task: NuGetCommand@2 displayName: Pack inputs: @@ -62,21 +58,27 @@ jobs: packagesToPack: WinSW.nuspec versioningScheme: byEnvVar versionEnvVar: BuildVersion + - publish: artifacts\publish\WinSW.NET461.exe artifact: WinSW.NET461.exe_$(BuildConfiguration) displayName: Publish .NET 4.6.1 + - publish: artifacts\publish\WinSW.NETCore.x64.zip artifact: WinSW.NETCore.x64.zip_$(BuildConfiguration) displayName: Publish .NET Core x64 .zip + - publish: artifacts\publish\WinSW.NETCore.x86.zip artifact: WinSW.NETCore.x86.zip_$(BuildConfiguration) displayName: Publish .NET Core x86 .zip + - publish: artifacts\publish\WinSW.NETCore.x64.exe artifact: WinSW.NETCore.x64.exe_$(BuildConfiguration) displayName: Publish .NET Core x64 .exe + - publish: artifacts\publish\WinSW.NETCore.x86.exe artifact: WinSW.NETCore.x86.exe_$(BuildConfiguration) displayName: Publish .NET Core x86 .exe + - publish: $(Build.ArtifactStagingDirectory)\WinSW.$(BuildVersion).nupkg artifact: WinSW.nupkg_$(BuildConfiguration) displayName: Publish Nuget