Invoke-ScriptAnalyzer

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>]

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>]

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

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，退出代码等于错误记录数。

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

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

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

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

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

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

Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs

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

Invoke-ScriptAnalyzer -Path D:\test_scripts\Test-Script.ps1 -CustomRulePath C:\CommunityAnalyzerRules -IncludeDefaultRules

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

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

该示例使用 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  ManageProf 14    The cmdlet 'Get-Widget' does not have a help comment.
                                                 iles.psm1

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

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

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

在此示例中，我们将创建一个脚本分析器配置文件，并将其保存在当前目录中的 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 将使用配置文件值并忽略参数。

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

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

RuleName                            Severity     FileName   Line  Message
--------                            --------     --------   ----  -------
PSAvoidUsingWriteHost               Warning                 1     Script
                                                                  because
                                                                  there i
                                                                  suppres
                                                                  Write-O
PSUseSingularNouns                  Warning                 1     The cmd
                                                                  noun sh

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

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

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

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

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