Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix Markdown in ScriptRuleDocumentation.md so it renders correctly on GitHub web site #898

Merged
merged 1 commit into from
Feb 20, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 20 additions & 12 deletions ScriptRuleDocumentation.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
(
Expand All @@ -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"
Expand All @@ -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
Expand Down Expand Up @@ -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]@{
Expand All @@ -137,7 +145,7 @@ function Measure-RequiresRunAsAdministrator
'RuleName' = $PSCmdlet.MyInvocation.InvocationName
'Severity' = 'Information'
}
$results += $result
$results += $result
}
}
else
Expand All @@ -150,11 +158,11 @@ function Measure-RequiresRunAsAdministrator
'RuleName' = $PSCmdlet.MyInvocation.InvocationName
'Severity' = 'Information'
}
$results += $result
}
$results += $result
}
}
return $results
#endregion
#endregion
}
catch
{
Expand Down