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

Description

Invoke-ScriptAnalyzer 會根據最佳做法規則集合評估腳本或模組檔案 (.ps1 、 .psm1 和 .psd1 檔案) ，並傳回代表規則違規的物件。 它也包含用來分析 DSC 資源的特殊規則。

Invoke-ScriptAnalyzer 隨附一組內建規則。 根據預設，它會使用所有規則。 您可以使用 IncludeRule 和 ExcludeRule 參數來選取您想要的規則。 您可以使用 Get-ScriptAnalyzerRule Cmdlet 來檢查並選取您想要包含或排除評估的規則。

您也可以使用您在 PowerShell 腳本中撰寫的自訂規則，或使用 C# 在元件中編譯。 您也可以使用 IncludeRule 和 ExcludeRule 參數來選取自訂規則。

您也可以在分析中包含規則，但隱藏所選函式或腳本的該規則輸出。 此功能僅在必要時才應該使用。 若要取得已隱藏的規則，請使用SuppressedOnly參數執行 Invoke-ScriptAnalyzer 。

針對 CI 系統中的使用方式， EnableExit 會結束殼層，其結束代碼等於錯誤記錄數目。

範例

範例 1 - 在腳本上執行所有腳本分析器規則

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

範例 2 - 在 Modules 目錄中的所有檔案上執行所有腳本分析器規則

本範例會在使用者型 Modules 目錄及其子目錄中的所有 .ps1 和 .psm1 檔案上執行所有腳本分析器規則。

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

範例 3 - 在模組上執行單一規則

此範例只會對模組資料夾中的 PSDiagnostics 檔案執行PSAvoidUsingPositionalParameters規則。 您可以使用這類命令來尋找特定規則違規的所有實例。

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

範例 4 - 在您的模組上執行兩個以外的所有規則

此範例會執行目錄中和其子目錄中和 .psm1 檔案 MyModules 上的 .ps1PSAvoidUsingInternalURLs 以外的所有規則 PSAvoidUsingCmdletAliases和PSAvoidUsingInternalURLs。

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

範例 5 - 使用自訂規則執行腳本分析器

此範例會使用路徑中的 C:\CommunityAnalyzerRules 標準規則和規則，在 上 Test-Script.ps1 執行 Script Analyzer。

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

範例 6 - 僅執行錯誤嚴重性且具有 PSDSC 來源名稱的規則

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

範例 7 - 隱藏規則違規

此範例示範如何在函式中隱藏規則違規的報告，以及如何探索隱藏的規則違規。

此範例會 SuppressMessageAttribute 使用 屬性來隱藏腳本中函式的 Get-Widgets.ps1PSUseSingularNouns和PSAvoidUsingCmdletAliases規則 Get-Widgets 。 您可以使用這個屬性來隱藏模組、腳本、類別、函式、參數或行的規則。

第一個命令會在包含函式的腳本檔案上執行 Script Analyzer。 輸出會報告規則違規。 即使違反更多規則，也不會報告任何隱藏的規則。

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 參數來報告隱藏腳本檔案的規則違規。

範例 8 - 使用設定檔定義分析腳本檔案

在此範例中，我們會建立腳本分析器設定檔，並將它儲存在 ScriptAnalyzerProfile.txt 目前目錄中的檔案中。 我們會在BitLocker模組檔案上執行 Invoke-ScriptAnalyzer 。 Profile參數的值是腳本分析器設定檔的路徑。

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

Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Profile .\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
                                                                  because
                                                                  there i
                                                                  suppres
                                                                  Write-O
PSUseSingularNouns                  Warning                 1     The cmd
                                                                  noun sh

當您使用ScriptDefinition參數時，DiagnosticRecord物件的FileName屬性是 $null 。

參數

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

輸入

None

您無法使用管線傳送輸入至此 Cmdlet。

輸出

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

根據預設， Invoke-ScriptAnalyzer 會針對每個規則違規傳回一個 DiagnosticRecord 物件。

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

如果您使用 SuppressedOnly 參數， Invoke-ScriptAnalyzer 請改為傳回 SuppressedRecord 物件。

相關連結

• Get-ScriptAnalyzerRule
• GitHub 上的 PSScriptAnalyzer