Skip to content

Commit 9d20c22

Browse files
yutingcyutingc
committed
Modified best practice.
1 parent 2d91cdb commit 9d20c22

File tree

1 file changed

+134
-0
lines changed

1 file changed

+134
-0
lines changed

‎PowerShellBestPractices.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
#PowerShell Best Practices
2+
3+
The following guidelines come from a combined effort from both the PowerShell team and the community. We will use this guideline to define rules for PSScriptAnalyzer. Please feel free to propose additional guidelines and rules for PSScriptAnalyzer.
4+
**Note: The hyperlink next to each guidelines will redirect to documentation page for the rule that is already implemented.
5+
6+
##Cmdlet Design Rules
7+
###Severity: Error
8+
###Severity: Warning
9+
- Use Only Approved Verbs [UseApprovedVerbs](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseApprovedVerbs.md)
10+
- Cmdlets Names: Characters that cannot be Used [AvoidReservedCharInCmdlet](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidReservedCharInCmdlet.md)
11+
- Parameter Names that cannot be Used [AvoidReservedParams](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidReservedParams.md)
12+
- Support Confirmation Requests [UseShouldProcessCorrectly](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseShouldProcessCorrectly.md) and [UseShouldProcessForStateChangingFunctions](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseShouldProcessForStateChangingFunctions.md)
13+
- Nouns should be singular [UseSingularNouns](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseSingularNouns.md)
14+
- Module Manifest Fields [MissingModuleManifestField](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/MissingModuleManifestField.md)
15+
- Version
16+
- Author
17+
- Description
18+
- LicenseUri (for PowerShell Gallery)
19+
- Must call ShouldProcess when ShouldProcess attribute is present and vice versa.[UseShouldProcessCorrectly](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseShouldProcessCorrectly.md)
20+
- Switch parameters should not default to true  [AvoidDefaultTrueValueSwtichParameter](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidDefaultTrueValueSwitchParameter.md)
21+
22+
###Severity: Information
23+
24+
###Severity: TBD
25+
- Support Force Parameter for Interactive Session
26+
- If your cmdlet is used interactively, always provide a Force parameter to override the interactive actions, such as prompts or reading lines of input). This is important because it allows your cmdlet to be used in non-interactive scripts and hosts. The following methods can be implemented by an interactive host.
27+
- Document Output Objects
28+
- Module must be loadable
29+
- No syntax errors
30+
- Unresolved dependencies are an error
31+
- Derive from the Cmdlet or PSCmdlet Classes
32+
- Specify the Cmdlet Attribute
33+
- Override an Input Processing Method
34+
- Specify the OutputType Attribute
35+
- Write Single Records to the Pipeline
36+
- Make Cmdlets Case-Insensitive and Case-Preserving
37+
38+
39+
##Script Functions
40+
###Severity: Error
41+
42+
###Severity: Warning
43+
- Avoid using alias [AvoidAlias](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidAlias.md)
44+
- Avoid using deprecated WMI cmdlets [AvoidUsingWMICmdlet](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingWMICmdlet.md)
45+
- Empty catch block should not be used [AvoidEmptyCatchBlock](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidEmptyCatchBlock.md)
46+
- Invoke existing cmdlet with correct parameters [UseCmdletCorrectly](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCmdletCorrectly.md)
47+
- Cmdlets should have ShouldProcess/ShouldContinue and Force param if certain system-modding verbs are present (Update, Set, Remove, New)[UseShouldProcessForStateChangingFunctions](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseShouldProcessForStateChangingFunctions.md)
48+
- Positional parameters should be avoided [AvoidUsingPositionalParameters](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingPositionalParameters.md)
49+
- Non-global variables must be initialized. Those that are supposed to be global and not initialized must have “global:” (includes for loop initializations)[AvoidUninitializedVariable](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUninitializedVariable.md)
50+
- Global variables should be avoided. [AvoidGlobalVars](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidGlobalVars.md)
51+
- Declared variables must be used in more than just their assignment. [UseDeclaredVarsMoreThanAssignments](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseDeclaredVarsMoreThanAssignments.md)
52+
- No trap statments should be used [AvoidTrapStatement](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidTrapStatement.md)
53+
- No Invoke-Expression [AvoidUsingInvokeExpression](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingInvokeExpression.md)
54+
55+
###Severity: Information
56+
57+
###Severity: TBD
58+
- Clear-Host should not be used
59+
- File paths should not be used (UNC)
60+
- Error Handling
61+
- Use -ErrorAction Stop when calling cmdlets
62+
- Use $ErrorActionPreference = 'Stop'/' Continue' when calling non-cmdlets
63+
- Avoid using flags to handle errors
64+
- Avoid using $?
65+
- Avoid testing for a null variable as an error condition
66+
- Copy $Error[0] to your own variable
67+
- Avoid using pipelines in scripts
68+
- If a return type is declared, the cmdlet must return that type. If a type is returned, a return type must be declared.
69+
70+
71+
72+
##Scripting Style
73+
###Severity: Error
74+
75+
###Severity: Warning
76+
- Don't use write-host unless writing to the host is all you want to do [AvoidUsingWriteHost](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingWriteHost.md)
77+
78+
###Severity: Information
79+
- Write comment-based help [ProvideCommentHelp](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/ProvideCommentHelp.md)
80+
- Use write-verbose to give information to someone running your script [ProvideVerboseMessage](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/ProvideVerboseMessage.md)
81+
###Severity: TBD
82+
- Provide usage Examples
83+
- Use the Notes section for detail on how the tool work
84+
- Should have help on every exported command (including parameter documentation
85+
- Document the version of PowerShell that script was written for
86+
- Indent your code
87+
- Avoid backticks
88+
89+
90+
##Script Security
91+
###Severity: Error
92+
- Password should be secure string [AvoidUsingPlainTextForPassword](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingPlainTextForPassword.md)- Should never have both -Username and -Password parameters (should take credentials)[UsePSCredentialType](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UsePSCredentialType.md)
93+
- -ComputerName hardcoded should not be used (information disclosure)[AvoidUsingComputerNameHardcoded](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingComputerNameHardcoded.md)
94+
- - ConvertTo-SecureString with plaintext should not be used (information disclosure)
95+
-
96+
###Severity: Warning
97+
- Password = 'string' should not be used. (information disclosure) [AvoidUsingUsernameAndPasswordParams](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingUsernameAndPasswordParams.md)
98+
- Internal URLs should not be used (information disclosure)[AvoidUsingFilePath](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingFilePath.md)
99+
100+
###Severity: Information
101+
102+
###Severity: TBD
103+
- APIKey and Credentials variables that are initialized (information disclosure)
104+
105+
106+
##DSC Related Rules
107+
###Severity: Error
108+
- Use standard DSC methods [UseStandardDSCFunctionsInResource](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseStandardDSC FunctionsInResource.md)
109+
- Use identical mandatory parameters for all DSC methods [UseIdenticalMandatoryParametersDSC](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseIdenticalMandatoryParametersDSC.md)
110+
- Use identical parameters for Set and Test DSC methods [UseIdenticalParametersDSC](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseIdenticalParametersDSC.md)
111+
112+
###Severity: Warning
113+
114+
###Severity: Information
115+
- All of the following three rule are grouped by: [ReturnCorrectTypeDSCFunctions](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/ReturnCorrectTypeDSCFunctions.md)
116+
- Avoid return any object from a Set-TargetResource function
117+
- Returning a Boolean object from a Test-TargetResource function
118+
- Returning an object from a Get-TargetResource function
119+
- DSC resources should have DSC tests [DSCTestsPresent](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/DscTestsPresent.md)
120+
- DSC resources should have DSC examples [DSCExamplesPresent](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/DscExamplesPresent.md)
121+
122+
###Severity: TBD
123+
- For PowerShell V4: Resource module contains .psd1 file and schema.mof for every resource
124+
- MOF has description for each element [IssueOpened](https://github.com/PowerShell/PSScriptAnalyzer/issues/131)
125+
- Resource module must alwasy contain .psd1 file and schema.mof (for non-class resource).
126+
- Use ShouldProcess for a Set DSC method
127+
- Resource module contains Resources folder which contains the resources [IssueOpened](https://github.com/PowerShell/PSScriptAnalyzer/issues/130)
128+
129+
130+
131+
###Reference:
132+
Cmdlet Development Guidelines from MSDN site (Cmdlet Development Guidelines)
133+
134+
The Community Book of PowerShell Practices (Compiled by Don Jones and Matt Penny and the Windows PowerShell Community)

0 commit comments

Comments
 (0)