Uso di PSScriptAnalyzer

Questo articolo descrive varie funzionalità di PSScriptAnalyzer e come usarle.

Errori del parser

A partire dalla versione 1.18.0, PSScriptAnalyzer genera errori del parser come record di diagnostica nel flusso di output.

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 è impostato su ErrorId dell'errore del parser.

Per eliminare ParseErrors, non includerlo come valore nel parametro 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.

Soppressione delle regole

È possibile eliminare una regola decorando uno script, una funzione o un parametro con . SuppressMessageAttribute di NET. Il costruttore per SuppressMessageAttribute accetta due parametri: una categoria e un ID controllo. Impostare il parametro categoryID sul nome della regola che si desidera eliminare e impostare il parametro checkID su una stringa vuota o null. Facoltativamente, è possibile aggiungere un terzo parametro denominato con una giustificazione per l'eliminazione del messaggio:

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

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

}

Nell'ambito dello script, della funzione o del parametro decorato, tutte le violazioni delle regole vengono eliminate.

Per eliminare un messaggio su un parametro specifico, impostare il parametro CheckId di SuppressMessageAttribute sul nome del parametro:

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

Utilizzare la proprietà Scope di SuppressMessageAttribute per limitare l'eliminazione delle regole alle funzioni o alle classi all'interno dell'ambito dell'attributo.

Utilizzare il valore Funzione per eliminare le violazioni in tutte le funzioni all'interno dell'ambito dell'attributo. Utilizzare il valore Class per eliminare le violazioni in tutte le classi all'interno dell'ambito dell'attributo:

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

function InternalFunction
{
    param()

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

Puoi ulteriormente limitare la soppressione in base al nome di una funzione, parametro, classe, variabile o oggetto impostando la proprietà Target di SuppressMessageAttribute su un'espressione regolare o un modello jolly.

Ad esempio, per eliminare la violazione della regola PSAvoidUsingWriteHost in start-bar e start-baz ma non in start-foo e 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"
}

Per eliminare le violazioni in tutte le funzioni:

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

Per eliminare le violazioni in start-bar, start-baz ma start-bam non in start-foo:

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

Annotazioni

Gli errori del parser non possono essere eliminati con SuppressMessageAttribute.

Supporto delle impostazioni in ScriptAnalyzer

È possibile creare impostazioni che descrivono le regole di ScriptAnalyzer da includere o escludere in base alla gravità. Utilizzare il parametro Settings di Invoke-ScriptAnalyzer per specificare la configurazione. Il parametro Impostazioni ti permette di creare una configurazione personalizzata per un ambiente specifico.

Questo parametro accetta i seguenti tipi di oggetti:

  • Un percorso verso un .psd1 file contenente un profilo definito dall'utente
  • Un oggetto hashtable contenente impostazioni
  • Il nome di un preset integrato

Preset integrati

ScriptAnalyzer fornisce un set di preimpostazioni predefinite che possono essere utilizzate per analizzare gli script. Il modulo PSScriptAnalyzer include un insieme di preset integrati che puoi usare con il parametro Settings . Ad esempio, se si desidera eseguire le regole di PowerShell Gallery nel modulo, usare il comando seguente:

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

Puoi specificare più preset separandoli con una virgola. Puoi usare il completamento delle schede per vedere i preset disponibili. I preset integrati sono memorizzati nella Settings cartella del modulo PSScriptAnalyzer . Puoi elencare i preset integrati eseguendo il seguente comando:

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

Per vedere le regole incluse in un preset, puoi aprire il .psd1 file in un editor di testo.

Explicit

Il seguente esempio mostra come invocare Script Analyzer con impostazioni che escludono due regole dal set predefinito di regole e qualsiasi regola con gravità diversa da Errore e Avviso.

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

Potresti anche salvare quell'hashtable in un .psd1 file e poi invocare Script Analyzer con quel file di impostazioni.

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

Se si inserisce un file di impostazioni denominato PSScriptAnalyzerSettings.psd1 nella radice del progetto, PSScriptAnalyzer lo individua quando si passa la radice del progetto come parametro Path .

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

Fornire impostazioni esplicitamente ha una priorità maggiore rispetto a questa modalità implicita. Puoi trovare file di esempio impostazioni nella Settings cartella del modulo PSScriptAnalyzer .

Verificare la compatibilità della versione di PowerShell

PSScriptAnalyzer può verificare la presenza di incompatibilità negli script di PowerShell con altre versioni e ambienti di PowerShell. PSScriptAnalyzer include quattro regole che verificano la presenza di problemi di compatibilità:

  • PSUseCompatibleCmdlets controlla se i cmdlet utilizzati in uno script sono disponibili in altri ambienti PowerShell
  • PSUseCompatibleCommands controlla se i comandi utilizzati in uno script sono disponibili in altri ambienti PowerShell
  • PSUseCompatibleSyntax verifica se una sintassi usata in uno script è compatibile in altre versioni di PowerShell
  • PSUseCompatibleTypes controlla se i tipi .NET e i metodi o le proprietà statici sono disponibili in altri ambienti PowerShell

Per altre informazioni su come usare queste regole, vedere Uso di PSScriptAnalyzer per verificare la compatibilità della versione di PowerShell nel blog del team di PowerShell.

Regole personalizzate

È possibile fornire uno o più percorsi alle regole personalizzate nel file delle impostazioni. È importante che questi percorsi puntino alla cartella di un modulo, che usa in modo implicito il manifesto del modulo, o al file di script del modulo (.psm1). Il modulo deve esportare le funzioni delle regole personalizzate per Export-ModuleMember renderle disponibili per PSScriptAnalyzer.

In questo esempio, la proprietà CustomRulePath indica due moduli diversi. Entrambi i moduli esportano le funzioni della regola con il verbo Measure , quindi Measure-* viene utilizzato per la proprietà IncludeRules.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

È inoltre possibile aggiungere regole predefinite elencandole nella proprietà IncludeRules . Quando si includono le regole predefinite, è importante impostare la proprietà IncludeDefaultRules su $true; in caso contrario, vengono utilizzate le regole predefinite.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Utilizzo di regole personalizzate in Visual Studio Code (VS Code)

Puoi anche usare le regole personalizzate fornite nel file delle impostazioni in VS Code. Aggiungi un file di impostazioni dell'area di lavoro VS Code (.vscode/settings.json) con i seguenti contenuti.

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

ScriptAnalyzer come libreria .NET

È possibile utilizzare direttamente il motore e le funzionalità di ScriptAnalyzer come libreria.

Di seguito sono riportate le interfacce pubbliche:

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)

Correzione delle violazioni

Puoi usare l'interruttore Fix per sostituire automaticamente i contenuti che causano violazioni con un'alternativa suggerita. Inoltre, poiché Invoke-ScriptAnalyzer implementa SupportsShouldProcess, è possibile utilizzare WhatIf o Confirm per individuare le correzioni da applicare. Dovresti usare il controllo del contenuto durante le correzioni, poiché alcune modifiche, come quella per EvitareUsingPlainTextForPassword, potrebbero richiedere altre modifiche agli script che non possono essere fatte automaticamente. La codifica iniziale non può sempre essere preservata quando applichi automaticamente i suggerimenti. Dovresti controllare la codifica dei file se i tuoi script dipendono da una codifica particolare.

La proprietà SuggestedCorrections del record errore consente scenari di correzione rapida in editor come VS Code. Forniamo SuggestedCorrection valido per le seguenti regole:

  • AvoidAlias
  • AvoidUsingPlainTextForPassword
  • Backtick fuorviante
  • Campo manifesto ModuloMancante
  • UseToExportFieldsInManifest
  • Last updated on