Invoke-ScriptAnalyzer

Referência

Módulo:: PSScriptAnalyzer

Avalia um script ou módulo com base nas regras de práticas recomendadas selecionadas

Sintaxe

Invoke-ScriptAnalyzer
      [-Path] <string>
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-SuppressedOnly]
      [-Fix]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]

Invoke-ScriptAnalyzer
      [-Path] <string>
      -IncludeSuppressed
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-Fix]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]

Invoke-ScriptAnalyzer
      [-ScriptDefinition] <string>
      -IncludeSuppressed
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]

Invoke-ScriptAnalyzer
      [-ScriptDefinition] <string>
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-SuppressedOnly]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]

Description

Invoke-ScriptAnalyzer avalia scripts ou arquivos de módulo (.ps1, .psm1e .psd1 arquivos) com base em uma coleção de regras de práticas recomendadas e retorna objetos que representam violações de regra. Ele também inclui regras especiais para analisar recursos de DSC.

Invoke-ScriptAnalyzer vem com um conjunto de regras internas. Por padrão, ele usa todas as regras. Você pode usar os parâmetros IncludeRule e ExcludeRule para selecionar as regras desejadas. Você pode usar o Get-ScriptAnalyzerRule cmdlet para examinar e selecionar as regras que deseja incluir ou excluir da avaliação.

Você também pode usar regras personalizadas que você escreve em scripts do PowerShell ou compilar em assemblies usando C#. As regras personalizadas também podem ser selecionadas usando os parâmetros IncludeRule e ExcludeRule .

Você também pode incluir uma regra na análise, mas suprimir a saída dessa regra para funções ou scripts selecionados. Esse recurso deve ser usado somente quando necessário. Para obter regras que foram suprimidas, execute Invoke-ScriptAnalyzer com o parâmetro SuppressedOnly .

Para uso em sistemas de CI, EnableExit sai do shell com um código de saída igual ao número de registros de erro.

Exemplos

EXEMPLO 1 – Executar todas as regras do Analisador de Script em um script

Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1

EXEMPLO 2 – Executar todas as regras do Analisador de Script em todos os arquivos no diretório Módulos

Este exemplo executa todas as regras do Analisador de Script em todos os .ps1 arquivos e .psm1 em seu diretório baseado no Modules usuário e em seus subdiretórios.

Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse

EXEMPLO 3 – Executar uma única regra em um módulo

Este exemplo executa apenas a regra PSAvoidUsingPositionalParameters nos arquivos na pasta do PSDiagnostics módulo. Você pode usar um comando como este para localizar todas as instâncias de uma violação de regra específica.

Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters

EXEMPLO 4 – Executar todas as regras, exceto duas em seus módulos

Este exemplo executa todas as regras, exceto PSAvoidUsingCmdletAliases e PSAvoidUsingInternalURLs nos .ps1 arquivos e .psm1 no MyModules diretório e em seus subdiretórios.

Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs

EXEMPLO 5 – Executar o Analisador de Script com regras personalizadas

Este exemplo executa o Analisador de Script em Test-Script.ps1 com as regras e regras padrão no C:\CommunityAnalyzerRules caminho.

Invoke-ScriptAnalyzer -Path D:\test_scripts\Test-Script.ps1 -CustomRulePath C:\CommunityAnalyzerRules -IncludeDefaultRules

EXEMPLO 6 – Executar apenas as regras que são Severidade do erro e que têm o nome de origem PSDSC

$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse

EXEMPLO 7 – Suprimir violações de regra

Este exemplo mostra como suprimir o relatório de violações de regra em uma função e como descobrir violações de regra suprimidas.

O exemplo usa o SuppressMessageAttribute atributo para suprimir as regras PSUseSingularNouns e PSAvoidUsingCmdletAliases para a Get-Widgets função no Get-Widgets.ps1 script. Você pode usar esse atributo para suprimir uma regra para um módulo, script, classe, função, parâmetro ou linha.

O primeiro comando executa o Analisador de Script no arquivo de script que contém a função . A saída relata uma violação de regra. Embora mais regras sejam violadas, nenhuma regra suprimida é relatada.

function Get-Widgets
{
    [CmdletBinding()]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "", Justification="Resolution in progress.")]
    Param()

    dir $pshome
    ...
}

Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1

RuleName                            Severity     FileName   Line  Message
--------                            --------     --------   ----  -------
PSProvideCommentHelp                Information  ManageProf 14    The cmdlet 'Get-Widget' does not have a help comment.
                                                 iles.psm1

Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly

Rule Name                           Severity     File Name  Line  Justification
---------                           --------     ---------  ----  -------------
PSAvoidUsingCmdletAliases           Warning      ManageProf 21    Resolution in progress.
                                                 iles.psm1
PSUseSingularNouns                  Warning      ManageProf 14
                                                 iles.psm1

O segundo comando usa o parâmetro SuppressedOnly para relatar violações das regras suprimidas do arquivo de script.

EXEMPLO 8 – Analisar arquivos de script usando uma definição de perfil

Neste exemplo, criamos um perfil do Analisador de Script e o ScriptAnalyzerProfile.txt salvamos no arquivo no diretório atual. Invoke-ScriptAnalyzer Executamos nos arquivos de módulo do BitLocker. O valor do parâmetro Profile é o caminho para o perfil do Analisador de Script.

# In .\ScriptAnalyzerProfile.txt
@{
    Severity = @('Error', 'Warning')
    IncludeRules = 'PSAvoid*'
    ExcludeRules = '*WriteHost'
}

Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Profile .\ScriptAnalyzerProfile.txt

Se você incluir um parâmetro conflitante no Invoke-ScriptAnalyzer comando, como -Severity Error, o cmdlet usará o valor do perfil e ignorará o parâmetro .

EXEMPLO 9 – Analisar um script armazenado como uma cadeia de caracteres

Este exemplo usa o parâmetro ScriptDefinition para analisar uma função na linha de comando. A cadeia de caracteres de função está entre aspas.

Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello'}"

RuleName                            Severity     FileName   Line  Message
--------                            --------     --------   ----  -------
PSAvoidUsingWriteHost               Warning                 1     Script
                                                                  because
                                                                  there i
                                                                  suppres
                                                                  Write-O
PSUseSingularNouns                  Warning                 1     The cmd
                                                                  noun sh

Quando você usa o parâmetro ScriptDefinition , a propriedade FileName do objeto DiagnosticRecord é $null.

Parâmetros

-Confirm

Solicita sua confirmação antes de executar o cmdlet.

Tipo:	SwitchParameter
Aliases:	cf
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-CustomRulePath

Insira o caminho para um arquivo que define regras ou um diretório que contém arquivos que definem regras. Há suporte para caracteres curinga. Quando CustomRulePath é especificado, somente as regras personalizadas encontradas nos caminhos especificados são usadas para a análise. Se Invoke-ScriptAnalyzer não for possível encontrar regras no , ele executará as regras padrão sem aviso prévio.

Para adicionar regras definidas em subdiretórios do caminho, use o parâmetro RecurseCustomRulePath . Para incluir as regras internas, adicione o parâmetro IncludeDefaultRules .

Tipo:	String[]
Aliases:	CustomizedRulePath
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	True

-EnableExit

Após a conclusão da análise, esse parâmetro sai das sessões do PowerShell e retorna um código de saída igual ao número de registros de erro. Isso pode ser útil no pipeline de CI (integração contínua).

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ExcludeRule

Omite as regras especificadas do teste do Analisador de Script. Há suporte para caracteres curinga.

Insira uma lista separada por vírgulas de nomes de regra, uma variável que contém nomes de regra ou um comando que obtém nomes de regra. Você também pode especificar uma lista de regras excluídas em um arquivo de perfil do Analisador de Script. Você pode excluir regras e regras padrão em um caminho de regra personalizado.

Quando você exclui uma regra, a regra não é executada em nenhum dos arquivos no caminho. Para excluir uma regra em uma determinada linha, parâmetro, função, script ou classe, ajuste o parâmetro Path ou suprima a regra. Para obter informações sobre como suprimir uma regra, consulte os exemplos.

Se uma regra for especificada nas coleções ExcludeRule e IncludeRule , a regra será excluída.

Tipo:	String[]
Cargo:	Named
Valor padrão:	All rules are included.
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	True

-Fix

Corrige determinados avisos que contêm uma correção em seu DiagnosticRecord.

Quando você usou Corrigir, Invoke-ScriptAnalyzer aplica as correções antes de executar a análise. Verifique se você tem um backup de seus arquivos ao usar esse parâmetro. Ele tenta preservar a codificação de arquivo, mas ainda há alguns casos em que a codificação pode ser alterada.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-IncludeDefaultRules

Invoque regras padrão junto com regras personalizadas.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-IncludeRule

Executa apenas as regras especificadas no teste do Analisador de Script. Por padrão, o PSScriptAnalyzer executa todas as regras.

Insira uma lista separada por vírgulas de nomes de regra, uma variável que contém nomes de regra ou um comando que obtém nomes de regra. Há suporte para caracteres curinga. Você também pode especificar nomes de regra em um arquivo de perfil do Analisador de Script.

Ao usar o parâmetro CustomizedRulePath , você pode usar esse parâmetro para incluir regras e regras padrão nos caminhos de regra personalizados.

Se uma regra for especificada nas coleções ExcludeRule e IncludeRule , a regra será excluída.

O parâmetro Severity tem precedência sobre IncludeRule. Por exemplo, se Severidade for Error, você não poderá usar IncludeRule para incluir uma Warning regra.

Tipo:	String[]
Cargo:	Named
Valor padrão:	All rules are included.
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	True

-IncludeSuppressed

Inclua diagnóstico suprimidas na saída.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	True
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Path

Especifica o caminho para os scripts ou módulo a serem analisados. Há suporte para caracteres curinga.

Insira o caminho para um script (.ps1) ou arquivo de módulo (.psm1) ou para um diretório que contém scripts ou módulos. Se o diretório contiver outros tipos de arquivos, eles serão ignorados.

Para analisar arquivos que não estão no diretório raiz do caminho especificado, use um caractere curinga (C:\Modules\MyModule\*) ou o parâmetro Recurse .

Tipo:	String
Aliases:	PSPath
Cargo:	0
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	True

-Recurse

Executa o Analisador de Script nos arquivos no diretório Path e em todos os subdiretórios recursivamente.

Recurse aplica-se somente ao valor do parâmetro Path. Para pesquisar o CustomRulePath recursivamente, use o parâmetro RecurseCustomRulePath .

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-RecurseCustomRulePath

Adiciona regras definidas em subdiretórios do local CustomRulePath . Por padrão, Invoke-ScriptAnalyzer usa apenas as regras personalizadas definidas no arquivo ou diretório especificado. Para incluir as regras internas, use o parâmetro IncludeDefaultRules .

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ReportSummary

Escreva um resumo das violações encontradas no host.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-SaveDscDependency

Resolver dependências de recursos de DSC.

Quando Invoke-ScriptAnalyzer é executado com esse parâmetro, ele procura instâncias de Import-DSCResource -ModuleName <somemodule>. Se <somemodule> não for possível encontrar pesquisando o , Invoke-ScriptAnalyzer retornará o $env:PSModulePatherro de análise. Esse erro é causado pelo analisador do PowerShell não conseguir localizar o símbolo para <somemodule>.

Se Invoke-ScriptAnalyzer encontrar o módulo no Galeria do PowerShell, ele baixará o módulo ausente para um caminho temporário. Em seguida, o caminho temporário é adicionado a $env:PSModulePath durante a verificação. O local temporário pode ser encontrado em $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ScriptDefinition

Executa a análise em comandos, funções ou expressões em uma cadeia de caracteres. Você pode usar esse recurso para analisar instruções, expressões e funções, independentemente do contexto de script.

Tipo:	String
Cargo:	0
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-Settings

Um caminho para um arquivo que contém um perfil definido pelo usuário ou um objeto hashtable que contém configurações para ScriptAnalyzer.

É executado Invoke-ScriptAnalyzer com os parâmetros e valores especificados no arquivo ou hashtable.

Se o caminho ou o conteúdo do arquivo ou hashtable for inválido, ele será ignorado. Os parâmetros e valores no perfil têm precedência sobre o mesmo parâmetro e valores especificados na linha de comando.

Um arquivo de perfil do Analisador de Script é um arquivo de texto que contém um hashtable com uma ou mais das seguintes chaves:

CustomRulePath
ExcludeRules
IncludeDefaultRules
IncludeRules
RecurseCustomRulePath
Regras
Severidade

As chaves e os valores no perfil são interpretados como se fossem parâmetros padrão e valores de Invoke-ScriptAnalyzer, semelhantes ao splatting. Para obter mais informações, consulte about_Splatting.

Tipo:	Object
Aliases:	Profile
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Severity

Depois de executar o Analisador de Script com todas as regras, esse parâmetro seleciona violações de regra com a gravidade especificada.

Os valores válidos são:

Erro
Aviso
Informações.

Você pode especificar um minério mais valores de severidade.

O parâmetro filtra as violações de regras somente depois de executar todas as regras. Para filtrar regras com eficiência, use Get-ScriptAnalyzerRule para selecionar as regras que você deseja executar.

O parâmetro Severity tem precedência sobre IncludeRule. Por exemplo, se Severidade for Error, você não poderá usar IncludeRule para incluir uma Warning regra.

Tipo:	String[]
Cargo:	Named
Valor padrão:	All rule violations
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-SuppressedOnly

Retorna violações somente para regras suprimidas.

Retorna um objeto SuppressedRecord (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord).

Para suprimir uma regra, use SuppressMessageAttribute. Para obter ajuda, consulte os exemplos.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Tipo:	SwitchParameter
Aliases:	wi
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

Entradas

None

Não é possível redirecionar a entrada para este cmdlet.

Saídas

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

Por padrão, Invoke-ScriptAnalyzer retorna um objeto DiagnosticRecord para cada violação de regra.

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

Se você usar o parâmetro SuppressedOnly , Invoke-ScriptAnalyzer retornará um objeto SuppressedRecord .

Compartilhar via

Invoke-ScriptAnalyzer

Sintaxe

Description

Exemplos

EXEMPLO 1 – Executar todas as regras do Analisador de Script em um script

EXEMPLO 2 – Executar todas as regras do Analisador de Script em todos os arquivos no diretório Módulos

EXEMPLO 3 – Executar uma única regra em um módulo

EXEMPLO 4 – Executar todas as regras, exceto duas em seus módulos

EXEMPLO 5 – Executar o Analisador de Script com regras personalizadas

EXEMPLO 6 – Executar apenas as regras que são Severidade do erro e que têm o nome de origem PSDSC

EXEMPLO 7 – Suprimir violações de regra

EXEMPLO 8 – Analisar arquivos de script usando uma definição de perfil

EXEMPLO 9 – Analisar um script armazenado como uma cadeia de caracteres

Parâmetros

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Entradas

Saídas

Recursos adicionais

Compartilhar via

Invoke-ScriptAnalyzer

Sintaxe

Description

Exemplos

EXEMPLO 1 – Executar todas as regras do Analisador de Script em um script

EXEMPLO 2 – Executar todas as regras do Analisador de Script em todos os arquivos no diretório Módulos

EXEMPLO 3 – Executar uma única regra em um módulo

EXEMPLO 4 – Executar todas as regras, exceto duas em seus módulos

EXEMPLO 5 – Executar o Analisador de Script com regras personalizadas

EXEMPLO 6 – Executar apenas as regras que são Severidade do erro e que têm o nome de origem PSDSC

EXEMPLO 7 – Suprimir violações de regra

EXEMPLO 8 – Analisar arquivos de script usando uma definição de perfil

EXEMPLO 9 – Analisar um script armazenado como uma cadeia de caracteres

Parâmetros

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Entradas

Saídas

Links Relacionados

Recursos adicionais