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

Description

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

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

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

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

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

範例

範例 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 和 PSAvoidUsingInternalURLs 以外的所有規則，.ps1 和 .psm1MyModules 目錄中的檔案及其子目錄中。

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

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

本範例會在 Test-Script.ps1 上執行腳本分析器，並在 C:\CommunityAnalyzerRules 路徑中使用標準規則和規則。

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 屬性來隱藏 PSUseSingularNouns 和 PSAvoidUsingCmdletAliases 腳本 Get-Widgets 中 Get-Widgets.ps1 函式的規則。 您可以使用這個屬性來隱藏模組、腳稿、類別、函式、參數或行的規則。

第一個命令會在包含函式的腳本檔案上執行 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 檔案中。 我們在 Invoke-ScriptAnalyzer 模組檔案上執行 。 Profile 參數的值是腳本分析器配置檔的路徑。

# 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
                                                                  because
                                                                  there i
                                                                  suppres
                                                                  Write-O
PSUseSingularNouns                  Warning                 1     The cmd
                                                                  noun sh

當您使用 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中包含修正的特定警告。

當您使用 Fix時，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 來選取您想要執行的規則。

嚴重性 參數的優先順序高於 includeRule 。 例如，如果 嚴重性 是 Error，則您無法使用 IncludeRule 來包含 Warning 規則。

參數屬性

類型:	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 物件。

相關連結

• Get-ScriptAnalyzerRule
• GitHub 上的 PSScriptAnalyzer