FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Backport MSDocs changes (#2085) · PowerShell/PSScriptAnalyzer@28081e5 · GitHub

/ PSScriptAnalyzer Public

Commit 28081e5

Browse files
bergmeister
and
sdwheeler
authored
Backport MSDocs changes (#2085)
* Backport docs updates from docs repo * Backport msdocs changes for Cmdlets. Where references to files in MSDocs were present (e.g. in UseShouldProcessForStateChangingFunctions), replaced with the live URLs. Did not port back TODO block of AvoidAssignmentToAutomaticVariable.md from https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/pull/241/files#diff-1db3dc2f98da1fa58e24bac28ea9f14f507c78d8299349aa0196f01f9479b6f5 Backported PRs: - https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/pull/281/files - MicrosoftDocs/PowerShell-Docs-Modules@ff80de6 - https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/pull/275/files - MicrosoftDocs/PowerShell-Docs-Modules#278 - https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/pull/235/files - https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/pull/276/files - MicrosoftDocs/PowerShell-Docs-Modules#273 - MicrosoftDocs/PowerShell-Docs-Modules#285 - MicrosoftDocs/PowerShell-Docs-Modules@6ca872b#diff-b3e50d455fe1b464a6fec38ac616cbde4a412766a05a606c1ae55be90ccb63a3 - MicrosoftDocs/PowerShell-Docs-Modules#277 * Update docs/Cmdlets/Invoke-ScriptAnalyzer.md Co-authored-by: Christoph Bergmeister <c.bergmeister@gmail.com> * Apply suggestions from code review Co-authored-by: Christoph Bergmeister <c.bergmeister@gmail.com> --------- Co-authored-by: Sean Wheeler <sean.wheeler@microsoft.com>
1 parent ae712f7 commit 28081e5

22 files changed

Lines changed: 225 additions & 122 deletions

‎docs/Cmdlets/Get-ScriptAnalyzerRule.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
33
Module Name: PSScriptAnalyzer
4-
ms.date: 10/07/2021
4+
ms.date: 12/12/2024
55
online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/get-scriptanalyzerrule?view=ps-modules&wt.mc_id=ps-gethelp
66
schema: 2.0.0
77
---
@@ -92,7 +92,7 @@ one value, but wildcards are supported. To get rules in subdirectories of the pa
9292
**RecurseCustomRulePath** parameter.
9393

9494
You can create custom rules using a .NET assembly or a PowerShell module, such as the
95-
[Community Analyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1)
95+
[Community Analyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/tree/main/Tests/Engine/CommunityAnalyzerRules)
9696
in the GitHub repository.
9797

9898
```yaml

‎docs/Cmdlets/Invoke-ScriptAnalyzer.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ value of the **Profile** parameter is the path to the Script Analyzer profile.
192192
ExcludeRules = '*WriteHost'
193193
}
194194
195-
Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Profile .\ScriptAnalyzerProfile.txt
195+
Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt
196196
```
197197

198198
If you include a conflicting parameter in the `Invoke-ScriptAnalyzer` command, such as

‎docs/Cmdlets/PSScriptAnalyzer.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,13 @@ checks the quality of PowerShell code by running a set of rules.
2121
## PSScriptAnalyzer Cmdlets
2222

2323
### [Get-ScriptAnalyzerRule](Get-ScriptAnalyzerRule.md)
24+
2425
Gets the script analyzer rules on the local computer.
2526

2627
### [Invoke-Formatter](Invoke-Formatter.md)
28+
2729
Formats a script text based on the input settings or default settings.
2830

2931
### [Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md)
32+
3033
Evaluates a script or module based on selected best practice rules

‎docs/Rules/AvoidAssignmentToAutomaticVariable.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,11 @@ only be assigned in certain special cases to achieve a certain effect as a speci
1616

1717
To understand more about automatic variables, see `Get-Help about_Automatic_Variables`.
1818

19+
<!-- TODO
20+
Ability to suppress was added in https://github.com/PowerShell/PSScriptAnalyzer/pull/1896
21+
Need documentation for how to configure suppression of this rule.
22+
-->
23+
1924
## How
2025

2126
Use variable names in functions or their parameters that do not conflict with automatic variables.

‎docs/Rules/AvoidDefaultValueSwitchParameter.md‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Switch Parameters Should Not Default To True
3-
ms.date: 06/28/2023
3+
ms.date: 12/05/2024
44
ms.topic: reference
55
title: AvoidDefaultValueSwitchParameter
66
---
@@ -10,11 +10,19 @@ title: AvoidDefaultValueSwitchParameter
1010

1111
## Description
1212

13-
Switch parameters for commands should default to false.
13+
If your parameter takes only `true` and `false`, define the parameter as type `[Switch]`. PowerShell
14+
treats a switch parameter as `true` when it's used with a command. If the parameter isn't included
15+
with the command, PowerShell considers the parameter to be false. Don't define `[Boolean]`
16+
parameters.
17+
18+
You shouldn't define a switch parameter with a default value of `$true` because this isn't the
19+
expected behavior of a switch parameter.
1420

1521
## How
1622

17-
Change the default value of the switch parameter to be false.
23+
Change the default value of the switch parameter to be `$false` or don't provide a default value.
24+
Write the logic of the script to assume that the switch parameter default value is `$false` or not
25+
provided.
1826

1927
## Example
2028

@@ -48,8 +56,22 @@ function Test-Script
4856
$Param1,
4957
5058
[switch]
51-
$Switch=$False
59+
$Switch
5260
)
61+
62+
begin {
63+
# Ensure that the $Switch is set to false if not provided
64+
if (-not $PSBoundParameters.ContainsKey('Switch')) {
65+
$Switch = $false
66+
}
67+
}
5368
...
5469
}
5570
```
71+
72+
## More information
73+
74+
- [Strongly Encouraged Development Guidelines][01]
75+
76+
<!-- link references -->
77+
[01]: https://learn.microsoft.com/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines#parameters-that-take-true-and-false

‎docs/Rules/AvoidGlobalFunctions.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@ title: AvoidGlobalFunctions
1313
Globally scoped functions override existing functions within the sessions with matching names. This
1414
name collision can cause difficult to debug issues for consumers of modules.
1515

16-
1716
To understand more about scoping, see `Get-Help about_Scopes`.
1817

1918
## How

‎docs/Rules/AvoidOverwritingBuiltInCmdlets.md‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Avoid overwriting built in cmdlets
3-
ms.date: 06/28/2023
3+
ms.date: 12/12/2024
44
ms.topic: reference
55
title: AvoidOverwritingBuiltInCmdlets
66
---
@@ -14,7 +14,7 @@ This rule flags cmdlets that are available in a given edition/version of PowerSh
1414
operating system which are overwritten by a function declaration. It works by comparing function
1515
declarations against a set of allowlists that ship with PSScriptAnalyzer. These allowlist files are
1616
used by other PSScriptAnalyzer rules. More information can be found in the documentation for the
17-
[UseCompatibleCmdlets](./UseCompatibleCmdlets.md) rule.
17+
[UseCompatibleCmdlets][01] rule.
1818

1919
## Configuration
2020

@@ -37,14 +37,17 @@ following your settings file.
3737

3838
The parameter `PowerShellVersion` is a list of allowlists that ship with PSScriptAnalyzer.
3939

40-
**Note**: The default value for `PowerShellVersion` is `core-6.1.0-windows` if PowerShell 6 or
41-
later is installed, and `desktop-5.1.14393.206-windows` if it is not.
40+
> [!NOTE]
41+
> The default value for `PowerShellVersion` is `core-6.1.0-windows` if PowerShell 6 or
42+
> later is installed, and `desktop-5.1.14393.206-windows` if it's not.
4243
4344
Usually, patched versions of PowerShell have the same cmdlet data, therefore only settings of major
4445
and minor versions of PowerShell are supplied. One can also create a custom settings file as well
45-
with the
46-
[New-CommandDataFile.ps1](https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Utils/New-CommandDataFile.ps1)
47-
script and use it by placing the created `JSON` into the `Settings` folder of the `PSScriptAnalyzer`
48-
module installation folder, then the `PowerShellVersion` parameter is just its file name (that can
49-
also be changed if desired). Note that the `core-6.0.2-*` files were removed in PSScriptAnalyzer
50-
1.18 since PowerShell 6.0 reached end of life.
46+
with the [New-CommandDataFile.ps1][02] script and use it by placing the created `JSON` into the
47+
`Settings` folder of the `PSScriptAnalyzer` module installation folder, then the `PowerShellVersion`
48+
parameter is just its filename (that can also be changed if desired). Note that the `core-6.0.2-*`
49+
files were removed in PSScriptAnalyzer 1.18 since PowerShell 6.0 reached end of life.
50+
51+
<!-- link references -->
52+
[01]: ./UseCompatibleCmdlets.md
53+
[02]: https://github.com/PowerShell/PSScriptAnalyzer/blob/main/Utils/New-CommandDataFile.ps1

‎docs/Rules/AvoidUsingCmdletAliases.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ There are also implicit aliases. When PowerShell cannot find the cmdlet name, it
2020
Every PowerShell author learns the actual command names, but different authors learn and use
2121
different aliases. Aliases can make code difficult to read, understand and impact availability.
2222

23-
Using the full command name makes it eaiser to maintain your scripts in the the future.
23+
Using the full command name makes it easier to maintain your scripts in the the future.
2424

2525
Using the full command names also allows for syntax highlighting in sites and applications like
2626
GitHub and Visual Studio Code.

‎docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Avoid Using SecureString With Plain Text
3-
ms.date: 06/28/2023
3+
ms.date: 01/28/2025
44
ms.topic: reference
55
title: AvoidUsingConvertToSecureStringWithPlainText
66
---
@@ -37,6 +37,4 @@ $EncryptedInput = ConvertTo-SecureString -String $UserInput -AsPlainText -Force
3737

3838
```powershell
3939
$SecureUserInput = Read-Host 'Please enter your secure code' -AsSecureString
40-
$EncryptedInput = ConvertFrom-SecureString -String $SecureUserInput
41-
$SecureString = ConvertTo-SecureString -String $EncryptedInput
4240
```

‎docs/Rules/AvoidUsingWriteHost.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Avoid Using Write-Host
3-
ms.date: 06/28/2023
3+
ms.date: 12/05/2024
44
ms.topic: reference
55
title: AvoidUsingWriteHost
66
---
@@ -10,10 +10,15 @@ title: AvoidUsingWriteHost
1010

1111
## Description
1212

13-
The use of `Write-Host` is greatly discouraged unless in the use of commands with the `Show` verb.
14-
The `Show` verb explicitly means 'show on the screen, with no other possibilities'.
13+
The primary purpose of the `Write-Host` cmdlet is to produce display-only output in the host. For
14+
example: printing colored text or prompting the user for input when combined with `Read-Host`.
15+
`Write-Host` uses the `ToString()` method to write the output. The particular result depends on the
16+
program that's hosting PowerShell. The output from `Write-Host` isn't sent to the pipeline. To
17+
output data to the pipeline, use `Write-Output` or implicit output.
1518

16-
Commands with the `Show` verb do not have this check applied.
19+
The use of `Write-Host` in a function is discouraged unless the function uses the `Show` verb. The
20+
`Show` verb explicitly means _display information to the user_. This rule doesn't apply to functions
21+
with the `Show` verb.
1722

1823
## How
1924

@@ -27,22 +32,22 @@ logging or returning one or more objects.
2732
```powershell
2833
function Get-MeaningOfLife
2934
{
30-
...
3135
Write-Host 'Computing the answer to the ultimate question of life, the universe and everything'
32-
...
3336
Write-Host 42
3437
}
3538
```
3639

3740
### Correct
3841

42+
Use `Write-Verbose` for informational messages. The user can decide whether to see the message by
43+
providing the **Verbose** parameter.
44+
3945
```powershell
4046
function Get-MeaningOfLife
4147
{
42-
[CmdletBinding()]Param() # to make it possible to set the VerbosePreference when calling the function
43-
...
48+
[CmdletBinding()]Param() # makes it possible to support Verbose output
49+
4450
Write-Verbose 'Computing the answer to the ultimate question of life, the universe and everything'
45-
...
4651
Write-Output 42
4752
}
4853
@@ -51,3 +56,7 @@ function Show-Something
5156
Write-Host 'show something on screen'
5257
}
5358
```
59+
60+
## More information
61+
62+
[Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host)

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL