Usando o PSScriptAnalyzer

Este artigo descreve vários recursos do PSScriptAnalyzer e como usá-los.

Erros do analisador

A partir da versão 1.18.0, o PSScriptAnalyzer emite erros do analisador como registros de diagnóstico no fluxo de saída.

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.

O RuleName é definido como o ErrorId do erro do analisador.

Para suprimir ParseErrors, não o inclua como um valor no parâmetro 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.

Supressão de regras

Você pode suprimir uma regra decorando um script, função ou parâmetro com . NET's SuppressMessageAttribute. O construtor de SuppressMessageAttribute usa dois parâmetros: uma categoria e uma ID de verificação. Defina o parâmetro categoryID como o nome da regra que você deseja suprimir e defina o parâmetro checkID como uma cadeia de caracteres nula ou vazia. Opcionalmente, você pode adicionar um terceiro parâmetro nomeado com uma justificativa para suprimir a mensagem:

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

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

}

Dentro do escopo do script, função ou parâmetro que você decorou, todas as violações de regras são suprimidas.

Para suprimir uma mensagem em um parâmetro específico, defina o parâmetro CheckId de SuppressMessageAttribute como o nome do parâmetro:

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

Use a propriedade Scope de SuppressMessageAttribute para limitar a supressão de regras a funções ou classes dentro do escopo do atributo.

Use o valor Function para suprimir violações em todas as funções dentro do escopo do atributo. Use o valor Class para suprimir violações em todas as classes dentro do escopo do atributo:

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

function InternalFunction
{
    param()

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

Pode ainda restringir a supressão com base numa função, parâmetro, classe, variável ou nome de objeto, definindo a propriedade Target do SuppressMessageAttribute para uma expressão regular ou um padrão de wildcard.

Por exemplo, para suprimir a violação da regra PSAvoidUsingWriteHost em start-bar e start-baz mas não em 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"
}

Para suprimir violações em todas as funções:

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

Para reprimir violações em start-bar, start-baz e start-bam mas não em start-foo:

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

Suporte a configurações no ScriptAnalyzer

Você pode criar configurações que descrevam as regras do ScriptAnalyzer para incluir ou excluir com base na gravidade. Use o parâmetro Settings de Invoke-ScriptAnalyzer para especificar a configuração. O parâmetro Definições permite-lhe criar uma configuração personalizada para um ambiente específico.

Este parâmetro aceita os seguintes tipos de objetos:

• Um caminho para um .psd1 ficheiro que contém um perfil definido pelo utilizador
• Um objeto de hashtable que contém definições
• O nome de um preset incorporado

Predefinições incorporadas

O ScriptAnalyzer fornece um conjunto de predefinições internas que podem ser usadas para analisar scripts. O módulo PSScriptAnalyzer inclui um conjunto de predefinições incorporadas que pode usar com o parâmetro Settings . Por exemplo, se você quiser executar regras da Galeria do PowerShell em seu módulo, use o seguinte comando:

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

Podes especificar vários presets separando-os com uma vírgula. Podes usar a completação de tabulação para ver os predefinidos disponíveis. Os presets incorporados são armazenados na Settings pasta do módulo PSScriptAnalyzer . Pode listar os presets incorporados executando o seguinte 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

Para ver as regras incluídas num preset, pode abrir o .psd1 ficheiro num editor de texto.

Explícito

O exemplo seguinte mostra como invocar o Script Analyzer com definições que excluem duas regras do conjunto padrão de regras e qualquer regra com gravidade diferente de Erro e Aviso.

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

Também podes guardar essa hashtable num .psd1 ficheiro e depois invocar o Script Analyzer com esse ficheiro de definições.

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

Pesquisa implícita

Se você colocar um arquivo de configurações nomeado PSScriptAnalyzerSettings.psd1 na raiz do projeto, o PSScriptAnalyzer o descobrirá quando você passar a raiz do projeto como o parâmetro Path .

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

Fornecer definições explicitamente tem maior prioridade sobre este modo implícito. Pode encontrar ficheiros de exemplos de definições na Settings pasta do módulo PSScriptAnalyzer .

Verificar a compatibilidade da versão do PowerShell

O PSScriptAnalyzer pode verificar se há incompatibilidades nos scripts do PowerShell com outras versões e ambientes do PowerShell. O PSScriptAnalyzer inclui quatro regras que verificam se há problemas de compatibilidade:

• PSUseCompatibleCmdlets verifica se os cmdlets usados em um script estão disponíveis em outros ambientes do PowerShell
• PSUseCompatibleCommands verifica se os comandos usados em um script estão disponíveis em outros ambientes do PowerShell
• PSUseCompatibleSyntax verifica se uma sintaxe usada num script é compatível noutras versões do PowerShell
• PSUseCompatibleTypes verifica se tipos .NET e métodos estáticos ou propriedades estão disponíveis em outros ambientes do PowerShell

Para obter mais informações sobre como usar essas regras, consulte Usando o PSScriptAnalyzer para verificar a compatibilidade da versão do PowerShell no blog da Equipe do PowerShell.

Regras personalizadas

É possível fornecer um ou mais caminhos para regras personalizadas no arquivo de configurações. É importante que esses caminhos apontem para a pasta de um módulo, que usa implicitamente o manifesto do módulo, ou para o arquivo de script do módulo (.psm1). O módulo deve exportar as funções de regra personalizadas usando Export-ModuleMember para que elas estejam disponíveis para PSScriptAnalyzer.

Neste exemplo, a propriedade CustomRulePath aponta para dois módulos diferentes. Ambos os módulos exportam as funções de regra com o verbo Measure , portanto, Measure-* é usado para a propriedade IncludeRules.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

Você também pode adicionar regras padrão listando as regras na propriedade IncludeRules . Ao incluir regras padrão, é importante que você defina a propriedade IncludeDefaultRules como , caso $truecontrário, as regras padrão serão usadas.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Utilização de regras personalizadas no Visual Studio Code (VS Code)

Também podes usar as regras personalizadas que estão fornecidas no ficheiro de definições do VS Code. Adicione um ficheiro de definições de espaço de trabalho VS Code (.vscode/settings.json) com o seguinte conteúdo.

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

ScriptAnalyzer como uma biblioteca .NET

Você pode consumir diretamente o mecanismo e a funcionalidade do ScriptAnalyzer como uma biblioteca.

Aqui estão as interfaces públicas:

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)

Correção de Violação

Pode usar o interruptor Fix para substituir automaticamente o conteúdo que causa violações por uma alternativa sugerida. Além disso, como Invoke-ScriptAnalyzer implementa SupportsShouldProcess, você pode usar WhatIf ou Confirm para descobrir quais correções seriam aplicadas. Deves usar controlo de versões ao aplicar correções, pois algumas alterações, como a de EvitarUsarTextoSimplesParaPassword, podem exigir outras modificações de script que não podem ser feitas automaticamente. A codificação inicial nem sempre pode ser preservada quando aplicas automaticamente as sugestões. Deves verificar a codificação de ficheiros se os teus scripts dependem de uma codificação específica.

A propriedade SuggestedCorrections do registo de erro permite correções rápidas em editores como o VS Code. Fornecemos SuggestedCorrection válida para as seguintes regras:

• EvitarAlias
• AvoidUsingPlainTextForPassword
• EnganosoBacktick
• MissingModuleManifestField
• UseToExportFieldsInManifest