Invoke-ScriptAnalyzer
選択したベスト プラクティス ルールに基づいてスクリプトまたはモジュールを評価します
構文
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>]
説明
Invoke-ScriptAnalyzer は、ベスト プラクティス ルールのコレクションに基づいてスクリプトまたはモジュール ファイル (.ps1、.psm1、および .psd1 ファイル) を評価し、規則違反を表すオブジェクトを返します。 また、DSC リソースを分析するための特別な規則も含まれています。
Invoke-ScriptAnalyzer には、一連の組み込み規則が付属しています。 既定では、すべてのルールが使用されます。
IncludeRule と ExcludeRule パラメーター 使用して、必要なルールを選択できます。
Get-ScriptAnalyzerRule コマンドレットを使用して、評価に含めるルールまたは評価から除外するルールを調べて選択できます。
PowerShell スクリプトで記述するカスタマイズされた規則を使用したり、C# を使用してアセンブリでコンパイルしたりすることもできます。 IncludeRule と ExcludeRule パラメーター 使用して、カスタム ルールを選択することもできます。
分析にルールを含めることもできますが、選択した関数またはスクリプトに対するそのルールの出力を抑制することもできます。 この機能は、必要な場合にのみ使用してください。 抑制されたルールを取得するには、Invoke-ScriptAnalyzer パラメーターを使用して を実行します。
CI システムで使用する場合、EnableExit は、エラー レコードの数と同じ終了コードでシェルを終了します。
例
例 1 - スクリプトに対してすべてのスクリプト アナライザー ルールを実行する
Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1
例 2 - Modules ディレクトリ内のすべてのファイルに対してすべての Script Analyzer ルールを実行する
この例では、ユーザー ベースの .ps1 ディレクトリとそのサブディレクトリ内のすべての .psm1 ファイルと Modules ファイルに対して、すべての Script Analyzer ルールを実行します。
Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse
例 3 - モジュールで 1 つのルールを実行する
次の使用例は、 モジュール フォルダー内のファイルに対して PSDiagnostics ルールのみを実行します。 このようなコマンドを使用して、特定の規則違反のすべてのインスタンスを見つけることができます。
Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters
例 4 - モジュールで 2 つを除くすべてのルールを実行する
次の使用例は、PSAvoidUsingCmdletAliases および MyModules します。
Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs
例 5 - カスタム 規則を使用してスクリプト アナライザーを実行する
この例では、Test-Script.ps1 パスの標準の規則と規則を使用して、C:\CommunityAnalyzerRules で 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 属性を使用して、 スクリプトの 関数の PSUseSingularNouns 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
2 番目のコマンドでは、SuppressedOnly パラメーターを使用して、抑制されたスクリプト ファイルの規則違反を報告します。
例 8 - プロファイル定義を使用してスクリプト ファイルを分析する
この例では、Script Analyzer プロファイルを作成し、現在のディレクトリの ScriptAnalyzerProfile.txt ファイルに保存します。
Invoke-ScriptAnalyzer モジュール ファイルで を実行します。
Profile パラメーターの値は、Script Analyzer プロファイルへのパスです。
# In .\ScriptAnalyzerProfile.txt
@{
Severity = @('Error', 'Warning')
IncludeRules = 'PSAvoid*'
ExcludeRules = '*WriteHost'
}
Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt
Invoke-ScriptAnalyzerなど、-Severity Error コマンドに競合するパラメーターを含める場合、コマンドレットはプロファイル値を使用し、パラメーターを無視します。
例 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
コマンドレットを実行する前に確認を求めるメッセージが表示されます。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
| Aliases: | cf |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-CustomRulePath
ルールを定義するファイルまたはルールを定義するファイルを含むディレクトリへのパスを入力します。
ワイルドカード文字がサポートされています。 CustomRulePath 指定すると、指定したパスで見つかったカスタム 規則のみが分析に使用されます。
Invoke-ScriptAnalyzer にルールが見つからない場合は、通知なしに標準ルールが実行されます。
パスのサブディレクトリで定義されている規則を追加するには、RecurseCustomRulePath パラメーターを使用します。 組み込み規則を含めるには、IncludeDefaultRules パラメーター 追加します。
パラメーターのプロパティ
| 型: | String[] |
| 規定値: | None |
| ワイルドカードのサポート: | True |
| DontShow: | False |
| Aliases: | カスタマイズされたルールパス |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-EnableExit
分析が完了すると、このパラメーターは PowerShell セッションを終了し、エラー レコードの数と同じ終了コードを返します。 これは、継続的インテグレーション (CI) パイプラインで役立ちます。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-ExcludeRule
Script Analyzer テストから指定した規則を省略します。 ワイルドカード文字がサポートされています。
ルール名のコンマ区切りのリスト、ルール名を含む変数、またはルール名を取得するコマンドを入力します。 Script Analyzer プロファイル ファイルで除外されるルールの一覧を指定することもできます。 カスタム ルール パスでは、標準のルールとルールを除外できます。
ルールを除外すると、パス内のどのファイルでもルールは実行されません。 特定の行、パラメーター、関数、スクリプト、またはクラスのルールを除外するには、Path パラメーターを調整するか、ルールを抑制します。 ルールの抑制の詳細については、例を参照してください。
ExcludeRule と IncludeRule コレクション 両方でルールが指定されている場合、ルールは除外されます。
パラメーターのプロパティ
| 型: | String[] |
| 規定値: | All rules are included. |
| ワイルドカードのサポート: | True |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-Fix
DiagnosticRecordの修正を含む特定の警告を修正します。
Fixを使用した場合、Invoke-ScriptAnalyzer は、分析を実行する前に修正プログラムを適用します。 このパラメーターを使用するときは、ファイルのバックアップがあることを確認してください。 ファイル エンコーディングを保持しようとしますが、エンコードが変更される場合もあります。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
Path_SuppressedOnly
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
Path_IncludeSuppressed
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-IncludeDefaultRules
カスタム ルールと共に既定のルールを呼び出します。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-IncludeRule
Script Analyzer テストで指定されたルールのみを実行します。 既定では、PSScriptAnalyzer はすべてのルールを実行します。
ルール名のコンマ区切りのリスト、ルール名を含む変数、またはルール名を取得するコマンドを入力します。 ワイルドカード文字がサポートされています。 Script Analyzer プロファイル ファイルでルール名を指定することもできます。
CustomizedRulePath パラメーターを使用する場合は、このパラメーターを使用して、カスタム 規則パスに標準の規則と規則を含めることができます。
ExcludeRule と IncludeRule コレクション 両方でルールが指定されている場合、ルールは除外されます。
Severity パラメーターは、IncludeRule よりも優先されます。 たとえば、重大度 が Errorされている場合、IncludeRule 使用して Warning ルールを含めることはできません。
パラメーターのプロパティ
| 型: | String[] |
| 規定値: | All rules are included. |
| ワイルドカードのサポート: | True |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-IncludeSuppressed
抑制された診断を出力に含めます。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
Path_IncludeSuppressed
| 配置: | Named |
| 必須: | True |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
ScriptDefinition_IncludeSuppressed
| 配置: | Named |
| 必須: | True |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-Path
分析するスクリプトまたはモジュールへのパスを指定します。 ワイルドカード文字がサポートされています。
スクリプト (.ps1) またはモジュール ファイル (.psm1) またはスクリプトまたはモジュールを含むディレクトリへのパスを入力します。 ディレクトリに他の種類のファイルが含まれている場合、それらは無視されます。
指定したパスのルート ディレクトリにないファイルを分析するには、ワイルドカード文字 (C:\Modules\MyModule\*) または Recurse パラメーターを使用します。
パラメーターのプロパティ
| 型: | String |
| 規定値: | None |
| ワイルドカードのサポート: | True |
| DontShow: | False |
| Aliases: | PSPath |
パラメーター セット
Path_SuppressedOnly
| 配置: | 0 |
| 必須: | True |
| パイプラインからの値: | True |
| プロパティ名別のパイプラインからの値: | True |
| 残りの引数からの値: | False |
Path_IncludeSuppressed
| 配置: | 0 |
| 必須: | True |
| パイプラインからの値: | True |
| プロパティ名別のパイプラインからの値: | True |
| 残りの引数からの値: | False |
-Recurse
パス ディレクトリ内のファイルとすべてのサブディレクトリに対して Script Analyzer を再帰的に実行します。
再帰は Path パラメーター値にのみ適用されます。 CustomRulePath を再帰的に検索するには、RecurseCustomRulePath パラメーターを使用します。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-RecurseCustomRulePath
CustomRulePath の場所のサブディレクトリで定義されている規則を追加します。 既定では、Invoke-ScriptAnalyzer では、指定したファイルまたはディレクトリで定義されているカスタム規則のみが使用されます。 組み込みの規則を含めるには、IncludeDefaultRules パラメーターを使用します。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-ReportSummary
ホストに見つかった違反の概要を書き込みます。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | 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 |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-ScriptDefinition
文字列内のコマンド、関数、または式に対して分析を実行します。 この機能を使用すると、スクリプト コンテキストに関係なく、ステートメント、式、関数を分析できます。
パラメーターのプロパティ
| 型: | String |
| 規定値: | None |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
ScriptDefinition_IncludeSuppressed
| 配置: | 0 |
| 必須: | True |
| パイプラインからの値: | True |
| プロパティ名別のパイプラインからの値: | True |
| 残りの引数からの値: | False |
ScriptDefinition_SuppressedOnly
| 配置: | 0 |
| 必須: | True |
| パイプラインからの値: | True |
| プロパティ名別のパイプラインからの値: | True |
| 残りの引数からの値: | False |
-Settings
ユーザー定義プロファイルまたは ScriptAnalyzer の設定を含むハッシュテーブル オブジェクトを含むファイルへのパス。
ファイルまたはハッシュテーブルで指定されたパラメーターと値を使用して Invoke-ScriptAnalyzer を実行します。
ファイルまたはハッシュテーブルのパスまたは内容が無効な場合は無視されます。 プロファイル内のパラメーターと値は、コマンド ラインで指定されたのと同じパラメーターと値よりも優先されます。
Script Analyzer プロファイル ファイルは、次の 1 つ以上のキーを持つハッシュテーブルを含むテキスト ファイルです。
- CustomRulePath
- ExcludeRules
- IncludeDefaultRules
- IncludeRules
- RecurseCustomRulePath
- 準則
- 深刻さ
プロファイルのキーと値は、スプラッティングと同様に、Invoke-ScriptAnalyzerの標準パラメーターと値であるかのように解釈されます。 詳細については、about_Splattingを参照してください。
パラメーターのプロパティ
| 型: | Object |
| 規定値: | None |
| ワイルドカードのサポート: | False |
| DontShow: | False |
| Aliases: | プロフィール |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-Severity
すべてのルールで Script Analyzer を実行した後、このパラメーターは指定された重大度の規則違反を選択します。
有効な値は次のとおりです。
- エラー
- Warnung
- 情報。
1 つ以上の重大度値を指定できます。
パラメーターは、すべてのルールを実行した後にのみ、規則違反をフィルター処理します。 ルールを効率的にフィルター処理するには、Get-ScriptAnalyzerRule を使用して、実行するルールを選択します。
Severity パラメーターは、IncludeRule よりも優先されます。 たとえば、重大度 が Errorされている場合、IncludeRule 使用して Warning ルールを含めることはできません。
パラメーターのプロパティ
| 型: | String[] |
| 規定値: | All rule violations |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-SuppressedOnly
抑制されたルールに対してのみ違反を返します。
SuppressedRecord オブジェクト (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord) を返します。
ルールを抑制するには、SuppressMessageAttributeを使用します。 ヘルプについては、例を参照してください。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
Path_SuppressedOnly
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
ScriptDefinition_SuppressedOnly
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-WhatIf
コマンドレットを実行した場合の動作を示します。 コマンドレットは実行されません。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
| Aliases: | ウィスコンシン |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
CommonParameters
このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。 詳細については、about_CommonParametersを参照してください。
入力
None
パイプを使用してこのコマンドレットに入力を渡すことはできません。
出力
Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord
既定では、Invoke-ScriptAnalyzer は、規則違反ごとに 1 つの DiagnosticRecord オブジェクトを返します。
Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord
SuppressedOnly パラメーターを使用する場合は、Invoke-ScriptAnalyzer 代わりに SuppressedRecord オブジェクトを返します。