PowerShell / PowerShell/PSScriptAnalyzer

Rule request: Prefix parameters with an unambiguous (ASCII) hyphen-minus

Open
#1,932 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue - Discussion
Dominant language
C#
Stars
2.2k
Forks
414
Avg merge
13h 1m
Merged PRs (30d)
2

Description

Hyphen-minus characters are sometimes unintendedly replaced when passed by word processors as Microsoft Office applications as MSWord and Outlook. It is recommended to prefix parameters with an unambiguous hyphen-minus as Unicode dashes might cause parsing errors in earlier versions of PowerShell.
Besides it unnecessary triggers the UseBOMForUnicodeEncodedFile rule with no clear indication of the location.

PowerShell 7
# .\Test.ps1
Write-Host “test” –ForegroundColor ‘Red’ -BackgroundColor ‘Green’
Invoke-ScriptAnalyzer .\Test.ps1

RuleName                            Severity     ScriptName Line  Message
--------                            --------     ---------- ----  -------
PSAvoidUsingWriteHost               Warning      Test.ps1   1     File 'Test.ps1' uses Write-Host. Avoid using
                                                                  Write-Host because it might not work in all hosts,
                                                                  does not work when there is no host, and (prior to
                                                                  PS 5.0) cannot be suppressed, captured, or
                                                                  redirected. Instead, use Write-Output,
                                                                  Write-Verbose, or Write-Information.
PSUseBOMForUnicodeEncodedFile       Warning      Test.ps1         Missing BOM encoding for non-ASCII encoded file
                                                                  'Test.ps1'
Windows PowerShell (5.1)

Windows PowerShell (5.1) still has issue with EM-dashes:

.\test.ps1
At C:\Users\Gebruiker\downloads\Test.ps1:1 char:25
+ ...  “test” –ForegroundColor ‘Red’ -BackgroundColor ‘Green’
+                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The string is missing the terminator: ".
    + CategoryInfo          : ParserError: (:) [], ParseException
    + FullyQualifiedErrorId : TerminatorExpectedAtEndOfString

Invoke-ScriptAnalyzer .\Test.ps1

RuleName                            Severity     ScriptName Line  Message
--------                            --------     ---------- ----  -------
TerminatorExpectedAtEndOfString     ParseError   Test.ps1   1     The string is missing the terminator: ".
PSAvoidUsingWriteHost               Warning      Test.ps1   1     File 'Test.ps1' uses Write-Host. Avoid using
                                                                  Write-Host because it might not work in all hosts,
                                                                  does not work when there is no host, and (prior to
                                                                  PS 5.0) cannot be suppressed, captured, or
                                                                  redirected. Instead, use Write-Output,
                                                                  Write-Verbose, or Write-Information.
PSUseBOMForUnicodeEncodedFile       Warning      Test.ps1         Missing BOM encoding for non-ASCII encoded file
                                                                  'Test.ps1'

Proposed technical implementation details (optional)

See (PowerShell based) prototype UseHyphenMinusForParameter at: https://github.com/iRon7/PSRules

What is the latest version of PSScriptAnalyzer at the point of writing

1.21.0

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the PowerShell examples in the issue and review the linked UseHyphenMinusForParameter prototype in PSRules. Compare the proposed behavior with existing PSScriptAnalyzer rules and the UseBOMForUnicodeEncodedFile output. Done should mean that Unicode dash characters used to prefix parameters are detected with a clear location and diagnostic, including the shown PowerShell cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.