Invoke-ScriptAnalyzer

構文

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

説明

Invoke-ScriptAnalyzer は、ベスト プラクティス ルールのコレクションに基づいてスクリプトまたはモジュール ファイル (.ps1、、 .psm1および .psd1 ファイル) を評価し、ルール違反を表すオブジェクトを返します。 また、DSC リソースを分析するための特別なルールも含まれています。

Invoke-ScriptAnalyzer には、一連の組み込みルールが付属しています。 既定では、すべてのルールが使用されます。 IncludeRule パラメーターと ExcludeRule パラメーターを使用して、必要なルールを選択できます。 コマンドレットを Get-ScriptAnalyzerRule 使用して、評価に含める規則または評価から除外する規則を調べて選択できます。

また、PowerShell スクリプトで記述するカスタマイズされた規則を使用したり、C# を使用してアセンブリでコンパイルしたりすることもできます。 カスタム ルールは、 IncludeRule パラメーターと ExcludeRule パラメーターを使用して選択することもできます。

分析にルールを含めることもできますが、選択した関数またはスクリプトに対するそのルールの出力は抑制できます。 この機能は、必要な場合にのみ使用する必要があります。 抑制されたルールを取得するには、SuppressedOnly パラメーターを指定して を実行Invoke-ScriptAnalyzerします。

CI システムで使用する場合、 EnableExit はエラー レコードの数と同じ終了コードでシェルを終了します。

例

例 1 - スクリプトに対してすべてのスクリプト アナライザー ルールを実行する

Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1

例 2 - Modules ディレクトリ内のすべてのファイルに対してスクリプト アナライザーのすべてのルールを実行する

この例では、ユーザー ベースModulesのディレクトリとそのサブディレクトリ内のすべての ファイルと .psm1 ファイルに対して、すべての .ps1 Script Analyzer ルールを実行します。

Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse

例 3 - モジュールで 1 つのルールを実行する

次の使用例は、モジュール フォルダー内PSDiagnosticsのファイルに対して PSAvoidUsingPositionalParameters ルールのみを実行します。 このようなコマンドを使用して、特定のルール違反のすべてのインスタンスを検索できます。

Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters

例 4 - モジュールで 2 つを除くすべてのルールを実行する

この例では、 ディレクトリとそのサブディレクトリの ファイルと .psm1 ファイルで PSAvoidUsingCmdletAliases と PSAvoidUsingInternalURLs を.ps1除くすべての規則をMyModules実行します。

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

例 5 - カスタム 規則を使用してスクリプト アナライザーを実行する

この例では、パス内の標準の規則と規則を使用して、Script Analyzer を C:\CommunityAnalyzerRules でTest-Script.ps1実行します。

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

2 番目のコマンドでは、 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

コマンド-Severity Errorに など、競合するパラメーターをInvoke-ScriptAnalyzer含める場合、コマンドレットはプロファイル値を使用し、 パラメーターを無視します。

例 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

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

入力

None

パイプを使用してこのコマンドレットに入力を渡すことはできません。

出力

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

既定では、 Invoke-ScriptAnalyzer はルール違反ごとに 1 つの DiagnosticRecord オブジェクトを返します。

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

SuppressedOnly パラメーターを使用する場合は、Invoke-ScriptAnalyzer代わりに SuppressedRecord オブジェクトを返します。

関連リンク

• Get-ScriptAnalyzerRule
• GitHub の PSScriptAnalyzer