diff --git a/ScriptRuleDocumentation.md b/ScriptRuleDocumentation.md index d3338a0e0..f7bdd00db 100644 --- a/ScriptRuleDocumentation.md +++ b/ScriptRuleDocumentation.md @@ -1,12 +1,15 @@ -##Documentation for Customized Rules in PowerShell Scripts -PSScriptAnalyzer uses MEF(Managed Extensibility Framework) to import all rules defined in the assembly. It can also consume rules written in PowerShell scripts. +## Documentation for Customized Rules in PowerShell Scripts + +PSScriptAnalyzer uses MEF(Managed Extensibility Framework) to import all rules defined in the assembly. It can also consume rules written in PowerShell scripts. When calling Invoke-ScriptAnalyzer, users can specify custom rules using the parameter `CustomizedRulePath`. The purpose of this documentation is to server as a basic guide on creating your own customized rules. -###Basics +### Basics + - Functions should have comment-based help. Make sure .DESCRIPTION field is there, as it will be consumed as rule description for the customized rule. + ``` PowerShell <# .SYNOPSIS @@ -21,11 +24,13 @@ The purpose of this documentation is to server as a basic guide on creating your ``` - Output type should be DiagnosticRecord: + ``` PowerShell [OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]])] ``` - Make sure each function takes either a Token or an Ast as a parameter + ``` PowerShell Param ( @@ -37,6 +42,7 @@ Param ``` - DiagnosticRecord should have four properties: Message, Extent, RuleName and Severity + ``` PowerShell $result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]]@{ "Message" = "This is a sample rule" @@ -47,18 +53,20 @@ $result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[ ``` - Make sure you export the function(s) at the end of the script using Export-ModuleMember + ``` PowerShell Export-ModuleMember -Function (FunctionName) ``` -###Example +### Example + ``` PowerShell <# .SYNOPSIS Uses #Requires -RunAsAdministrator instead of your own methods. .DESCRIPTION - The #Requires statement prevents a script from running unless the Windows PowerShell version, modules, snap-ins, and module and snap-in version prerequisites are met. - From Windows PowerShell 4.0, the #Requires statement let script developers require that sessions be run with elevated user rights (run as Administrator). + The #Requires statement prevents a script from running unless the Windows PowerShell version, modules, snap-ins, and module and snap-in version prerequisites are met. + From Windows PowerShell 4.0, the #Requires statement let script developers require that sessions be run with elevated user rights (run as Administrator). Script developers does not need to write their own methods any more. To fix a violation of this rule, please consider to use #Requires -RunAsAdministrator instead of your own methods. .EXAMPLE @@ -123,12 +131,12 @@ function Measure-RequiresRunAsAdministrator } #endregion #region Finds ASTs that match the predicates. - + [System.Management.Automation.Language.Ast[]]$methodAst = $ScriptBlockAst.FindAll($predicate1, $true) [System.Management.Automation.Language.Ast[]]$assignmentAst = $ScriptBlockAst.FindAll($predicate2, $true) if ($null -ne $ScriptBlockAst.ScriptRequirements) { - if ((!$ScriptBlockAst.ScriptRequirements.IsElevationRequired) -and + if ((!$ScriptBlockAst.ScriptRequirements.IsElevationRequired) -and ($methodAst.Count -ne 0) -and ($assignmentAst.Count -ne 0)) { $result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]@{ @@ -137,7 +145,7 @@ function Measure-RequiresRunAsAdministrator 'RuleName' = $PSCmdlet.MyInvocation.InvocationName 'Severity' = 'Information' } - $results += $result + $results += $result } } else @@ -150,11 +158,11 @@ function Measure-RequiresRunAsAdministrator 'RuleName' = $PSCmdlet.MyInvocation.InvocationName 'Severity' = 'Information' } - $results += $result - } + $results += $result + } } return $results - #endregion + #endregion } catch {