Invoke-ScriptAnalyzer

參考

模組:: PSScriptAnalyzer

根據選取的最佳做法規則評估腳本或模組

語法

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

在執行 Cmdlet 前提示您確認。

類型:	SwitchParameter
別名:	cf
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-CustomRulePath

輸入定義規則的檔案路徑，或包含定義規則之檔案的目錄。支援使用萬用字元。指定 CustomRulePath 時，只會使用指定路徑中找到的自訂規則來進行分析。如果 Invoke-ScriptAnalyzer 在中找不到規則，它會在不請注意的情況下執行標準規則。

若要新增路徑子目錄中定義的規則，請使用 RecurseCustomRulePath 參數。若要包含內建規則，請新增 IncludeDefaultRules 參數。

類型:	String[]
別名:	CustomizedRulePath
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	True

-EnableExit

完成分析時，此參數會結束 PowerShell 會話，並傳回等於錯誤記錄數目的結束代碼。這在持續整合 (CI) 管線中很有用。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ExcludeRule

省略腳本分析器測試中指定的規則。支援使用萬用字元。

輸入以逗號分隔的規則名稱清單、包含規則名稱的變數，或取得規則名稱的命令。您也可以在腳本分析器設定檔檔中指定排除規則的清單。您可以在自訂規則路徑中排除標準規則和規則。

當您排除規則時，規則不會在路徑中的任何檔案上執行。若要排除特定行、參數、函式、腳本或類別的規則，請調整 Path 參數或隱藏規則。如需隱藏規則的相關資訊，請參閱範例。

如果在 ExcludeRule 和 IncludeRule 集合中指定規則，則會排除規則。

類型:	String[]
Position:	Named
預設值:	All rules are included.
必要:	False
接受管線輸入:	False
接受萬用字元:	True

-Fix

修正在其 DiagnosticRecord中包含修正的特定警告。

當您使用 修正時， Invoke-ScriptAnalyzer 請先套用修正程式，再執行分析。使用此參數時，請確定您有檔案的備份。它會嘗試保留檔案編碼，但在某些情況下，編碼可能會變更。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-IncludeDefaultRules

叫用預設規則以及自訂規則。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-IncludeRule

只在腳本分析器測試中執行指定的規則。根據預設，PSScriptAnalyzer 會執行所有規則。

輸入以逗號分隔的規則名稱清單、包含規則名稱的變數，或取得規則名稱的命令。支援使用萬用字元。您也可以在腳本分析器設定檔檔中指定規則名稱。

當您使用 CustomRulePath 參數時，可以使用此參數在自訂規則路徑中包含標準規則和規則。

如果在 ExcludeRule 和 IncludeRule 集合中指定規則，則會排除規則。

Severity參數優先于IncludeRule。例如，如果 Severity 為 Error ，則您無法使用 IncludeRule 來包含 Warning 規則。

類型:	String[]
Position:	Named
預設值:	All rules are included.
必要:	False
接受管線輸入:	False
接受萬用字元:	True

-IncludeSuppressed

在輸出中包含隱藏的診斷。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-Path

指定要分析之腳本或模組的路徑。支援使用萬用字元。

輸入腳本 (.ps1) 或模組檔案 .psm1 的路徑， () 或包含腳本或模組的目錄。如果目錄包含其他類型的檔案，則會忽略它們。

若要分析不在指定路徑根目錄中的檔案，請使用萬用字元 (C:\Modules\MyModule\*) 或 Recurse 參數。

類型:	String
別名:	PSPath
Position:	0
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	True

-Recurse

在 Path 目錄中的檔案上執行腳本分析器，並以遞迴方式對所有子目錄執行。

遞迴僅適用于 Path 參數值。若要以遞迴方式搜尋 CustomRulePath ，請使用 RecurseCustomRulePath 參數。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-RecurseCustomRulePath

新增 CustomRulePath 位置子目錄中定義的規則。根據預設， Invoke-ScriptAnalyzer 只會使用指定檔案或目錄中定義的自訂規則。若要包含內建規則，請使用 IncludeDefaultRules 參數。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ReportSummary

將發現違規的摘要寫入主機。

類型:	SwitchParameter
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
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ScriptDefinition

在字串中的命令、函式或運算式上執行分析。您可以使用這項功能來分析語句、運算式和函式，與其腳本內容無關。

類型:	String
Position:	0
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

-Settings

包含使用者定義設定檔的檔案路徑，或包含 ScriptAnalyzer 設定的雜湊表物件。

使用 Invoke-ScriptAnalyzer 檔案或雜湊表中指定的參數和值執行。

如果檔案或雜湊表的路徑或內容無效，則會忽略它。設定檔中的參數和值優先于命令列中指定的相同參數和值。

腳本分析器設定檔檔是文字檔，其中包含具有下列一或多個索引鍵的雜湊表：

CustomRulePath
ExcludeRules
IncludeDefaultRules
IncludeRules
RecurseCustomRulePath
規則
嚴重性

設定檔中的索引鍵和值會解譯為標準參數和的值 Invoke-ScriptAnalyzer ，類似于展開。如需詳細資訊，請參閱 about_Splatting。

類型:	Object
別名:	Profile
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Severity

使用所有規則執行腳本分析器之後，此參數會選取具有指定嚴重性的規則違規。

有效值為：

[錯誤]
警告
資訊。

您可以指定一個或多個嚴重性值。

參數只會在執行所有規則之後篩選規則違規。若要有效率地篩選規則，請使用 Get-ScriptAnalyzerRule 來選取您想要執行的規則。

Severity參數優先于IncludeRule。例如，如果 Severity 為 Error ，則您無法使用 IncludeRule 來包含 Warning 規則。

類型:	String[]
Position:	Named
預設值:	All rule violations
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-SuppressedOnly

只會針對隱藏的規則傳回違規。

會 (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord) 傳回SuppressedRecord物件。

若要隱藏規則，請使用 SuppressMessageAttribute。如需說明，請參閱範例。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-WhatIf

顯示執行 Cmdlet 後會發生的情況。 Cmdlet 並不會執行。

類型:	SwitchParameter
別名:	wi
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

None

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

輸出

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

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

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

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

共用方式為

Invoke-ScriptAnalyzer

語法

Description

範例

範例 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

輸入

輸出

其他資源

共用方式為

Invoke-ScriptAnalyzer

語法

Description

範例

範例 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

輸入

輸出

相關連結

其他資源