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í. ScriptAnalyzer podporuje následující režimy pro specifikaci souboru nastavení:

Vestavěné předvolby

ScriptAnalyzer dodává sadu vestavěných předvoleb, které lze použít k analýze skriptů. 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

Kromě toho můžete použít další vestavěná přednastavení, včetně DSC a CodeFormatting. Tyto předvolby lze doplnit tabulátorem pro parametr Nastavení .

Explicitní

Následující příklad vyloučí dvě pravidla z výchozí sady pravidel a všechna pravidla s jinou závažností než Error a Warning.

# PSScriptAnalyzerSettings.psd1
@{
    Severity=@('Error','Warning')
    ExcludeRules=@('PSAvoidUsingCmdletAliases', 'PSAvoidUsingWriteHost')
}

Tento soubor nastavení pak můžete vyvolat pomocí Invoke-ScriptAnalyzer:

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

Následující příklad vybere několik pravidel, která se mají provést namísto všech výchozích pravidel.

# PSScriptAnalyzerSettings.psd1
@{
    IncludeRules=@('PSAvoidUsingPlainTextForPassword',
                'PSAvoidUsingConvertToSecureStringWithPlainText')
}

Poté můžete tento soubor nastavení vyvolat:

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

Implicit

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-01-29