PSScriptAnalyzer 规则和建议

2024-12-03

以下准则来自 PowerShell 团队和社区的共同努力。这些准则按类型进行组织。在每个类型中，都有一个规则列表。规则按 PSScriptAnalyzer 规则实现中定义的 严重性 分组。标记为“TBD”的严重性级别表示“待确定”。这些建议当前未定义规则。

Cmdlet 设计规则

严重性：错误

未定义任何规则。

严重性：警告

UseApprovedVerbs 仅使用批准的谓词
AvoidReservedCharInCmdlet，具有不可用字符的 Cmdlet 名称
无法 AvoidReservedParams 使用的参数名称
UseShouldProcessForStateChangingFunctions 和 UseSupportsShouldProcess 支持确认请求
当存在 ShouldProcess 属性时，必须调用 ShouldProcess，反之亦然，UseShouldProcess
名词应 UseSingularNouns
MissingModuleManifestField 缺少模块清单
字段
- 版本
- Author
- 说明
- LicenseUri（适用于 PowerShell 库）
开关参数不应默认为 true AvoidDefaultValueSwitchParameter

严重性：信息

未定义任何规则。

严重性：TBD

支持 Force 参数进行交互式会话。如果 cmdlet 以交互方式使用，请始终提供 Force 参数来替代交互式操作，例如提示或读取输入行。这很重要，因为它允许在非交互式脚本和主机中使用 cmdlet。交互式主机可以实现以下方法。
文档输出对象
模块必须可加载
没有语法错误
未解析的依赖项是错误
派生自 Cmdlet 或 PSCmdlet 类
指定 Cmdlet 属性
重写输入处理方法
指定 OutputType 属性
将单个记录写入管道
使 cmdlet 不区分大小写和保留大小写

脚本函数

严重性：错误

未定义任何规则。

严重性：警告

避免使用别名 AvoidUsingCmdletAliases
避免使用弃用的 WMI cmdlet AvoidUsingWMICmdlet
避免使用空 catch 块 AvoidUsingEmptyCatchBlock
UseCmdlet 正确调用具有正确参数的现有 cmdlet
如果使用某些系统修改谓词（Update、Set、Remove、New）：UseShouldProcessForStateChangingFunctions，Cmdlet 应具有 ShouldProcess/ShouldContinue 和 Force 参数
避免使用位置参数 AvoidUsingPositionalParameters
避免使用全局变量 AvoidGlobalVars
声明变量应在分配后使用 UseDeclaredVarsMoreThanAssignments
避免使用 Invoke-ExpressionAvoidUsingInvokeExpression

严重性：信息

未定义任何规则。

严重性：TBD

避免使用 Clear-Host
避免使用 UNC 文件路径
错误处理
- 调用 cmdlet 时使用 -ErrorAction Stop
- 调用非 cmdlet 时使用 $ErrorActionPreference = 'Stop'/'Continue'
- 避免使用标志来处理错误
- 避免使用 $?
- 避免将 null 变量作为错误条件进行测试
- 将 $Error[0] 复制到自己的变量
避免在脚本中使用管道
如果声明了返回类型，则 cmdlet 必须返回该类型。如果返回类型，则必须声明返回类型。

脚本样式

严重性：错误

未定义任何规则。

严重性：警告

避免使用 Write-Host，除非写入主机是你想要执行 AvoidUsingWriteHost

严重性：信息

ProvideCommentHelp 编写基于注释的帮助

严重性：TBD

提供用法示例
有关工具工作原理的详细信息，请使用“说明”部分
每个导出的命令都应有帮助（包括参数文档）
记录为脚本编写的 PowerShell 版本
缩进代码
避免反杆

脚本安全性

严重性：错误

避免使用纯文本密码 AvoidUsingPlainTextForPassword
请避免 -Username 和 -Password 参数（请改用 PSCredential）：UsePSCredentialType
避免硬编码 -ComputerName 参数参数（信息泄漏）：AvoidUsingComputerNameHardcoded
避免在纯文本中使用 ConvertTo-SecureString（信息泄露）：AvoidUsingConvertToSecureStringWithPlainText

严重性：警告

避免使用 $Password = 'string'（信息泄露）。 AvoidUsingUsernameAndPasswordParams

严重性：信息

未定义任何规则。

严重性：TBD

避免初始化 APIKey 和凭据变量（信息泄露）

严重性：错误

使用标准 DSC 方法 StandardDSCFunctionsInResource
对所有 DSC 方法使用相同的必需参数，UseIdenticalMandatoryParametersForDSC
对 Set 和 Test DSC 方法使用相同的参数，UseIdenticalParametersForDSC

严重性：警告

未定义任何规则。

严重性：信息

ReturnCorrectTypesForDSCFunctions 规则介绍了以下三项建议
- 避免从 Set-TargetResource 或 Set（基于类）函数返回任何对象
- 从 Test-TargetResource 或 Test（基于类）函数返回布尔值
- 从 Get-TargetResource 或 Get（基于类）函数返回对象
DSC 资源应具有 DSC 测试 DSCTestsPresent
DSC 资源应具有 DSC 示例 DSCExamplesPresent

严重性：TBD

对于 Windows PowerShell v4，资源模块应具有 .psd1 文件和每个资源的 schema.mof
MOF 应为每个元素提供说明 - 请参阅问题 #131
资源模块应具有 .psd1 文件（始终）和 schema.mof（对于非类资源），请参阅问题 #116
对 Set DSC 方法使用 ShouldProcess
资源模块包含包含资源的 DscResources 文件夹 - 请参阅问题 #130

引用