Invoke-ScriptAnalyzer

模块:: PSScriptAnalyzer Module

根据所选的最佳做法规则评估脚本或模块

语法

Path_SuppressedOnly (默认值)

Invoke-ScriptAnalyzer
    [-Path] <string>
    [-CustomRulePath <string[]>]
    [-RecurseCustomRulePath]
    [-IncludeDefaultRules]
    [-ExcludeRule <string[]>]
    [-IncludeRule <string[]>]
    [-Severity <string[]>]
    [-Recurse]
    [-SuppressedOnly]
    [-Fix]
    [-EnableExit]
    [-Settings <Object>]
    [-SaveDscDependency]
    [-ReportSummary]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Path_IncludeSuppressed

Invoke-ScriptAnalyzer
    [-Path] <string>
    -IncludeSuppressed
    [-CustomRulePath <string[]>]
    [-RecurseCustomRulePath]
    [-IncludeDefaultRules]
    [-ExcludeRule <string[]>]
    [-IncludeRule <string[]>]
    [-Severity <string[]>]
    [-Recurse]
    [-Fix]
    [-EnableExit]
    [-Settings <Object>]
    [-SaveDscDependency]
    [-ReportSummary]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

ScriptDefinition_IncludeSuppressed

Invoke-ScriptAnalyzer
    [-ScriptDefinition] <string>
    -IncludeSuppressed
    [-CustomRulePath <string[]>]
    [-RecurseCustomRulePath]
    [-IncludeDefaultRules]
    [-ExcludeRule <string[]>]
    [-IncludeRule <string[]>]
    [-Severity <string[]>]
    [-Recurse]
    [-EnableExit]
    [-Settings <Object>]
    [-SaveDscDependency]
    [-ReportSummary]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

ScriptDefinition_SuppressedOnly

Invoke-ScriptAnalyzer
    [-ScriptDefinition] <string>
    [-CustomRulePath <string[]>]
    [-RecurseCustomRulePath]
    [-IncludeDefaultRules]
    [-ExcludeRule <string[]>]
    [-IncludeRule <string[]>]
    [-Severity <string[]>]
    [-Recurse]
    [-SuppressedOnly]
    [-EnableExit]
    [-Settings <Object>]
    [-SaveDscDependency]
    [-ReportSummary]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

说明

Invoke-ScriptAnalyzer 基于最佳做法规则的集合评估脚本或模块文件（.ps1、.psm1和 .psd1 文件），并返回表示违反规则的对象。它还包括用于分析 DSC 资源的特殊规则。

Invoke-ScriptAnalyzer 附带一组内置规则。默认情况下，它使用所有规则。可以使用 IncludeRule 和 ExcludeRule 参数来选择所需的规则。可以使用 Get-ScriptAnalyzerRule cmdlet 检查和选择要从评估中包括或排除的规则。

还可以使用在 PowerShell 脚本中编写的自定义规则，或使用 C# 在程序集中编译。还可以使用 IncludeRule 和 ExcludeRule 参数来选择自定义规则。

还可以在分析中包含规则，但禁止显示所选函数或脚本的该规则的输出。仅在必要时才应使用此功能。若要获取取消的规则，请使用 Invoke-ScriptAnalyzer 参数运行。

对于 CI 系统中的使用，EnableExit 退出 shell，退出代码等于错误记录数。

示例

示例 1 - 在脚本上运行所有脚本分析器规则

Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1

示例 2 - 对 Modules 目录中的所有文件运行所有脚本分析器规则

此示例针对基于用户的 .ps1 目录及其子目录中的所有 .psm1 和 Modules 文件运行所有脚本分析器规则。

Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse

示例 3 - 在模块上运行单个规则

此示例仅对模块文件夹中的文件运行 PSDiagnostics 规则。可以使用如下所示的命令查找特定规则冲突的所有实例。

Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters

示例 4 - 在模块上运行除两个规则之外的所有规则

本示例运行除 PSAvoidUsingCmdletAliases 和 PSAvoidUsingInternalUR Ls 以外的所有规则，.ps1 和 .psm1MyModules 目录中 .psm1 文件及其子目录中。

$invokeScriptAnalyzerSplat = @{
    Path = 'C:\ps-test\MyModule'
    Recurse = $true
    ExcludeRule = 'PSAvoidUsingCmdletAliases', 'PSAvoidUsingInternalURLs'
}
Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat

示例 5 - 使用自定义规则运行脚本分析器

此示例使用 Test-Script.ps1 路径中的标准规则和规则在 C:\CommunityAnalyzerRules 上运行脚本分析器。

$invokeScriptAnalyzerSplat = @{
    Path = 'D:\test_scripts\Test-Script.ps1'
    CustomRulePath = 'C:\CommunityAnalyzerRules'
    IncludeDefaultRules = $true
}
Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat

示例 6 - 仅运行错误严重性并具有 PSDSC 源名称的规则

$DSCError = Get-ScriptAnalyzerRule -Severity Error |
    Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse

示例 7 - 禁止违反规则

此示例演示如何禁止在函数中报告规则冲突，以及如何发现禁止的规则冲突。

该示例使用 SuppressMessageAttribute 属性来禁止 PSUseSingularNouns 和 PSAvoidUsingCmdletAliasesGet-Widgets 脚本中 Get-Widgets.ps1 函数的规则。可以使用此属性来禁止显示模块、脚本、类、函数、参数或行的规则。

第一个命令在包含函数的脚本文件上运行脚本分析器。输出报告规则冲突。尽管违反了更多规则，但不会报告任何禁止的规则。

function Get-Widgets
{
    [CmdletBinding()]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "",
        Justification="Resolution in progress.")]
    Param()

    dir $PSHOME
    ...
}

Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1

RuleName                  Severity     FileName            Line  Message
--------                  --------     --------            ----  -------
PSProvideCommentHelp      Information  ManageProfiles.psm1 14    The cmdlet 'Get-Widget' does not have a help comment.

Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly

Rule Name                   Severity  File Name           Line  Justification
---------                   --------  ---------           ----  -------------
PSAvoidUsingCmdletAliases   Warning   ManageProfiles.psm1 21    Resolution in progress.
PSUseSingularNouns          Warning   ManageProfiles.psm1 14

第二个命令使用 SuppressedOnly 参数报告禁止的脚本文件规则的冲突。

示例 8 - 使用配置文件定义分析脚本文件

在此示例中，我们将创建一个脚本分析器配置文件，并将其保存在当前目录中的 ScriptAnalyzerProfile.txt 文件中。我们在 Invoke-ScriptAnalyzer 模块文件上运行。 配置文件 参数的值是脚本分析器配置文件的路径。

# In .\ScriptAnalyzerProfile.txt
@{
    Severity = @('Error', 'Warning')
    IncludeRules = 'PSAvoid*'
    ExcludeRules = '*WriteHost'
}

Invoke-ScriptAnalyzer -Path $PSHOME\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt

如果在 Invoke-ScriptAnalyzer 命令（如 -Severity Error）中包含冲突参数，则 cmdlet 将使用配置文件值并忽略参数。

示例 9 - 分析存储为字符串的脚本

此示例使用 ScriptDefinition 参数在命令行中分析函数。函数字符串用引号引起来。

Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello'}"

RuleName               Severity     FileName   Line  Message
--------               --------     --------   ----  -------
PSAvoidUsingWriteHost  Warning                 1     Script definition 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.
PSUseSingularNouns     Warning                 1     The cmdlet 'Get-Widgets' uses a plural noun. A
                                                     singular noun should be used instead.

使用 ScriptDefinition 参数时，DiagnosticRecord 对象的 FileName 属性 $null。

参数

-Confirm

在运行 cmdlet 之前，提示你进行确认。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False
别名:	cf

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-CustomRulePath

输入文件的路径，该文件定义规则或包含定义规则的文件的目录。支持通配符。 CustomRulePath 指定时，仅使用指定路径中找到的自定义规则用于分析。如果 Invoke-ScriptAnalyzer 找不到规则，则会在不通知的情况下运行标准规则。

若要添加路径的子目录中定义的规则，请使用 RecurseCustomRulePath 参数。若要包含内置规则，请添加 IncludeDefaultRules 参数。

参数属性

类型:	String[]
默认值:	None
支持通配符:	True
不显示:	False
别名:	自定义规则路径

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-EnableExit

分析完成后，此参数将退出 PowerShell 会话，并返回等于错误记录数的退出代码。这在持续集成（CI）管道中非常有用。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ExcludeRule

省略脚本分析器测试中的指定规则。支持通配符。

输入规则名称的逗号分隔列表、包含规则名称的变量或获取规则名称的命令。还可以在脚本分析器配置文件中指定排除规则的列表。可以在自定义规则路径中排除标准规则和规则。

排除规则时，该规则不会在路径中的任何文件上运行。若要排除特定行、参数、函数、脚本或类上的规则，请调整 Path 参数或取消规则。有关取消规则的信息，请参阅示例。

如果在 excludeRule 和 IncludeRule 集合中都指定了规则，则排除该规则。

参数属性

类型:	String[]
默认值:	All rules are included.
支持通配符:	True
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Fix

修复了在其 DiagnosticRecord中包含修补程序的某些警告。

使用修复时，Invoke-ScriptAnalyzer 在运行分析之前应用修补程序。使用此参数时，请确保已备份文件。它尝试保留文件编码，但在某些情况下，编码可能会更改。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

Path_SuppressedOnly

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

Path_IncludeSuppressed

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-IncludeDefaultRules

调用默认规则以及自定义规则。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-IncludeRule

仅在脚本分析器测试中运行指定的规则。默认情况下，PSScriptAnalyzer 运行所有规则。

输入规则名称的逗号分隔列表、包含规则名称的变量或获取规则名称的命令。支持通配符。还可以在脚本分析器配置文件中指定规则名称。

使用 CustomRulePath 参数时，可以使用此参数在自定义规则路径中包含标准规则和规则。

如果在 excludeRule 和 IncludeRule 集合中都指定了规则，则排除该规则。

严重性 参数优先于 IncludeRule。例如，如果 严重性Error，则无法使用 IncludeRule 来包含 Warning 规则。

参数属性

类型:	String[]
默认值:	All rules are included.
支持通配符:	True
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-IncludeSuppressed

在输出中包含禁止的诊断。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

Path_IncludeSuppressed

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

ScriptDefinition_IncludeSuppressed

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Path

指定要分析的脚本或模块的路径。支持通配符。

输入脚本（.ps1）或模块文件（.psm1）或包含脚本或模块的目录的路径。如果目录包含其他类型的文件，则忽略它们。

若要分析不在指定路径的根目录中的文件，请使用通配符（C:\Modules\MyModule\*）或 Recurse 参数。

参数属性

类型:	String
默认值:	None
支持通配符:	True
不显示:	False
别名:	PSPath

参数集

Path_SuppressedOnly

Position:	0
必需:	True
来自管道的值:	True
来自管道的值（按属性名称）:	True
来自剩余参数的值:	False

Path_IncludeSuppressed

Position:	0
必需:	True
来自管道的值:	True
来自管道的值（按属性名称）:	True
来自剩余参数的值:	False

-Recurse

在 Path 目录和所有子目录中的文件上以递归方式运行脚本分析器。

Recurse 仅适用于 Path 参数值。若要以递归方式搜索 CustomRulePath，请使用 RecurseCustomRulePath 参数。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-RecurseCustomRulePath

添加在 CustomRulePath 位置的子目录中定义的规则。默认情况下，Invoke-ScriptAnalyzer 仅使用指定文件或目录中定义的自定义规则。若要包含内置规则，请使用 IncludeDefaultRules 参数。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ReportSummary

编写发现给主机的冲突摘要。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-SaveDscDependency

解决 DSC 资源依赖项。

使用此参数运行 Invoke-ScriptAnalyzer 时，它会查找 Import-DSCResource -ModuleName <somemodule>实例。如果无法通过搜索 <somemodule>找到 $env:PSModulePath，则 Invoke-ScriptAnalyzer 返回分析错误。此错误是由 PowerShell 分析程序无法找到 <somemodule>符号引起的。

如果 Invoke-ScriptAnalyzer PowerShell 库中找到该模块，则会将缺少的模块下载到临时路径。然后，在扫描期间将临时路径添加到 $env:PSModulePath。可以在 $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir中找到临时位置。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ScriptDefinition

对字符串中的命令、函数或表达式运行分析。可以使用此功能来分析语句、表达式和函数，与脚本上下文无关。

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

ScriptDefinition_IncludeSuppressed

Position:	0
必需:	True
来自管道的值:	True
来自管道的值（按属性名称）:	True
来自剩余参数的值:	False

ScriptDefinition_SuppressedOnly

Position:	0
必需:	True
来自管道的值:	True
来自管道的值（按属性名称）:	True
来自剩余参数的值:	False

-Settings

包含用户定义的配置文件的文件的路径，或包含 ScriptAnalyzer 设置的哈希表对象。

使用文件或哈希表中指定的参数和值运行 Invoke-ScriptAnalyzer。

如果文件或哈希表的路径或内容无效，则忽略它。配置文件中的参数和值优先于命令行中指定的相同参数和值。

脚本分析器配置文件是包含包含以下一个或多个键的哈希表的文本文件：

CustomRulePath
ExcludeRules
IncludeDefaultRules
IncludeRules
RecurseCustomRulePath
规则
严重程度

配置文件中的键和值被解释为标准参数和 Invoke-ScriptAnalyzer的值，类似于散点。有关详细信息，请参阅 about_Splatting。

参数属性

类型:	Object
默认值:	None
支持通配符:	False
不显示:	False
别名:	个人资料

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Severity

使用所有规则运行脚本分析器后，此参数将选择具有指定严重性的规则冲突。

有效值为：

错误
警告
信息
解析错误

你可以指定一个或多个严重度值。

参数仅在运行完所有规则后过滤规则违规输出。它不会过滤运行哪些规则。若要有效地筛选规则，请使用 Get-ScriptAnalyzerRule 选择要运行的规则。

参数属性

类型:	String[]
默认值:	All rule violations
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-SuppressedOnly

仅针对禁止的规则返回冲突。

返回 SuppressedRecord 对象（Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord）。

若要取消规则，请使用 SuppressMessageAttribute。有关帮助，请参阅示例。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False

参数集

Path_SuppressedOnly

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

ScriptDefinition_SuppressedOnly

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-WhatIf

显示 cmdlet 运行时会发生什么情况。命令脚本未运行。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False
别名:	无线

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

CommonParameters

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。有关详细信息，请参阅 about_CommonParameters。

输入

None

不能通过管道将输入传递给此 cmdlet。

输出

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

默认情况下，Invoke-ScriptAnalyzer 为每个规则冲突返回一个 DiagnosticRecord 对象。

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

如果使用 SuppressedOnly 参数，Invoke-ScriptAnalyzer 将返回 SuppressedRecord 对象。

反馈

此页面是否有帮助？

Invoke-ScriptAnalyzer

语法

Path_SuppressedOnly (默认值)

Path_IncludeSuppressed

ScriptDefinition_IncludeSuppressed

ScriptDefinition_SuppressedOnly

说明

示例

示例 1 - 在脚本上运行所有脚本分析器规则

示例 2 - 对 Modules 目录中的所有文件运行所有脚本分析器规则

示例 3 - 在模块上运行单个规则

示例 4 - 在模块上运行除两个规则之外的所有规则

示例 5 - 使用自定义规则运行脚本分析器

示例 6 - 仅运行错误严重性并具有 PSDSC 源名称的规则

示例 7 - 禁止违反规则

示例 8 - 使用配置文件定义分析脚本文件

示例 9 - 分析存储为字符串的脚本

参数

-Confirm

参数属性

参数集

-CustomRulePath

参数属性

参数集

-EnableExit

参数属性

参数集

-ExcludeRule

参数属性

参数集

-Fix

参数属性

参数集

-IncludeDefaultRules

参数属性

参数集

-IncludeRule

参数属性

参数集

-IncludeSuppressed

参数属性

参数集

-Path

参数属性

参数集

-Recurse

参数属性

参数集

-RecurseCustomRulePath

参数属性

参数集

-ReportSummary

参数属性

参数集

-SaveDscDependency

参数属性

参数集

-ScriptDefinition

参数属性

参数集

-Settings

参数属性

参数集

-Severity

参数属性

参数集

-SuppressedOnly

参数属性

参数集

-WhatIf

参数属性

参数集

CommonParameters

输入

None

输出

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

相关链接

反馈