Compartilhar via

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

Suprimindo regras

Você pode suprimir uma regra decorando um script, função ou parâmetro com . NET 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 regra 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!"
}

Você pode restringir ainda mais a supressão com base no nome de uma função, parâmetro, classe, variável ou objeto definindo a propriedade Target do SuppressMessageAttribute para uma expressão regular ou um padrão de curinga.

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 suprimir violações em start-bar, start-baz e start-bam não em start-foo:

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

Observação

Os erros do analisador não podem ser suprimidos com SuppressMessageAttribute.

Suporte a configurações no ScriptAnalyzer

Você pode criar configurações que descrevem as regras do ScriptAnalyzer a serem incluídas ou excluídas com base na Gravidade. Use o parâmetro Settings de Invoke-ScriptAnalyzer para especificar a configuração. O parâmetro Configurações permite criar uma configuração personalizada para um ambiente específico. O ScriptAnalyzer suporta os seguintes modos para especificar o arquivo de configurações:

Predefinições integradas

O ScriptAnalyzer fornece um conjunto de predefinições internas que podem ser usadas para analisar scripts. 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

Além disso, você pode usar outras predefinições internas, incluindo DSC e CodeFormatting. Essas predefinições podem ser preenchidas com a guia para o parâmetro Configurações .

Explicit

O exemplo a seguir exclui duas regras do conjunto padrão de regras e qualquer regra com uma gravidade diferente de Erro e Aviso.

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

Em seguida, você pode invocar esse arquivo de configurações com Invoke-ScriptAnalyzer:

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

O próximo exemplo seleciona algumas regras a serem executadas em vez de todas as regras padrão.

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

Em seguida, você pode invocar esse arquivo de configurações:

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

Implícito

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 configurações explicitamente tem prioridade maior sobre esse modo implícito. Você pode encontrar arquivos de configurações de exemplo na Settings pasta do módulo PSScriptAnalyzer .

Verificar a compatibilidade da versão do PowerShell

O PSScriptAnalyzer pode verificar se há incompatibilidades de scripts do PowerShell com outras versões e ambientes do PowerShell. O PSScriptAnalyzer inclui quatro regras que verificam 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 em um script é compatível em outras versões do PowerShell
  • PSUseCompatibleTypes verifica se os tipos .NET e métodos ou propriedades estáticas 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 de 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 para Export-ModuleMember 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 $true; caso contrá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-*'
    )
}

Usando regras personalizadas no Visual Studio Code (VS Code)

Você também pode usar as regras personalizadas fornecidas no arquivo de configurações no VS Code. Adicione um arquivo de configuraçõ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

Você 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 o implementa SupportsShouldProcess, você pode usar WhatIf ou Confirm para descobrir quais correções seriam aplicadas. Você deve usar controle de versão ao aplicar correções, pois algumas alterações, como a de EvitarUsarTextoSimplesParaSenha, podem exigir outras modificações de script que não podem ser feitas automaticamente. A codificação inicial nem sempre pode ser preservada quando você aplica sugestões automaticamente. Você deve verificar a codificação de arquivos se seus scripts dependem de uma codificação específica.

A propriedade SuggestedCorrections do registro de erro permite cenários rápidos em editores como o VS Code. Fornecemos SuggestedCorrection válido para as seguintes regras:

  • AvoidAlias
  • EvitarUsingPlainTextForPassword
  • Acento Duvidoso
  • MissingModuleManifestField
  • UseToExportFieldsInManifest
  • Last updated on