Servy PowerShell Module

Table of Contents

1. Introduction
2. Installation
3. Usage Examples
4. Cmdlets Reference
5. Troubleshooting
6. References

Introduction

The Servy PowerShell Module allows you to manage Windows services easily using PowerShell. You can install, start, stop, restart, export/import configurations, check service status, show help, display the version, and uninstall services.

The PowerShell module is compatible with PowerShell 2.0+, Windows 7+ and Windows Server 2008+. If Servy is installed, the module is available at %ProgramFiles%\Servy\Servy.psm1 and will automatically locate the CLI executable. For the portable version of Servy, place the module Servy.psm1 in the same folder as servy-cli.exe. The module will automatically detect and use the local executable.

Important: If you face any issues with the PowerShell module in automated or non-interactive environments (e.g., CI/CD, Ansible, WinRM), use -Quiet option to suppress interactive output such as spinners or loading animations.

Installation

Import the module in your PowerShell session:

Import-Module "C:\Program Files\Servy\Servy.psm1" -Force

Display the version:

Show-ServyVersion -Quiet

Display help:

Show-ServyHelp

Usage Examples

Pro Tip: In PowerShell, Switch parameters (like -Quiet, -Install, or -EnableHealth) are toggle flags. You should not pass values like $true or $false to them. Simply including the flag enables it, and omitting it leaves it disabled.

Install a New Service

# CORRECT: Switch flags are used alone
Install-ServyService `
  -Quiet `
  -Name "WexflowServer" `
  -Description "Wexflow Workflow Engine" `
  -Path "C:\Program Files\dotnet\dotnet.exe" `
  -StartupDir "C:\Program Files\Wexflow Server\Wexflow.Server" `
  -Params "Wexflow.Server.dll" `
  -StartupType "Automatic" `
  -EnableHealth `
  -RecoveryAction "RestartService" `
  -HeartbeatInterval 30  `
  -MaxFailedChecks 3

# INCORRECT: Do not do this
# Install-ServyService -Quiet $true -EnableHealth $true

Export Service Configuration

Export-ServyServiceConfig `
  -Quiet `
  -Name "WexflowServer" `
  -ConfigFileType "xml" `
  -Path "C:\WexflowServer.xml"

Export-ServyServiceConfig `
  -Quiet `
  -Name "WexflowServer" `
  -ConfigFileType "json" `
  -Path "C:\WexflowServer.json"

Import Service Configuration

# CORRECT: Flags -Quiet and -Install are toggled by presence
Import-ServyServiceConfig `
  -Quiet `
  -ConfigFileType "xml" `
  -Path "C:\WexflowServer.xml" `
  -Install

Import-ServyServiceConfig `
  -Quiet `
  -ConfigFileType "json" `
  -Path "C:\WexflowServer.json"

Start, Stop, Restart, and Check Status

Start-ServyService -Quiet -Name "WexflowServer"
Get-ServyServiceStatus -Quiet -Name "WexflowServer"
Stop-ServyService -Quiet -Name "WexflowServer"
Restart-ServyService -Quiet -Name "WexflowServer"

Uninstall a Service

Uninstall-ServyService -Quiet -Name "WexflowServer"

Cmdlets Reference

Cmdlet	Parameters	Description
Install-ServyService	-Name (string, required) -Path (string, required) -DisplayName (string, optional) -Description (string, optional) -StartupDir (string, optional) -Params (string, optional) -StartupType (string, optional: Automatic, AutomaticDelayedStart, Manual, Disabled) -Priority (string, optional: Idle, BelowNormal, Normal, AboveNormal, High, RealTime) -Stdout (string, optional) -Stderr (string, optional) -StartTimeout (string, optional) -StopTimeout (string, optional) -EnableSizeRotation (switch, optional) -RotationSize (string, optional) -EnableDateRotation (switch, optional) -DateRotationType (string, optional: Daily, Weekly, Monthly) -MaxRotations (string, optional) -EnableHealth (switch, optional) -HeartbeatInterval (string, optional) -MaxFailedChecks (string, optional) -RecoveryAction (string, optional: None, RestartService, RestartProcess, RestartComputer) -MaxRestartAttempts (string, optional) -FailureProgramPath (string, optional) -FailureProgramStartupDir (string, optional) -FailureProgramParams (string, optional) -Env (string, optional) -Deps (string, optional) -User (string, optional) -Password (string, optional) -PreLaunchPath (string, optional) -PreLaunchStartupDir (string, optional) -PreLaunchParams (string, optional) -PreLaunchEnv (string, optional) -PreLaunchStdout (string, optional) -PreLaunchStderr (string, optional) -PreLaunchTimeout (string, optional) -PreLaunchRetryAttempts (string, optional) -PreLaunchIgnoreFailure (switch, optional) -PostLaunchPath (string, optional) -PostLaunchStartupDir (string, optional) -PostLaunchParams (string, optional) -EnableDebugLogs (switch, optional) -Quiet (switch, optional)	Installs a new Windows service with advanced configuration. Wraps the Servy CLI install command to turn any executable into a managed Windows service. It supports complex lifecycle management, logging, and self-healing features. Key Features: • Logging: Redirect output to files with rotation by size or date. • Health: Automated recovery actions (e.g., RestartService) based on failed heartbeats. • Lifecycle: Execute tasks before (PreLaunch) or after (PostLaunch) startup. Examples: • Install-ServyService -Name "MyApp" -Path "C:\App\app.exe" • Install-ServyService -Name "MyApp" -DisplayName "My App" -Path "C:\App\app.exe" • Install-ServyService -Name "LogApp" -Path "C:\App\app.exe" -Stdout "C:\App\stdout.log" -EnableSizeRotation -RotationSize 10 • Install-ServyService -Name "SecureApp" -Path "C:\App\app.exe" -Env "API_KEY=12345;DB_PORT=5432"
Uninstall-ServyService	-Name (string, required) -Quiet (switch, optional)	Uninstalls a Windows service by name. Completely removes the service entry from the Windows Service Control Manager (SCM) and the Servy internal database. Example: • Uninstall-ServyService -Name "MyApp" -Quiet
Start-ServyService	-Name (string, required) -Quiet (switch, optional)	Starts a Windows service. Triggers the service start signal. If any PreLaunch settings were defined during installation, the pre-launch process will be executed and must succeed before the main service starts (unless PreLaunchIgnoreFailure was used). Example: • Start-ServyService -Name "MyApp"
Stop-ServyService	-Name (string, required) -Quiet (switch, optional)	Stops a Windows service. Sends a termination signal to the service process. It respects the StopTimeout value set during installation, allowing the application to shut down gracefully before forcing termination. Example: • Stop-ServyService -Name "MyApp" -Quiet
Restart-ServyService	-Name (string, required) -Quiet (switch, optional)	Restarts a Windows service. Performs a full stop operation followed by a start operation. This is the recommended way to apply configuration changes after an import. Example: • Restart-ServyService -Name "MyApp"
Get-ServyServiceStatus	-Name (string, required) -Quiet (switch, optional)	Retrieves the current status of the service. Queries the SCM for the real-time state of the process. Possible Results: Stopped, StartPending, Running, StopPending, Paused. Example: • Get-ServyServiceStatus -Name "MyApp"
Export-ServyServiceConfig	-Name (string, required) -ConfigFileType (string, required: xml, json) -Path (string, required) -Quiet (switch, optional)	Exports the service configuration to a file. Saves all metadata (paths, timeouts, health checks, etc.) to an external file for backup or template creation. Examples: • Export-ServyServiceConfig -Name "MyApp" -ConfigFileType "json" -Path "C:\Backups\MyApp.json" • Export-ServyServiceConfig -Name "MyApp" -ConfigFileType "xml" -Path "C:\Backups\MyApp.xml"
Import-ServyServiceConfig	-ConfigFileType (string, required: xml, json) -Path (string, required) -Install (switch, optional) -Quiet (switch, optional)	Imports a configuration from a file. Loads settings from a previously exported file into the Servy database. Use the -Install switch to register the service with Windows immediately after import. Examples: • Import-ServyServiceConfig -ConfigFileType "json" -Path "C:\Configs\NewApp.json" -Install • Import-ServyServiceConfig -ConfigFileType "xml" -Path "C:\Configs\NewApp.xml"
Show-ServyHelp	-Command (string, optional) -Quiet (switch, optional)	Displays the Servy CLI help manual. Provides global usage instructions or detailed parameter explanations for a specific command if requested. Examples: • Show-ServyHelp • Show-ServyHelp -Command "install"
Show-ServyVersion	-Quiet (switch, optional)	Displays the version of the Servy binary. Outputs the version string of the servy-cli.exe file being utilized by the module. Example: • Show-ServyVersion -Quiet

Troubleshooting

1. Installation Fails When Passing $true or $false

   A common mistake in PowerShell is attempting to pass a boolean value to a switch parameter (e.g., -Quiet $true).

   • The Symptom: The command fails with a "Parameter cannot be found" error or, more commonly, PowerShell interprets $true as the next positional argument. In Install-ServyService, this often results in $true being mistakenly assigned to the -Path or -Name parameters, causing the underlying CLI call to fail.
   • The Fix: Remove the $true or $false reference. Use -Quiet to turn it on, and simply omit it to keep it off.

2. "Access Denied" Errors

   Most Servy operations (install, uninstall, start, stop) interact directly with the Windows Service Control Manager.

   • Solution: Ensure your PowerShell session is running with Administrator privileges. If you are using an IDE like VS Code, restart it as an Administrator.

3. Service Fails to Start

   If Start-ServyService returns a success message but the service status remains Stopped, the issue is likely within the application executable or the PreLaunch configuration.

   • Solution: Check your stdout and stderr logs if you configured them during installation.
   • Validation: Run the command defined in -Path and -Params manually in a command prompt to see if it crashes immediately.

4. CLI Executable Not Found

   In portable mode, the module expects servy-cli.exe to be in the same folder as Servy.psm1.

   • Solution: Verify that the files haven't been separated. If you are using the installed version, ensure %ProgramFiles%\Servy\ is in your System PATH or that the files exist in that directory.

5. Issues in Automated Environments (Ansible/CI/CD)

   Automated runners often hang if a process attempts to draw an interactive progress bar or spinner.

   • Solution: Always use the -Quiet switch in non-interactive scripts. This forces the module to output plain text logs instead of interactive UI elements.

6. Environment Variable Formatting

   The -Env and -PreLaunchEnv parameters require a specific string format.

   • Requirement: Use the Key=Value format, separated by semicolons.
   • Example: -Env "NODE_ENV=production;PORT=3000"

References

• Servy.psm1
• servy-module-examples.ps1