Använda PSScriptAnalyzer

I den här artikeln beskrivs olika funktioner i PSScriptAnalyzer och hur du använder dem.

Parserfel

Från och med version 1.18.0 genererar PSScriptAnalyzer parserfel som diagnostikposter i utdataströmmen.

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 är inställt på ErrorId för parserfelet.

Om du vill ignorera ParseErrors ska du inte ta med det som ett värde i parametern Allvarlighetsgrad .

$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.

Ignorera regler

Du kan ignorera en regel genom att dekorera ett skript, en funktion eller en parameter med . NET:s SuppressMessageAttribute. Konstruktorn för SuppressMessageAttribute tar två parametrar: en kategori och ett kontroll-ID. Ange parametern categoryID till namnet på den regel som du vill ignorera och ange parametern checkID till en null eller tom sträng. Du kan också lägga till en tredje namngiven parameter med en motivering för att ignorera meddelandet:

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

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

}

Inom omfånget för skriptet, funktionen eller parametern som du har skapat ignoreras alla regelöverträdelser.

Om du vill ignorera ett meddelande för en specifik parameter anger du parametern CheckId för SuppressMessageAttribute till namnet på parametern:

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

Använd egenskapen Scope för SuppressMessageAttribute för att begränsa regelundertryckning till funktioner eller klasser inom attributets omfång.

Använd värdet Function för att förhindra överträdelser av alla funktioner inom attributets omfång. Använd värdet Class för att förhindra överträdelser av alla klasser inom attributets omfång:

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

function InternalFunction
{
    param()

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

Du kan ytterligare begränsa suppression baserat på namnet på en funktion, parameter, klass, variabel eller objekt genom att sätta Target-egenskapen i SuppressMessageAttribute till ett reguljärt uttryck eller ett wildcard-mönster.

Om du till exempel vill förhindra regelöverträdelsen PSAvoidUsingWriteHost i start-bar och men start-baz inte i start-foo och 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"
}

Så här stävjar du överträdelser i alla funktioner:

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

För att stävja överträdelser i start-bar, start-baz och start-bam men inte i start-foo:

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

Anmärkning

Parserfel kan inte ignoreras med SuppressMessageAttribute.

Stöd för inställningar i ScriptAnalyzer

Du kan skapa inställningar som beskriver de ScriptAnalyzer-regler som ska inkluderas eller exkluderas baserat på allvarlighetsgrad. Använd parametern Invoke-ScriptAnalyzer för för att ange konfiguration. Inställningsparametern låter dig skapa en anpassad konfiguration för en specifik miljö.

Denna parameter accepterar följande typer av objekt:

  • En väg till en .psd1 fil som innehåller en användardefinierad profil
  • Ett hashtabellobjekt som innehåller inställningar
  • Namnet på en inbyggd förinställning

Inbyggda förinställningar

ScriptAnalyzer levereras en uppsättning inbyggda förinställningar som kan användas för att analysera skript. PSScriptAnalyzer-modulen innehåller en uppsättning inbyggda förinställningar som du kan använda med inställningsparametern . Om du till exempel vill köra PowerShell-galleriet regler i modulen använder du följande kommando:

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

Du kan ange flera presets genom att separera dem med en kommatecken. Du kan använda tabb-komplettering för att se tillgängliga förinställningar. De inbyggda förinställningarna lagras i Settings mappen för PSScriptAnalyzer-modulen . Du kan lista de inbyggda förinställningarna genom att köra följande kommando:

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

För att se reglerna som ingår i en förinställning kan du öppna .psd1 filen i en textredigerare.

Explicit

Följande exempel visar hur man anropar Script Analyzer med inställningar som utesluter två regler från standarduppsättningen av regler och alla regler med en annan allvarlighetsgrad än Fel och Varning.

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

Du kan också spara den hashtabellen i en .psd1 fil och sedan starta Script Analyzer med den inställningsfilen.

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

Om du placerar en inställningsfil med namnet PSScriptAnalyzerSettings.psd1 i projektroten identifierar PSScriptAnalyzer den när du skickar projektroten som sökvägsparameter .

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

Att tillhandahålla inställningar har uttryckligen högre prioritet än detta implicita läge. Du kan hitta exempelinställningar i Settings mappen för PSScriptAnalyzer-modulen .

Kontrollera kompatibilitet för PowerShell-version

PSScriptAnalyzer kan kontrollera PowerShell-skript för inkompatibiliteter med andra PowerShell-versioner och miljöer. PSScriptAnalyzer innehåller fyra regler som söker efter kompatibilitetsproblem:

Mer information om hur du använder dessa regler finns i Använda PSScriptAnalyzer för att kontrollera kompatibilitet för PowerShell-version på PowerShell-teamets blogg.

Anpassade regler

Det är möjligt att ange en eller flera sökvägar till anpassade regler i inställningsfilen. Det är viktigt att dessa sökvägar pekar antingen på en moduls mapp, som implicit använder modulmanifestet, eller på modulens skriptfil (.psm1). Modulen måste exportera de anpassade regelfunktionerna som används Export-ModuleMember för att de ska vara tillgängliga för PSScriptAnalyzer.

I detta exempel pekar egenskapen CustomRulePath på två olika moduler. Båda modulerna exporterar regelfunktionerna med verbet Measure so Measure-* används för egenskapen IncludeRules.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

Du kan också lägga till standardregler genom att visa reglerna i egenskapen IncludeRules . När du inkluderar standardregler är det viktigt att du anger egenskapen IncludeDefaultRules till $true, annars används standardreglerna.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Att använda anpassade regler i Visual Studio Code (VS Code)

Du kan också använda de anpassade reglerna som finns i inställningsfilen i VS Code. Lägg till en VS Code-arbetsytsinställningsfil (.vscode/settings.json) med följande innehåll.

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

ScriptAnalyzer som ett .

Du kan använda ScriptAnalyzers motor och funktioner direkt som ett bibliotek.

Här är de offentliga gränssnitten:

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)

Korrigering av överträdelser

Du kan använda Fix-switchen för att automatiskt ersätta innehåll som orsakar överträdelser mot ett föreslaget alternativ. Eftersom Invoke-ScriptAnalyzerSupportsShouldProcess implementeras kan du dessutom använda WhatIf eller Confirm för att ta reda på vilka korrigeringar som ska tillämpas. Du bör använda versionshantering när du applicerar korrigeringar eftersom vissa ändringar, som den för AvoidUsingPlainTextForPassword, kan kräva andra skriptändringar som inte kan göras automatiskt. Initial kodning kan inte alltid bevaras när du automatiskt tillämpar förslag. Du bör kontrollera filkodning om dina skript är beroende av en viss kodning.

Egenskapen SuggestedCorrections i felposten möjliggör snabbfix-scenarier i redigerare som VS Code. Vi tillhandahåller giltig SuggestedCorrection för följande regler:

  • UndvikaAlias
  • Undvik att använda PlainTextForPassword
  • VilseledandeBacktick
  • MissingModuleManifestField (på engelska)
  • UseToExportFieldsInManifest
  • Uppdaterades senast