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 目錄中的檔案及其子目錄中。

$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 和 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  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 模組檔案上執行。 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 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中包含修正的特定警告。

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

參數屬性

類型:	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

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

參數屬性

參數集

CommonParameters

輸入

None

輸出

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

相關連結

意見反應