Použití psScriptAnalyzeru

Tento článek popisuje různé funkce jazyka PSScriptAnalyzer a způsob jejich použití.

Chyby analyzátoru

Počínaje verzí 1.18.0 generuje PSScriptAnalyzer chyby analyzátoru jako diagnostické záznamy ve výstupním datovém proudu.

Invoke-ScriptAnalyzer -ScriptDefinition '"b" = "b"; function eliminate-file () { }'

RuleName            Severity   ScriptName Line Message
--------            --------   ---------- ---- -------
InvalidLeftHandSide ParseError            1    The assignment expression isn't
                                               valid. The input to an
                                               assignment operator must be an
                                               object that's able to accept
                                               assignments, such as a variable
                                               or a property.
PSUseApprovedVerbs  Warning               1    The cmdlet 'eliminate-file' uses an
                                               unapproved verb.

RuleName je nastaven na ErrorId chyby analyzátoru.

Chcete-li potlačit chybuParseErrors, nezahrnujte ji jako hodnotu do parametru Severity .

$invokeScriptAnalyzerSplat = @{
    ScriptDefinition = '"b" = "b"; function eliminate-file () { }'
    Severity = 'Warning'
}
Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat

RuleName           Severity ScriptName Line Message
--------           -------- ---------- ---- -------
PSUseApprovedVerbs Warning             1    The cmdlet 'eliminate-file' uses an
                                            unapproved verb.

Potlačení pravidel

Pravidlo můžete potlačit tak, že skript, funkci nebo parametr ozdobíte pomocí . NET SuppressMessageAttribute. Konstruktor pro SuppressMessageAttribute přebírá dva parametry: kategorii a ID kontroly. Nastavte parametr categoryID na název pravidla, které chcete potlačit, a nastavte parametr checkID na hodnotu null nebo prázdný řetězec. Volitelně můžete přidat třetí pojmenovaný parametr s odůvodněním pro potlačení zprávy:

function SuppressMe()
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideCommentHelp', '',
        Justification='Just an example')]
    param()

    Write-Verbose -Message "I'm making a difference!"

}

V rámci skriptu, funkce nebo parametru, který jste dekorovali, jsou všechna porušení pravidel potlačena.

Chcete-li potlačit zprávu u konkrétního parametru, nastavte parametr CheckIdSuppressMessageAttribute na název parametru:

function SuppressTwoVariables()
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideDefaultParameterValue', 'b')]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideDefaultParameterValue', 'a')]
    param([string]$a, [int]$b)
    {
    }
}

Pomocí vlastnosti Scope nástroje SuppressMessageAttribute můžete omezit potlačení pravidel na funkce nebo třídy v rámci rozsahu atributu.

Pomocí hodnoty Funkce můžete potlačit porušení všech funkcí v rozsahu atributu. Hodnotu Třída použijte k potlačení porušení u všech tříd v rámci rozsahu atributu:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideCommentHelp', '', Scope='Function')]
param()

function InternalFunction
{
    param()

    Write-Verbose -Message "I am invincible!"
}

Potlačení můžete dále omezit na základě funkce – parametru, třídy, proměnné nebo objektu – nastavením vlastnosti Target v SuppressMessageAttribute na regulární výraz nebo vzor divoké karty.

Chcete-li například potlačit porušení pravidla PSAvoidUsingWriteHost v start-bar a start-baz ale ne v start-foo a start-bam:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='start-ba[rz]')]
param()
function start-foo {
    write-host "start-foo"
}

function start-bar {
    write-host "start-bar"
}

function start-baz {
    write-host "start-baz"
}

function start-bam {
    write-host "start-bam"
}

Chcete-li potlačit porušení ve všech funkcích:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='*')]
Param()

Chcete-li potlačit porušení v start-bar, start-baz a start-bam nikoli v start-foo:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='start-b*')]
Param()

Poznámka:

Chyby analyzátoru nelze potlačit pomocí SuppressMessageAttribute.

Podpora nastavení v ScriptAnalyzer

Můžete vytvořit nastavení, která popisují pravidla ScriptAnalyzer, která se mají zahrnout nebo vyloučit na základě závažnosti. Pomocí parametru Settings můžete Invoke-ScriptAnalyzer zadat konfiguraci. Parametr Nastavení vám umožní vytvořit vlastní konfiguraci pro konkrétní prostředí.

Tento parametr přijímá následující typy objektů:

  • Cesta k .psd1 souboru obsahujícímu uživatelsky definovaný profil
  • Hashtable objekt obsahující nastavení
  • Název vestavěného přednastavení

Vestavěné předvolby

ScriptAnalyzer dodává sadu vestavěných předvoleb, které lze použít k analýze skriptů. Modul PSScriptAnalyzer obsahuje sadu vestavěných přednastavení, které můžete použít s parametrem Nastavení . Pokud například chcete na svém modulu spustit pravidla Galerie prostředí PowerShell , použijte následující příkaz:

Invoke-ScriptAnalyzer -Path /path/to/module/ -Settings PSGallery -Recurse

Můžete specifikovat více přednastavení tím, že je oddělíte čárkou. Můžete použít doplňování tabulatur, abyste viděli dostupné předvolby. Vestavěné předvolby jsou uloženy ve složce Settings modulu PSScriptAnalyzer . Vestavěné přednastavení můžete vyřadit spuštěním následujícího příkazu:

Get-ChildItem "$($(Get-Module PSScriptAnalyzer).ModuleBase)\Settings\*.psd1"

    Directory: C:\Users\sewhee\Documents\PowerShell\Modules\psscriptAnalyzer\1.25.0\Settings

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           3/20/2026  6:41 PM          15025 CmdletDesign.psd1
-a---           3/20/2026  6:41 PM          16330 CodeFormatting.psd1
-a---           3/20/2026  6:41 PM          16331 CodeFormattingAllman.psd1
-a---           3/20/2026  6:41 PM          16331 CodeFormattingOTBS.psd1
-a---           3/20/2026  6:41 PM          16375 CodeFormattingStroustrup.psd1
-a---           3/20/2026  6:41 PM          14674 DSC.psd1
-a---           3/20/2026  6:41 PM          15735 PSGallery.psd1
-a---           3/20/2026  6:41 PM          15157 ScriptFunctions.psd1
-a---           3/20/2026  6:41 PM          14736 ScriptingStyle.psd1
-a---           3/20/2026  6:41 PM          14985 ScriptSecurity.psd1

Pro zobrazení pravidel v přednastavení můžete soubor otevřít .psd1 v textovém editoru.

Explicitní

Následující příklad ukazuje, jak spustit Script Analyzer s nastavením, která vylučují dvě pravidla ze výchozí sady pravidel a jakékoliv pravidlo s jinou závažností než Chyba a Varování.

$pssaSettings = @{
    Severity=@('Error','Warning')
    ExcludeRules=@('PSAvoidUsingCmdletAliases', 'PSAvoidUsingWriteHost')
}
Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings $pssaSettings

Můžete také uložit hashtable do .psd1 souboru a pak s tímto nastavením spustit Script Analyzer.

Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings PSScriptAnalyzerSettings.psd1

Pokud umístíte soubor nastavení s názvem v PSScriptAnalyzerSettings.psd1 kořenovém adresáři projektu, nástroj PSScriptAnalyzer jej zjistí, když předáte kořenový adresář projektu jako parametr Path .

Invoke-ScriptAnalyzer -Path "C:\path\to\project" -Recurse

Poskytování nastavení má explicitní přednost před tímto implicitním režimem. Ukázkové soubory nastavení najdete ve složce Settingsmodulu PSScriptAnalyzer .

Kontrola kompatibility verzí PowerShellu

PSScriptAnalyzer může kontrolovat nekompatibilitu skriptů PowerShell s jinými verzemi a prostředími PowerShellu. PSScriptAnalyzer obsahuje čtyři pravidla, která kontrolují problémy s kompatibilitou:

  • PSUseCompatibleCmdlets kontroluje, jestli jsou rutiny použité ve skriptu dostupné v jiných prostředích PowerShellu
  • PSUseCompatibleCommands kontroluje, jestli jsou příkazy použité ve skriptu dostupné v jiných prostředích PowerShellu
  • PSUseCompatibleSyntax kontroluje, zda je syntaxe použitá ve skriptu kompatibilní s jinými verzemi PowerShellu
  • PSUseCompatibleTypes kontroluje, jestli jsou typy .NET a statické metody nebo vlastnosti dostupné v jiných prostředích PowerShellu

Další informace o tom, jak používat tato pravidla, najdete v tématu Použití PSScriptAnalyzer ke kontrole kompatibility verzí PowerShellu na blogu týmu PowerShellu.

Vlastní pravidla

V souboru nastavení je možné zadat jednu nebo více cest k vlastním pravidlům. Je důležité, aby tyto cesty odkazovaly buď na složku modulu, která implicitně používá manifest modulu, nebo na soubor skriptu modulu (.psm1). Modul musí exportovat funkce vlastních pravidel pomocí Export-ModuleMember , aby byly k dispozici pro PSScriptAnalyzer.

V tomto příkladu vlastnost CustomRulePath ukazuje na dva různé moduly. Oba moduly exportují funkce pravidel pomocí příkazu Measure so se Measure-* používá pro vlastnost IncludeRules.

@{
    CustomRulePath      = @(
        '.\output\RequiredModules\DscResource.AnalyzerRules'
        '.\tests\QA\AnalyzerRules\SqlServerDsc.AnalyzerRules.psm1'
    )

    IncludeRules        = @(
        'Measure-*'
    )
}

Výchozí pravidla můžete také přidat tak, že je uvedete ve vlastnosti IncludeRules . Při zahrnutí výchozích pravidel je důležité nastavit vlastnost IncludeDefaultRules na ; $truejinak se použijí výchozí pravidla.

@{
    CustomRulePath      = @(
        '.\output\RequiredModules\DscResource.AnalyzerRules'
        '.\tests\QA\AnalyzerRules\SqlServerDsc.AnalyzerRules.psm1'
    )

    IncludeDefaultRules = $true

    IncludeRules        = @(
        # Default rules
        'PSAvoidDefaultValueForMandatoryParameter'
        'PSAvoidDefaultValueSwitchParameter'

        # Custom rules
        'Measure-*'
    )
}

Použití vlastních pravidel ve Visual Studio Code (VS Code)

Můžete také použít vlastní pravidla, která jsou k dispozici v souboru nastavení ve VS Code. Přidejte soubor nastavení pracovního prostoru VS Code (.vscode/settings.json) s následujícím obsahem.

{
    "powershell.scriptAnalysis.settingsPath": ".vscode/analyzersettings.psd1",
    "powershell.scriptAnalysis.enable": true,
}

ScriptAnalyzer jako knihovna .NET

Modul a funkce ScriptAnalyzeru můžete přímo využívat jako knihovnu.

Zde jsou veřejná rozhraní:

using Microsoft.Windows.PowerShell.ScriptAnalyzer;

public void Initialize(System.Management.Automation.Runspaces.Runspace runspace,
Microsoft.Windows.PowerShell.ScriptAnalyzer.IOutputWriter outputWriter,
[string[] customizedRulePath = null],
[string[] includeRuleNames = null],
[string[] excludeRuleNames = null],
[string[] severity = null],
[bool suppressedOnly = false],
[string profile = null])

public System.Collections.Generic.IEnumerable<DiagnosticRecord> AnalyzePath(string path,
    [bool searchRecursively = false])

public System.Collections.Generic.IEnumerable<IRule> GetRule(string[] moduleNames,
    string[] ruleNames)

Náprava porušení

Můžete použít přepínač Oprava k automatické nahrazení obsahu způsobujícího porušení doporučenou alternativou. Navíc, protože Invoke-ScriptAnalyzer implementuje SupportsShouldProcess, můžete použít WhatIf nebo Confirm ke zjištění, které opravy budou použity. Při aplikaci oprav byste měli používat správu zdrojového kódu, protože některé změny, například u AvoidUsingPlainTextForPassword, mohou vyžadovat jiné úpravy skriptů, které nelze provést automaticky. Počáteční kódování se ne vždy zachová, když automaticky aplikujete návrhy. Měl bys zkontrolovat kódování souborů, pokud tvé skripty závisí na konkrétním kódování.

Vlastnost SuggestedCorrections v chybovém záznamu umožňuje rychlé opravy v editorech jako VS Code. Poskytujeme platnou metodu SuggestedCorrection pro následující pravidla:

  • Vyhnout se alias
  • Vyhněte se použití prostého textu pro heslo
  • ZavádějícíBacktick
  • Chybějící pole manifestu modulu
  • UseToExportFieldsInManifest
  • Last updated on