Merge pull request #770 from PowerShell/kapilmb/fix-dsc-rule

Fix UseIdenticalMandatoryParametersForDSC rule logic

Author: Kapil Borle

Engine/Extensions.cs

@@ -30,6 +30,18 @@ public static Range ToRange(this IScriptExtent extent)
                  extent.EndColumnNumber);
         }
 
+        /// <summary>
+        /// Get the parameter Asts from a function definition Ast.
+        ///
+        /// If not parameters are found, return null.
+        /// </summary>
+        public static IEnumerable<ParameterAst> GetParameterAsts(
+            this FunctionDefinitionAst functionDefinitionAst)
+        {
+            ParamBlockAst paramBlockAst;
+            return functionDefinitionAst.GetParameterAsts(out paramBlockAst);
+        }
+
         /// <summary>
         /// Get the parameter Asts from a function definition Ast.
         ///
@@ -41,6 +53,8 @@ public static IEnumerable<ParameterAst> GetParameterAsts(
             this FunctionDefinitionAst functionDefinitionAst,
             out ParamBlockAst paramBlockAst)
         {
+            // todo instead of returning null return an empty enumerator if no parameter is found
+            // this removes the burden from the user for null checking.
             paramBlockAst = null;
             if (functionDefinitionAst.Parameters != null)
             {
@@ -114,6 +128,16 @@ public static NamedAttributeArgumentAst GetSupportsShouldProcessAst(this Attribu
             return null;
         }
 
+
+        /// <summary>
+        /// Return the boolean value of a named attribute argument.
+        /// </summary>
+        public static bool GetValue(this NamedAttributeArgumentAst attrAst)
+        {
+            ExpressionAst argumentAst;
+            return attrAst.GetValue(out argumentAst);
+        }
+
         /// <summary>
         /// Return the boolean value of a named attribute argument.
         /// </summary>

RuleDocumentation/UseIdenticalMandatoryParametersForDSC.md

@@ -4,50 +4,74 @@
 
 ## Description
 
-The `Get-TargetResource`, `Test-TargetResource` and `Set-TargetResource` functions of DSC Resource must have the same mandatory parameters.
+For script based DSC resources, if a property is declared with attributes `Key` of `Required` in a mof file, then is should be present as a mandatory parameter in the corresponding `Get-TargetResource`, `Set-TargetResource` and `Test-TargetResource` functions.
 
 ## How
 
-Correct the mandatory parameters for the functions in DSC resource.
+Make sure all the properties with `Key` and `Required` attributes have equivalent mandatory parameters in the `Get/Set/Test` functions.
 
 ## Example
 
+Consider the following `mof` file.
+
+```powershell
+class WaitForAny : OMI_BaseResource
+{
+    [key, Description("Name of Resource on remote machine")]
+    string Name;
+
+    [required, Description("List of remote machines")]
+    string NodeName[];
+};
+```
+
 ### Wrong
 
 ``` PowerShell
 function Get-TargetResource
 {
-    [OutputType([Hashtable])]
+    [CmdletBinding()]
     param
     (
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [String]
-        $Name
+        $Message
     )
-    ...
 }
 
 function Set-TargetResource
 {
+    [CmdletBinding()]
     param
     (
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Message,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [String]
-        $TargetName
+        $Name
     )
-    ...
 }
 
 function Test-TargetResource
 {
-    [OutputType([System.Boolean])]
+    [CmdletBinding()]
     param
     (
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Message,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [String]
         $Name
     )
-    ...
 }
 ```
 
@@ -56,36 +80,52 @@ function Test-TargetResource
 ``` PowerShell
 function Get-TargetResource
 {
-    [OutputType([Hashtable])]
+    [CmdletBinding()]
     param
     (
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Message,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [String]
         $Name
     )
-    ...
 }
 
 function Set-TargetResource
 {
+    [CmdletBinding()]
     param
     (
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Message,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [String]
         $Name
     )
-    ...
 }
 
 function Test-TargetResource
 {
-    [OutputType([System.Boolean])]
+    [CmdletBinding()]
     param
     (
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Message,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [String]
         $Name
     )
-    ...
 }
 ```

Rules/Strings.resx

@@ -619,7 +619,7 @@
     <value>The Get/Test/Set TargetResource functions of DSC resource must have the same mandatory parameters.</value>
   </data>
   <data name="UseIdenticalMandatoryParametersDSCError" xml:space="preserve">
-    <value>The mandatory parameter '{0}' is not present in '{1}' DSC resource function(s).</value>
+    <value>The '{0}' parameter '{1}' is not present in '{2}' DSC resource function(s).</value>
   </data>
   <data name="UseIdenticalMandatoryParametersDSCName" xml:space="preserve">
     <value>UseIdenticalMandatoryParametersForDSC</value>