win_dsc - Add argument validation and other fixes

changelogs/fragments/win_dsc-validation.yaml

@@ -0,0 +1,4 @@
+minor_changes:
+- win_dsc - The win_dsc module will now fail if an invalid DSC property is set.
+- win_dsc - The module invocation and possible options will be displayed when running with ``-vvv``.
+- win_dsc - The Verbose logs will be returned when running with ``-vvv``.

docs/docsite/rst/porting_guides/porting_guide_2.8.rst

@@ -128,6 +128,8 @@ PowerShell module options and option choices are currently case insensitive to w
 specification. This behaviour is deprecated and a warning displayed to the user if a case insensitive match was found.
 A future release of Ansible will make these checks case sensitive.
 
+The ``win_dsc`` module will now validate the input options for a DSC resource. In previous versions invalid options would be ignored but are now not.
+
 Modules removed
 ---------------
 

docs/docsite/rst/user_guide/windows_dsc.rst

@@ -29,7 +29,7 @@ DSC and Ansible modules have a common goal which is to define and ensure the sta
 resource. Because of
 this, resources like the DSC `File resource <https://docs.microsoft.com/en-us/powershell/dsc/fileresource>`_
 and Ansible ``win_file`` can be used to achieve the same result. Deciding which to use depends 
-on the scenario. 
+on the scenario.
 
 Reasons for using an Ansible module over a DSC resource:
 
@@ -99,6 +99,67 @@ This is what the Ansible task version of the above DSC Registry resource would l
         ValueName: TestValue
         ValueData: TestData
 
+Starting in Ansible 2.8, the ``win_dsc`` module automatically validates the
+input options from Ansible with the DSC definition. This means Ansible will
+fail if the option name is incorrect, a mandatory option is not set, or the
+value is not a valid choice. When running Ansible with a verbosity level of 3
+or more (``-vvv``), the return value will contain the possible invocation
+options based on the ``resource_name`` specified. Here is an example of the
+invocation output for the above ``Registry`` task::
+
+    changed: [2016] => {
+        "changed": true,
+        "invocation": {
+            "module_args": {
+                "DependsOn": null,
+                "Ensure": "Present",
+                "Force": null,
+                "Hex": null,
+                "Key": "HKEY_LOCAL_MACHINE\\SOFTWARE\\ExampleKey",
+                "PsDscRunAsCredential_password": null,
+                "PsDscRunAsCredential_username": null,
+                "ValueData": [
+                    "TestData"
+                ],
+                "ValueName": "TestValue",
+                "ValueType": null,
+                "module_version": "latest",
+                "resource_name": "Registry"
+            }
+        },
+        "module_version": "1.1",
+        "reboot_required": false,
+        "verbose_set": [
+            "Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = ResourceSet,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.",
+            "An LCM method call arrived from computer SERVER2016 with user sid S-1-5-21-3088887838-4058132883-1884671576-1105.",
+            "[SERVER2016]: LCM:  [ Start  Set      ]  [[Registry]DirectResourceAccess]",
+            "[SERVER2016]:                            [[Registry]DirectResourceAccess] (SET) Create registry key 'HKLM:\\SOFTWARE\\ExampleKey'",
+            "[SERVER2016]:                            [[Registry]DirectResourceAccess] (SET) Set registry key value 'HKLM:\\SOFTWARE\\ExampleKey\\TestValue' to 'TestData' of type 'String'",
+            "[SERVER2016]: LCM:  [ End    Set      ]  [[Registry]DirectResourceAccess]  in 0.1930 seconds.",
+            "[SERVER2016]: LCM:  [ End    Set      ]    in  0.2720 seconds.",
+            "Operation 'Invoke CimMethod' complete.",
+            "Time taken for configuration job to complete is 0.402 seconds"
+        ],
+        "verbose_test": [
+            "Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = ResourceTest,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.",
+            "An LCM method call arrived from computer SERVER2016 with user sid S-1-5-21-3088887838-4058132883-1884671576-1105.",
+            "[SERVER2016]: LCM:  [ Start  Test     ]  [[Registry]DirectResourceAccess]",
+            "[SERVER2016]:                            [[Registry]DirectResourceAccess] Registry key 'HKLM:\\SOFTWARE\\ExampleKey' does not exist",
+            "[SERVER2016]: LCM:  [ End    Test     ]  [[Registry]DirectResourceAccess] False in 0.2510 seconds.",
+            "[SERVER2016]: LCM:  [ End    Set      ]    in  0.3310 seconds.",
+            "Operation 'Invoke CimMethod' complete.",
+            "Time taken for configuration job to complete is 0.475 seconds"
+        ]
+    }
+
+The ``invocation.module_args`` key shows the actual values that were set as
+well as other possible values that were not set. Unfortunately this will not
+show the default value for a DSC property, only what was set from the Ansible
+task. Any ``*_password`` option will be masked in the output for security
+reasons, if there are any other sensitive module options, set ``no_log: True``
+on the task to stop all task output from being logged.
+
+
 Property Types
 --------------
 Each DSC resource property has a type that is associated with it. Ansible
@@ -110,9 +171,9 @@ require certain rules.
 PSCredential
 ++++++++++++
 A ``[PSCredential]`` object is used to store credentials in a secure way, but
-Ansible has no way to serialize this over JSON. To set a DSC PSCredential property, 
-the definition of that parameter should have two entries that are suffixed with 
-``_username`` and ``_password`` for the username and password respectively. 
+Ansible has no way to serialize this over JSON. To set a DSC PSCredential property,
+the definition of that parameter should have two entries that are suffixed with
+``_username`` and ``_password`` for the username and password respectively.
 For example:
 
 .. code-block:: yaml+jinja
@@ -123,9 +184,12 @@ For example:
     SourceCredential_username: AdminUser
     SourceCredential_password: PasswordForAdminUser
 
-.. Note:: You should set ``no_log: yes`` on the task definition in
-    Ansible to ensure any credentials used are not stored in any log file or
-    console output.
+.. Note:: On versions of Ansible older than 2.8, you should set ``no_log: yes``
+    on the task definition in Ansible to ensure any credentials used are not
+    stored in any log file or console output.
+
+A ``[PSCredential]`` is defined with ``EmbeddedInstance("MSFT_Credential")`` in
+a DSC resource MOF definition.
 
 CimInstance Type
 ++++++++++++++++
@@ -144,13 +208,20 @@ For example, to define a ``[CimInstance]`` value in Ansible:
       Windows: yes
 
 In the above example, the CIM instance is a representation of the class
-``MSFT_xWebAuthenticationInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>``_.
+`MSFT_xWebAuthenticationInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>`_.
 This class accepts four boolean variables, ``Anonymous``, ``Basic``,
 ``Digest``, and ``Windows``. The keys to use in a ``[CimInstance]`` depend on
 the class it represents. Please read through the documentation of the resource
 to determine the keys that can be used and the types of each key value. The
 class definition is typically located in the ``<resource name>.schema.mof``.
 
+HashTable Type
+++++++++++++++
+A ``[HashTable]`` object is also a dictionary but does not have a strict set of
+keys that can/need to be defined. Like a ``[CimInstance]``, define it like a
+normal dictionary value in YAML. A ``[HashTable]]`` is defined with
+``EmbeddedInstance("MSFT_KeyValuePair")`` in a DSC resource MOF definition.
+
 Arrays
 ++++++
 Simple type arrays like ``[string[]]`` or ``[UInt32[]]`` are defined as a list
@@ -192,17 +263,39 @@ like this example:
       Port: 80
       IPAddress: '*'
 
-The above example, is an array with two values of the class ``MSFT_xWebBindingInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>``_.
+The above example, is an array with two values of the class `MSFT_xWebBindingInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>`_.
 When defining a ``[CimInstance[]]``, be sure to read the resource documentation
 to find out what keys to use in the definition.
 
+DateTime
+++++++++
+A ``[DateTime]`` object is a DateTime string representing the date and time in
+the `ISO 8601 <https://www.w3.org/TR/NOTE-datetime>`_ date time format. The
+value for a ``[DateTime]`` field should be quoted in YAML to ensure the string
+is properly serialized to the Windows host. Here is an example of how to define
+a ``[DateTime]`` value in Ansible:
+
+.. code-block:: yaml+jinja
+
+    # As UTC-0 (No timezone)
+    DateTime: '2019-02-22T13:57:31.2311892+00:00'
+
+    # As UTC+4
+    DateTime: '2019-02-22T17:57:31.2311892+04:00'
+
+    # As UTC-4
+    DateTime: '2019-02-22T09:57:31.2311892-04:00'
+
+All the values above are equal to a UTC date time of February 22nd 2019 at
+1:57pm with 31 seconds and 2311892 milliseconds.
+
 Run As Another User
 -------------------
 By default, DSC runs each resource as the SYSTEM account and not the account
 that Ansible use to run the module. This means that resources that are dynamically
 loaded based on a user profile, like the ``HKEY_CURRENT_USER`` registry hive,
-will be loaded under the ``SYSTEM`` profile. The parameter 
-`PsDscRunAsCredential`` is a parameter that can be set for every DSC resource
+will be loaded under the ``SYSTEM`` profile. The parameter
+``PsDscRunAsCredential`` is a parameter that can be set for every DSC resource
 force the DSC engine to run under a different account. As
 ``PsDscRunAsCredential`` has a type of ``PSCredential``, it is defined with the
 ``_username`` and ``_password`` suffix.
@@ -331,7 +424,7 @@ Interact with Azure
       win_psmodule:
         name: xAzure
         state: present
-    
+
     - name: Create virtual machine in Azure
       win_dsc:
         resource_name: xAzureVM