win_nssm: refactor to fix issues, support check mode and add more features (#45693)

* win_nssm: rename cmdlets to use approved verbs, rename service name parameters

* win_nssm: improve code style and cmdlets ordering

* win_nssm: always escape all command line parameters with Argv-ToString

fix error when the service name contains quotes

* win_nssm: use Fail-Json instead of exceptions and remove global try/catch

* win_nssm: small refactoring, inline some functions

* win_nssm: refactoring - add a generic cmdlet to idempotently set any nssm service parameter

* win_nssm: refactoring - inline some functions

To make the code more malleable for future changes

* win_nssm: change application, stdout_file and stderr_file options type to path

* win_nssm: deprecates app_parameters, rename app_parameters_free_form to arguments, and add support for list of parameters

* win_nssm: add support of check mode

* win_nssm: add working_directory option

* win_nssm: add display_name and description options

* win_nssm: minor changes

* win_nssm: remove some sanity exclusions

* win_nssm: avoid using aliases and minor style fixes

* win_nssm: doc and ui improvements

* win_nssm: remove sanity exclusions

* win_nssm: minor revision

* win_nssm: deprecates dependencies, start_mode, user and password parameters and some choices of state in favor of win_service

* win_nssm: fix style

* win_nssm: add executable option to specify the location of the NSSM utility

* win_nssm: add missing parameter types

* win_nssm: add diff mode support

* win_nssm: avoid displaying depreciation warning if default value is assigned

* win_nssm: fix variable scope

* win_nssm: use the explicit -LiteralPath parameter name instead of -Path

* win_nssm: fix documentation

* win_nssm: add porting guide entries

* win_nssm: add changelog fragment

lib/ansible/modules/windows/win_nssm.py

@@ -15,9 +15,10 @@ DOCUMENTATION = r'''
 ---
 module: win_nssm
 version_added: "2.0"
-short_description: NSSM - the Non-Sucking Service Manager
+short_description: Install a service using NSSM
 description:
-    - nssm is a service helper which doesn't suck. See U(https://nssm.cc/) for more information.
+    - Install a Windows service using the NSSM wrapper.
+    - NSSM is a service helper which doesn't suck. See U(https://nssm.cc/) for more information.
 requirements:
     - "nssm >= 2.24.0 # (install via M(win_chocolatey)) C(win_chocolatey: name=nssm)"
 options:
@@ -29,50 +30,75 @@ options:
   state:
     description:
       - State of the service on the system.
-      - Note that NSSM actions like "pause", "continue", "rotate" do not fit the declarative style of ansible, so these should be implemented via the
-        ansible command module.
+      - Values C(started), C(stopped), and C(restarted) are deprecated since v2.8,
+        please use the M(win_service) module instead to start, stop or restart the service.
     type: str
     choices: [ absent, present, started, stopped, restarted ]
-    default: started
+    default: present
   application:
     description:
       - The application binary to run as a service
-      - "Specify this whenever the service may need to be installed (state: present, started, stopped, restarted)"
-      - "Note that the application name must look like the following, if the directory includes spaces:"
-      - 'nssm install service "C:\\Program Files\\app.exe\\" "C:\\Path with spaces\\"'
-      - >
-        See commit 0b386fc1984ab74ee59b7bed14b7e8f57212c22b in the nssm.git project for more info:
-        U(https://git.nssm.cc/?p=nssm.git;a=commit;h=0b386fc1984ab74ee59b7bed14b7e8f57212c22b)
+      - Required when I(state) is C(present), C(started), C(stopped), or C(restarted).
+    type: path
+  executable:
+    description:
+    - The location of the NSSM utility (in case it is not located in your PATH).
+    type: path
+    default: nssm.exe
+    version_added: "2.8.0"
+  description:
+    description:
+      - The description to set for the service.
+    type: str
+    version_added: "2.8.0"
+  display_name:
+    description:
+      - The display name to set for the service.
+    type: str
+    version_added: "2.8.0"
+  working_directory:
+    version_added: "2.8.0"
+    description:
+      - The working directory to run the service executable from (defaults to the directory containing the application binary)
+    type: path
+    aliases: [ app_directory, chdir ]
   stdout_file:
     description:
       - Path to receive output.
-    type: str
+    type: path
   stderr_file:
     description:
       - Path to receive error output.
-    type: str
+    type: path
   app_parameters:
     description:
       - A string representing a dictionary of parameters to be passed to the application when it starts.
-      - Use either this or C(app_parameters_free_form), not both.
+      - DEPRECATED since v2.8, please use I(arguments) instead.
+      - This is mutually exclusive with I(arguments).
     type: str
-  app_parameters_free_form:
+  arguments:
     description:
-      - Single string of parameters to be passed to the service.
-      - Use either this or C(app_parameters), not both.
+      - Parameters to be passed to the application when it starts.
+      - This can be either a simple string or a list.
+      - This parameter was renamed from I(app_parameters_free_form) in 2.8.
+      - This is mutually exclusive with I(app_parameters).
+    aliases: [ app_parameters_free_form ]
     type: str
     version_added: "2.3"
   dependencies:
     description:
       - Service dependencies that has to be started to trigger startup, separated by comma.
+      - DEPRECATED since v2.8, please use the M(win_service) module instead.
     type: list
   user:
     description:
       - User to be used for service startup.
+      - DEPRECATED since v2.8, please use the M(win_service) module instead.
     type: str
   password:
     description:
       - Password to be used for service startup.
+      - DEPRECATED since v2.8, please use the M(win_service) module instead.
     type: str
   start_mode:
     description:
@@ -80,84 +106,66 @@ options:
       - C(delayed) causes a delayed but automatic start after boot (added in version 2.5).
       - C(manual) means that the service will start only when another service needs it.
       - C(disabled) means that the service will stay off, regardless if it is needed or not.
+      - DEPRECATED since v2.8, please use the M(win_service) module instead.
     type: str
     choices: [ auto, delayed, disabled, manual ]
     default: auto
 seealso:
-- module: win_service
+  - module: win_service
+notes:
+  - The service will NOT be started after its creation when C(state=present).
+  - Once the service is created, you can use the M(win_service) module to start it or configure
+    some additionals properties, such as its startup type, dependencies, service account, and so on.
 author:
   - Adam Keech (@smadam813)
   - George Frank (@georgefrank)
   - Hans-Joachim Kliemeck (@h0nIg)
   - Michael Wild (@themiwi)
+  - Kevin Subileau (@ksubileau)
 '''
 
 EXAMPLES = r'''
-# Install and start the foo service
-- win_nssm:
-    name: foo
-    application: C:\windows\foo.exe
-
-# Install and start the foo service with a key-value pair argument
-# This will yield the following command: C:\windows\foo.exe -bar true
-- win_nssm:
-    name: foo
-    application: C:\windows\foo.exe
-    app_parameters: -bar=true
-
-# Install and start the foo service with a single parameter
-# This will yield the following command: C:\windows\\foo.exe bar
-- win_nssm:
-    name: foo
-    application: C:\windows\foo.exe
-    app_parameters: _=bar
-
-# Install and start the foo service with a mix of single params, and key value pairs
-# This will yield the following command: C:\windows\\foo.exe bar -file output.bat -foo false
-- win_nssm:
-    name: foo
-    application: C:\windows\foo.exe
-    app_parameters: _=bar; -file=output.bat; -foo=false
-
-# Use the single line parameters option to specify an arbitrary string of parameters
-# for the service executable
-- name: Make sure the Consul service runs
+- name: Install the foo service
   win_nssm:
-    name: consul
-    application: C:\consul\consul.exe
-    app_parameters_free_form: agent -config-dir=C:\consul\config
-    stdout_file: C:\consul\log.txt
-    stderr_file: C:\consul\error.txt
+    name: foo
+    application: C:\windows\foo.exe
 
-# Install and start the foo service, redirecting stdout and stderr to the same file
-- win_nssm:
+# This will yield the following command: C:\windows\foo.exe bar "true"
+- name: Install the Consul service with a list of parameters
+  win_nssm:
+    name: Consul
+    application: C:\consul\consul.exe
+    arguments:
+      - agent
+      - -config-dir=C:\consul\config
+
+# This is strictly equivalent to the previous example
+- name: Install the Consul service with an arbitrary string of parameters
+  win_nssm:
+    name: Consul
+    application: C:\consul\consul.exe
+    arguments: agent -config-dir=C:\consul\config
+
+
+# Install the foo service, an then configure and start it with win_service
+- name: Install the foo service, redirecting stdout and stderr to the same file
+  win_nssm:
     name: foo
     application: C:\windows\foo.exe
     stdout_file: C:\windows\foo.log
     stderr_file: C:\windows\foo.log
 
-# Install and start the foo service, but wait for dependencies tcpip and adf
-- win_nssm:
+- name: Configure and start the foo service using win_service
+  win_service:
     name: foo
-    application: C:\windows\foo.exe
-    dependencies: 'adf,tcpip'
-
-# Install and start the foo service with dedicated user
-- win_nssm:
-    name: foo
-    application: C:\windows\foo.exe
+    dependencies: [ adf, tcpip ]
     user: foouser
     password: secret
-
-# Install the foo service but do not start it automatically
-- win_nssm:
-    name: foo
-    application: C:\windows\foo.exe
-    state: present
     start_mode: manual
+    state: started
 
-# Remove the foo service
-- win_nssm:
+- name: Remove the foo service
+  win_nssm:
     name: foo
     state: absent
 '''