Skip to content

Update example based on UUF comments #425

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.

Sign up for GitHub

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

Merged
sdwheeler merged 2 commits into from
Jun 23, 2026
Merged

Update example based on UUF comments #425

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2aca474
Update example based on UUF comments
sdwheeler Jun 23, 2026
be1c85e
Simplify example
sdwheeler Jun 23, 2026
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
153 changes: 53 additions & 100 deletions reference/docs-conceptual/PSScriptAnalyzer/create-custom-rule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,15 @@ Include the `.DESCRIPTION` field. This field becomes the description for the cus
#>
```

### Output type should be **DiagnosticRecord**
### Output type should be an array of **DiagnosticRecord** objects

```powershell
[OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
```

### Each function must have a Token array or an Ast parameter

The name of the **Ast** parameter name must end with **Ast**.
The name of the **Ast** parameter name must end with `Ast`.

```powershell
Param
Expand All @@ -53,7 +53,7 @@ Param
)
```

The name of the **Token** parameter name must end with **Token**.
The name of the **Token** parameter name must end with `Token`.

```powershell
Param
Expand All @@ -76,24 +76,24 @@ The **DiagnosticRecord** should have at least four properties:

```powershell
$result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]]@{
"Message" = "This is a sample rule"
"Extent" = $ast.Extent
"RuleName" = $PSCmdlet.MyInvocation.InvocationName
"Severity" = "Warning"
Message = 'This is a sample rule'
Extent = $ast.Extent
RuleName = $PSCmdlet.MyInvocation.InvocationName
Severity = 'Warning'
}
```

Since version 1.17.0, you can include a **SuggestedCorrections** property of type
**IEnumerable\<CorrectionExtent\>**. Make sure to specify the correct type. For example:

```powershell
[int]$startLineNumber = $ast.Extent.StartLineNumber
[int]$endLineNumber = $ast.Extent.EndLineNumber
[int]$startColumnNumber = $ast.Extent.StartColumnNumber
[int]$endColumnNumber = $ast.Extent.EndColumnNumber
[string]$correction = 'Correct text that replaces Extent text'
[string]$file = $MyInvocation.MyCommand.Definition
[string]$optionalDescription = 'Useful but optional description text'
$startLineNumber = $ast.Extent.StartLineNumber
$endLineNumber = $ast.Extent.EndLineNumber
$startColumnNumber = $ast.Extent.StartColumnNumber
$endColumnNumber = $ast.Extent.EndColumnNumber
$correction = 'Correct text that replaces Extent text'
$file = $MyInvocation.MyCommand.Definition
$optionalDescription = 'Useful but optional description text'
$objParams = @{
TypeName = 'Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.CorrectionExtent'
ArgumentList = $startLineNumber, $endLineNumber, $startColumnNumber,
Expand All @@ -104,13 +104,12 @@ $suggestedCorrections = New-Object System.Collections.ObjectModel.Collection[$($
$suggestedCorrections.add($correctionExtent) | Out-Null

[Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
"Message" = "This is a rule with a suggested correction"
"Extent" = $ast.Extent
"RuleName" = $PSCmdlet.MyInvocation.InvocationName
"Severity" = "Warning"
"Severity" = "Warning"
"RuleSuppressionID" = "MyRuleSuppressionID"
"SuggestedCorrections" = $suggestedCorrections
Message = 'This is a rule with a suggested correction'
Extent = $ast.Extent
RuleName = $PSCmdlet.MyInvocation.InvocationName
Severity = 'Warning'
RuleSuppressionID = 'MyRuleSuppressionID'
SuggestedCorrections = $suggestedCorrections
}
```

Expand All @@ -132,7 +131,7 @@ Export-ModuleMember -Function (FunctionName)
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
sessions be run with elevated user rights (run as Administrator). Script developers do
not need to write their own methods any more. To fix a violation of this rule, please
consider using #Requires -RunAsAdministrator instead of your own methods.
.EXAMPLE
Expand All @@ -144,95 +143,49 @@ Export-ModuleMember -Function (FunctionName)
.NOTES
None
#>
function Measure-RequiresRunAsAdministrator
{
function Measure-RequiresRunAsAdministrator {
[CmdletBinding()]
[OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
Param
param
(
[Parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[System.Management.Automation.Language.ScriptBlockAst]
$ScriptBlockAst
)

Process
{
$results = @()
try
{
#region Define predicates to find ASTs.
# Finds specific method, IsInRole.
[ScriptBlock]$predicate1 = {
param ([System.Management.Automation.Language.Ast]$Ast)
[bool]$returnValue = $false
if ($Ast -is [System.Management.Automation.Language.MemberExpressionAst])
{
[System.Management.Automation.Language.MemberExpressionAst]$meAst = $Ast
if ($meAst.Member -is [System.Management.Automation.Language.StringConstantExpressionAst])
{
[System.Management.Automation.Language.StringConstantExpressionAst]$sceAst = $meAst.Member
if ($sceAst.Value -eq 'isinrole')
{
$returnValue = $true
}
}
}
return $returnValue
}
begin {
$MeasureRequiresAdmin = @(
'The #Requires statement prevents a script from running unless the PowerShell version,'
'modules, snap-ins, and module and snap-in version prerequisites are met. Since'
'Windows PowerShell 4.0, the #Requires statement lets script developers require that'
'sessions be run with elevated user rights (run as Administrator). Script developers'
'don''t need to write their own methods to test for elevated rights. To fix a violation'
'of this rule, use #Requires -RunAsAdministrator instead of your own methods.'
) -join ' '

# Finds specific method, IsInRole.
[ScriptBlock]$predicate = {
param($Ast)
return $Ast.Member.Value -eq 'IsInRole'
}
}

# Finds specific value, [system.security.principal.windowsbuiltinrole]::administrator.
[ScriptBlock]$predicate2 = {
param ([System.Management.Automation.Language.Ast]$Ast)
[bool]$returnValue = $false
if ($Ast -is [System.Management.Automation.Language.AssignmentStatementAst])
{
[System.Management.Automation.Language.AssignmentStatementAst]$asAst = $Ast
if ($asAst.Right.ToString() -eq '[system.security.principal.windowsbuiltinrole]::administrator')
{
$returnValue = $true
}
}
return $returnValue
}
#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
($methodAst.Count -ne 0) -and ($assignmentAst.Count -ne 0))
{
$result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
'Message' = $Messages.MeasureRequiresRunAsAdministrator
'Extent' = $assignmentAst.Extent
'RuleName' = $PSCmdlet.MyInvocation.InvocationName
'Severity' = 'Information'
}
$results += $result
}
}
else
{
if (($methodAst.Count -ne 0) -and ($assignmentAst.Count -ne 0))
{
$result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
'Message' = $Messages.MeasureRequiresRunAsAdministrator
'Extent' = $assignmentAst.Extent
'RuleName' = $PSCmdlet.MyInvocation.InvocationName
'Severity' = 'Information'
}
$results += $result
}
}
return $results
#endregion
process {
# Exit early if the script block has a #Requires -RunAsAdministrator statement.
if ($ScriptBlockAst.ScriptRequirements.IsElevationRequired) {
return
}
catch
{
$PSCmdlet.ThrowTerminatingError($PSItem)

# Test for calls to IsInRole() method
[System.Management.Automation.Language.Ast]$methodAst = $ScriptBlockAst.Find($predicate, $true)
if ($methodAst) {
[Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
Message = $MeasureRequiresAdmin
Extent = $methodAst.Extent
RuleName = $PSCmdlet.MyInvocation.InvocationName
Severity = 'Information'
}
}
}
}
Expand Down