Invoke-ScriptAnalyzer

Referência

Módulo:: PSScriptAnalyzer

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

Syntax

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 ficheiros de módulo (.ps1, .psm1e .psd1 ficheiros) com base numa coleção de regras de melhores práticas e devolve objetos que representam violações de regras. Também inclui regras especiais para analisar recursos do DSC.

Invoke-ScriptAnalyzer inclui um conjunto de regras incorporadas. Por predefinição, utiliza todas as regras. Pode utilizar os parâmetros IncludeRule e ExcludeRule para selecionar as regras pretendidas. Pode utilizar o Get-ScriptAnalyzerRule cmdlet para examinar e selecionar as regras que pretende incluir ou excluir da avaliação.

Também pode utilizar regras personalizadas que escreve em scripts do PowerShell ou compilar em assemblagens com C#. As regras personalizadas também podem ser selecionadas com os parâmetros IncludeRule e ExcludeRule .

Também pode incluir uma regra na análise, mas suprimir a saída dessa regra para funções ou scripts selecionados. Esta funcionalidade só deve ser utilizada quando necessário. Para obter regras que foram suprimidas, execute Invoke-ScriptAnalyzer com o parâmetro SuppressedOnly .

Para utilização em sistemas CI, o EnableExit sai da shell com um código de saída igual ao número de registos de erros.

Exemplos

EXEMPLO 1 - Executar todas as regras do Analisador de Scripts num script

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

EXEMPLO 2 - Executar todas as regras do Analisador de Scripts em todos os ficheiros no diretório Módulos

Este exemplo executa todas as regras do Analisador de Scripts em todos os .ps1 ficheiros e .psm1 no diretório baseado no Modules utilizador e nos respetivos subdiretórios.

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

EXEMPLO 3 - Executar uma única regra num módulo

Este exemplo executa apenas a regra PSAvoidUsingPositionalParameters nos ficheiros na pasta do PSDiagnostics módulo. Pode utilizar um comando como este para encontrar 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 - Execute todas as regras exceto duas nos módulos

Este exemplo executa todas as regras exceto PSAvoidUsingCmdletAliases e PSAvoidUsingInternalURLs nos .ps1 ficheiros e .psm1 no MyModules diretório e nos respetivos subdiretórios.

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

EXEMPLO 5 - Executar o Analisador de Scripts com regras personalizadas

Este exemplo executa o Analisador de Scripts 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 - Execute apenas as regras que são Gravidade do erro e tenha 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 regras

Este exemplo mostra como suprimir o relatório de violações de regras numa função e como detetar violações de regras que são suprimidas.

O exemplo utiliza o SuppressMessageAttribute atributo para suprimir as regras PSUseSingularNouns e PSAvoidUsingCmdletAliases para a Get-Widgets função no Get-Widgets.ps1 script. Pode utilizar este atributo para suprimir uma regra para um módulo, script, classe, função, parâmetro ou linha.

O primeiro comando executa o Analisador de Scripts no ficheiro de script que contém a função. O resultado comunica uma violação da regra. Embora sejam violadas mais regras, nenhuma regra suprimida é reportada.

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 utiliza o parâmetro SuppressedOnly para comunicar violações das regras que são suprimidas do ficheiro de script.

EXEMPLO 8 - Analisar ficheiros de script com uma definição de perfil

Neste exemplo, criamos um perfil do Analisador de Scripts e guardamo-lo no ScriptAnalyzerProfile.txt ficheiro no diretório atual. Invoke-ScriptAnalyzer Executamos nos ficheiros do módulo BitLocker. O valor do parâmetro Perfil é o caminho para o perfil do Analisador de Scripts.

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

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

Se incluir um parâmetro em conflito no Invoke-ScriptAnalyzer comando, como -Severity Error, o cmdlet utiliza o valor do perfil e ignora o parâmetro.

EXEMPLO 9 - Analisar um script armazenado como uma cadeia

Este exemplo utiliza o parâmetro ScriptDefinition para analisar uma função na linha de comandos. A cadeia 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 utiliza o parâmetro ScriptDefinition , a propriedade FileName do objeto DiagnosticRecord é $null.

Parâmetros

-Confirm

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

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CustomRulePath

Introduza o caminho para um ficheiro que defina regras ou um diretório que contenha ficheiros que definam regras. Os carateres universais são suportados. Quando CustomRulePath é especificado, apenas as regras personalizadas encontradas nos caminhos especificados são utilizadas para a análise. Se Invoke-ScriptAnalyzer não conseguir encontrar regras no , executa as regras padrão sem aviso prévio.

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

Type:	String[]
Aliases:	CustomizedRulePath
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-EnableExit

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ExcludeRule

Omite as regras especificadas do teste do Analisador de Scripts. Os carateres universais são suportados.

Introduza uma lista separada por vírgulas de nomes de regras, uma variável que contenha nomes de regras ou um comando que obtenha nomes de regras. Também pode especificar uma lista de regras excluídas num ficheiro de perfil do Analisador de Scripts. Pode excluir regras e regras padrão num caminho de regra personalizado.

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

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

Type:	String[]
Position:	Named
Default value:	All rules are included.
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-Fix

Corrige determinados avisos que contêm uma correção no respetivo DiagnósticoRegisto.

Quando utilizou Correção, Invoke-ScriptAnalyzer aplica as correções antes de executar a análise. Certifique-se de que tem uma cópia de segurança dos seus ficheiros ao utilizar este parâmetro. Tenta preservar a codificação de ficheiros, mas ainda existem alguns casos em que a codificação pode ser alterada.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-IncludeDefaultRules

Invoque regras predefinidas juntamente com Regras personalizadas.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-IncludeRule

Executa apenas as regras especificadas no teste do Analisador de Scripts. Por predefinição, o PSScriptAnalyzer executa todas as regras.

Introduza uma lista separada por vírgulas de nomes de regras, uma variável que contenha nomes de regras ou um comando que obtenha nomes de regras. Os carateres universais são suportados. Também pode especificar nomes de regras num ficheiro de perfil do Analisador de Scripts.

Quando utiliza o parâmetro CustomizedRulePath , pode utilizar este parâmetro para incluir regras e regras padrão nos caminhos de regras personalizados.

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

O parâmetro Gravidade tem precedência sobre IncludeRule. Por exemplo, se a Gravidade for Error, não pode utilizar IncludeRule para incluir uma Warning regra.

Type:	String[]
Position:	Named
Default value:	All rules are included.
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-IncludeSuppressed

Inclua diagnósticos suprimidos na saída.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

Especifica o caminho para os scripts ou módulo a analisar. Os carateres universais são suportados.

Introduza o caminho para um script (.ps1) ou ficheiro de módulo (.psm1) ou para um diretório que contenha scripts ou módulos. Se o diretório contiver outros tipos de ficheiros, estes serão ignorados.

Para analisar ficheiros que não estejam no diretório de raiz do caminho especificado, utilize um caráter universal (C:\Modules\MyModule\*) ou o parâmetro Recurse .

Type:	String
Aliases:	PSPath
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	True

-Recurse

Executa o Analisador de Scripts nos ficheiros no diretório Caminho e todos os subdiretórios de forma recursiva.

A repetição aplica-se apenas ao valor do parâmetro Caminho. Para procurar o CustomRulePath de forma recursiva, utilize o parâmetro RecurseCustomRulePath .

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RecurseCustomRulePath

Adiciona regras definidas em subdiretórios da localização CustomRulePath . Por predefinição, Invoke-ScriptAnalyzer utiliza apenas as regras personalizadas definidas no ficheiro ou diretório especificado. Para incluir as regras incorporadas, utilize o parâmetro IncludeDefaultRules .

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ReportSummary

Escreva um resumo das violações encontradas no anfitrião.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SaveDscDependency

Resolver dependências de recursos do DSC.

Quando Invoke-ScriptAnalyzer é executado com este parâmetro, procura instâncias de Import-DSCResource -ModuleName <somemodule>. Se <somemodule> não for possível encontrar ao procurar no , Invoke-ScriptAnalyzer devolve o $env:PSModulePatherro de análise. Este erro é causado pelo parser do PowerShell não conseguir encontrar o símbolo de <somemodule>.

Se Invoke-ScriptAnalyzer encontrar o módulo no Galeria do PowerShell, transfere o módulo em falta para um caminho temporário. Em seguida, o caminho temporário é adicionado a $env:PSModulePath durante a análise. A localização temporária pode ser encontrada em $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ScriptDefinition

Executa a análise em comandos, funções ou expressões numa cadeia. Pode utilizar esta funcionalidade para analisar instruções, expressões e funções, independentemente do contexto do script.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-Settings

Um caminho para um ficheiro que contém um perfil definido pelo utilizador ou um objeto hash que contém definições para ScriptAnalyzer.

É executado Invoke-ScriptAnalyzer com os parâmetros e valores especificados no ficheiro ou tabela hash.

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

Um ficheiro de perfil do Analisador de Scripts é um ficheiro de texto que contém uma tabela hash com uma ou mais das seguintes chaves:

CustomRulePath
ExcludeRules
IncludeDefaultRules
IncludeRules
RecurseCustomRulePath
Regras
Gravidade

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

Type:	Object
Aliases:	Profile
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Severity

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

Os valores válidos são:

Erro
Aviso
Informações.

Pode especificar mais um ou mais valores de gravidade.

O parâmetro filtra as violações de regras apenas depois de executar todas as regras. Para filtrar regras de forma eficiente, utilize Get-ScriptAnalyzerRule para selecionar as regras que pretende executar.

O parâmetro Gravidade tem precedência sobre IncludeRule. Por exemplo, se Gravidade for Error, não pode utilizar IncludeRule para incluir uma Warning regra.

Type:	String[]
Position:	Named
Default value:	All rule violations
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SuppressedOnly

Devolve violações apenas para regras que são suprimidas.

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

Para suprimir uma regra, utilize SuppressMessageAttribute. Para obter ajuda, veja os exemplos.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

None

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

Saídas

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

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

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

Se utilizar o parâmetro SuppressedOnly , em vez disso, Invoke-ScriptAnalyzer devolve um objeto SuppressedRecord .

Partilhar via

Invoke-ScriptAnalyzer

Syntax

Description

Exemplos

EXEMPLO 1 - Executar todas as regras do Analisador de Scripts num script

EXEMPLO 2 - Executar todas as regras do Analisador de Scripts em todos os ficheiros no diretório Módulos

EXEMPLO 3 - Executar uma única regra num módulo

EXEMPLO 4 - Execute todas as regras exceto duas nos módulos

EXEMPLO 5 - Executar o Analisador de Scripts com regras personalizadas

EXEMPLO 6 - Execute apenas as regras que são Gravidade do erro e tenha o nome de origem PSDSC

EXEMPLO 7 - Suprimir violações de regras

EXEMPLO 8 - Analisar ficheiros de script com uma definição de perfil

EXEMPLO 9 - Analisar um script armazenado como uma cadeia

Parâmetros

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Entradas

Saídas

Comentários

Recursos adicionais

Partilhar via

Invoke-ScriptAnalyzer

Syntax

Description

Exemplos

EXEMPLO 1 - Executar todas as regras do Analisador de Scripts num script

EXEMPLO 2 - Executar todas as regras do Analisador de Scripts em todos os ficheiros no diretório Módulos

EXEMPLO 3 - Executar uma única regra num módulo

EXEMPLO 4 - Execute todas as regras exceto duas nos módulos

EXEMPLO 5 - Executar o Analisador de Scripts com regras personalizadas

EXEMPLO 6 - Execute apenas as regras que são Gravidade do erro e tenha o nome de origem PSDSC

EXEMPLO 7 - Suprimir violações de regras

EXEMPLO 8 - Analisar ficheiros de script com uma definição de perfil

EXEMPLO 9 - Analisar um script armazenado como uma cadeia

Parâmetros

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Entradas

Saídas

Ligações Relacionadas

Comentários

Recursos adicionais