次の方法で共有


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 オブジェクトを返します。