Usando PSScriptAnalyzer para verificar PowerShell versão de compatibilidade

PSScriptAnalyzer versão 1.18 foi lançado recentemente, e vem equipado com poderosas novas regras que podem verificar scripts do PowerShell para incompatibilidades com outros PowerShell versões e ambientes.

neste post no blog, o primeiro de uma série, veremos como usar estas novas regras para verificar um script para problemas em execução em PowerShell 3, 5.1 e 6.o que é Psscriptanalisador?,

PSScriptAnalzyer é um módulo que fornece análise estática (ou linting) e alguma análise dinâmica (baseada no estado do seu ambiente) para o PowerShell. Ele é capaz de encontrar problemas e corrigir maus hábitos em scripts PowerShell como você criá-los, semelhante à forma como o compilador c# lhe dará avisos e encontrar erros no código C# antes de ser executado.,

Se você usar o VSCode PowerShell extensão, você pode ter visto o “verde squigglies” e relatórios de problemas que PSScriptAnalyzer gera para scripts de você autor:

Você pode instalar PSScriptAnalyzer para usar em seus próprios scripts com:

Install-Module PSScriptAnalyzer -Scope CurrentUser

PSScriptAnalyzer obras, executando uma série de regras em seus scripts, cada uma delas de forma independente avalia algumas problema., Por exemplo, AvoidUsingCmdletAliases verifica que aliases não são usados em scripts, e MisleadingBackticks verificações de aspas para traz, no fim das linhas não são seguidos por espaços em branco.

para mais informações, consulte a série PSScriptAnalyzer deep dive blog.

Introdução a verificação de compatibilidade regras

O novo compatibilidade de verificação de funcionalidade é fornecida por três novas regras:

• PSUseCompatibleSyntax, que verifica se a sintaxe usada em um script irá funcionar em outras PowerShell versões.,
• PSUseCompatibleCommands, que verifica se os comandos usados em um script estão disponíveis em outros ambientes PowerShell.
• PSUseCompatibleTypes, que verifica se os tipos.NET e métodos/propriedades estáticos estão disponíveis em outros ambientes PowerShell.

a regra de verificação da sintaxe simplesmente requer uma lista de versões PowerShell que você deseja atingir, e irá dizer-lhe se uma sintaxe usada no seu programa não irá funcionar em nenhuma dessas versões.,

as regras de verificação de comandos e tipos são mais sofisticadas e dependem de perfis (catálogos de comandos e tipos disponíveis) de plataformas PowerShell comumente usadas. Eles precisam de configuração para usar esses perfis, que iremos ver abaixo.

para este post, vamos olhar para configurar e usar PSUseCompatibleSyntax e PSUseCompatibleCommands para verificar que um script funciona com diferentes versões de PowerShell. Vamos olhar para PSUseCompatibleTypes em um post posterior, embora esteja configurado de forma muito semelhante ao PSUseCompatibleCommands.,

exemplo de Trabalho: um pequeno script do PowerShell

Imagine que temos um pequeno (e artificial) arquivamento de script guardado .\archiveScript.ps1:

Este script foi escrito em PowerShell 6.2, e que já testamos, que funciona lá. Mas nós também queremos executá-lo em outras máquinas, algumas das quais funcionam PowerShell 5.1 e algumas das quais funcionam PowerShell 3.0.

idealmente vamos testá-lo em outras plataformas, mas seria bom se pudéssemos tentar resolver tantos bugs quanto possível antes do tempo.,

verificar a sintaxe com PSUseCompatibleSyntax

a primeira e mais fácil regra a aplicar é PSUseCompatibleSyntax. Nós vamos criar algumas configurações para o PSScriptAnalyzer para habilitar a regra, e então executar a análise em nosso script para obter de volta qualquer diagnóstico sobre compatibilidade.

executar PSScriptAnalyzer é simples., Ele vem como um módulo de PowerShell, uma vez que é instalado no seu caminho de módulo que você acabou de chamá-lo em seu arquivo com Invoke-ScriptAnalyzer, assim:

Invoke-ScriptAnalyzer -Path ".\archiveScript.ps1`

muito simples invocação de como este será executado PSScriptAnalyzer usando suas regras padrão e as configurações de script que você aponte-o para.

no entanto, como eles exigem uma configuração mais direcionada, as regras de compatibilidade não são ativadas por padrão. Em vez disso, precisamos fornecer algumas configurações para executar a regra de verificação de sintaxe., Em particular, PSUseCompatibleSyntax requer uma lista das versões PowerShell que você está visando com seu script.

executar isto irá apresentar – nos a seguinte saída:

isto está a dizer-nos que a sintaxe ]::new() que usamos não funcionará em PowerShell 3. Melhor do que a que, neste caso, a regra tem, na verdade, propôs uma correção:

$diagnostics = Invoke-ScriptAnalyzer -Path .\archiveScript.ps1 -Settings $settings$diagnostics.SuggestedCorrections

A correção sugerida é usar New-Object em vez disso., A forma como isto é sugerido pode parecer um pouco inútil aqui com toda a informação da posição, mas veremos mais tarde por que isso é útil.

Este exemplo do dicionário é um pouco artificial, é claro (uma vez que uma hashtable viria mais naturalmente), mas ter uma chave de fenda lançada nas obras em PowerShell 3 ou 4 por causa de um ::new() não é incomum. A regra PSUseCompatibleSyntax também irá avisá-lo sobre classes, workflows e using afirmações dependendo das versões de PowerShell que você está criando.,

não vamos fazer a mudança sugerida ainda, uma vez que há mais para mostrar-lhe primeiro.

verificar a utilização de comandos com PSUseCompatibleCommands

queremos agora verificar os comandos. Como a compatibilidade de comandos é um pouco mais complicada do que a sintaxe (uma vez que a disponibilidade de comandos depende de mais do que a versão do PowerShell está sendo executado), nós temos que direcionar perfis em vez disso.

perfis são catálogos de informações tiradas de máquinas de estoque rodando ambientes PowerShell comuns., Os enviados no PSScriptAnalyzer nem sempre podem corresponder perfeitamente ao seu ambiente de trabalho, mas eles chegam muito perto (há também uma maneira de gerar o seu próprio perfil, detalhado em um post posterior no blog). No nosso caso, estamos a tentar atingir PowerShell 3.0, PowerShell 5.1 e PowerShell 6.2 no Windows. Temos os dois primeiros perfis, mas, no último caso, teremos de apontar para 6.1. Estes alvos estão muito próximos, por isso os avisos ainda serão pertinentes para a utilização de PowerShell 6.2. Mais tarde, quando um perfil 6.2 estiver disponível, poderemos mudar para isso.,

é necessário procurar na documentação do PSUseCompatibleCommands uma lista de perfis disponíveis por omissão. Para os nossos objectivos pretendidos nós escolher:

A nomes longos no direito são canônicos perfil de identificadores, que usamos nas configurações:

pode haver um atraso na primeira vez que você executar este, porque as regras para carregar os catálogos em um cache. Cada catálogo de uma plataforma PowerShell contém detalhes de todos os módulos e .,Conjuntos líquidos disponíveis para PowerShell naquela plataforma, que pode ser de até 1700 comandos com 15.000 parâmetros e 100 conjuntos com 10.000 tipos. Mas quando estiver carregada, a análise de compatibilidade será rápida. Temos de saída como esta:

RuleName Severity ScriptName Line Message-------- -------- ---------- ---- -------PSUseCompatibleCommands Warning archiveScr 2 The parameter "FullyQualifiedName" is not available for ipt.ps1 command "Import-Module" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 12 The command "Get-FileHash" is not available by default in ipt.ps1 PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 18 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "5.1.17763.316" on platform "Microsoft Windows Server 2019 Datacenter"PSUseCompatibleCommands Warning archiveScr 18 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 19 The command "Compress-Archive" is not available by ipt.ps1 default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 23 The parameter "NoNewline" is not available for command ipt.ps1 "Out-File" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"

Isto está nos dizendo que:

• Import-Module não suporta -FullyQualifiedName no PowerShell 3.0;
• Get-FileHash não existe no PowerShell 3.0;
• Split-Path não tem -LeafBase no PowerShell 5.1 ou PowerShell 3.,0;
• Compress-Archive não está disponível em PowerShell 3.0, e;
• Out-File não suporta -NoNewline no PowerShell 3.0

Uma coisa que você vai notar é que o Get-FoldersToArchive função não está sendo avisado. Isto porque as regras de compatibilidade são projetadas para ignorar os comandos fornecidos pelo usuário; um comando só será marcado como incompatível se estiver presente em algum perfil e não em um de seus alvos.,

mais uma vez, podemos alterar o script para corrigir esses avisos, mas, antes, quero mostrar a você como fazer isso mais experiência contínua; como você alterar o script, você quer saber se as alterações que você fizer quebra de compatibilidade, e isso é fácil de fazer com os passos abaixo.

usando um ficheiro de configuração para invocação repetida

a primeira coisa que queremos é tornar a invocação PSScriptAnalyzer mais automatizada e reprodutível. Um bom passo para isso é pegar o hashtable de configurações que fizemos e transformá-lo em um arquivo de dados declarativos, separando o “o que” do “como”.,

PSScriptAnalyzer irá aceitar um caminho para um PSD1 no parâmetro -Settings, então tudo o que precisamos fazer é transformar a nossa hashtable em um arquivo PSD1, que faremos ./PSScriptAnalyzerSettings.psd1. Aviso de nós pode mesclar as configurações para PSUseCompatibleSyntax e PSUseCompatibleCommands:

Agora podemos executar o PSScriptAnalyzer novamente o script usando as configurações do arquivo:

Invoke-ScriptAnalyzer -Path ./archiveScript.ps1 -Settings ./PSScriptAnalyzerSettings.psd1

Isto dá a saída:

RuleName Severity ScriptName Line Message-------- -------- ---------- ---- -------PSUseCompatibleCommands Warning archiveScr 1 The parameter "FullyQualifiedName" is not available for ipt.ps1 command "Import-Module" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 9 The command "Get-FileHash" is not available by default in ipt.ps1 PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 12 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 12 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "5.1.17763.316" on platform "Microsoft Windows Server 2019 Datacenter"PSUseCompatibleCommands Warning archiveScr 13 The command "Compress-Archive" is not available by ipt.ps1 default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 16 The parameter "NoNewline" is not available for command ipt.ps1 "Out-File" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleSyntax Warning archiveScr 6 The constructor syntax ipt.ps1 "]::new()" is not available by default in PowerShell versions 3,4

Agora nós não dependem de quaisquer variáveis mais, e ter uma spefication da análise que você deseja., Usando isso, você pode colocar isso em ambientes de integração contínua, por exemplo, para verificar se as mudanças em scripts não quebram a compatibilidade.

mas o que realmente queremos é saber que os scripts PowerShell permanecem compatíveis à medida que os editamos. Isso é o que o arquivo de configuração está construindo, e também onde é mais fácil fazer as alterações que você precisa para tornar o seu script compatível. Para isso, queremos integrar com a extensão PowerShell VSCode.,

integrando-se com o VSCode para verificação da compatibilidade em voo

como explicado no início desta postagem, a extensão PowerShell do VSCode tem suporte para PSScriptAnalyzer. Na verdade, a partir da versão 1.12.0, a extensão PowerShell navios com PSScriptAnalyzer 1.18, o que significa que você não precisa fazer nada além de criar um arquivo de configuração para fazer a análise de compatibilidade.

já temos o nosso ficheiro de configuração pronto a partir do último passo, por isso tudo o que temos de fazer é apontar a extensão PowerShell para o ficheiro na configuração do VSCode.,

pode abrir a configuração com Ctrl+ (use o Cmd em vez de Ctrl Em macOS). Na janela de configuração, queremos PowerShell > Script Analysis: Settings Path. In thesettings.json view this is"powershell.scriptAnalysis.settingsPath"., Entrando em um caminho relativo aqui vai encontrar um arquivo de configurações em nossa área de trabalho, então é só colocar ./PSScriptAnalyzerSettings.psd1:

settings.json visualizar este terá a seguinte aparência:

"powershell.scriptAnalysis.settingsPath": "./PSScriptAnalyzerSettings.psd1"

Agora, abrindo o script em VSCode vemos “verde squigglies” para compatibilidade com as advertências:

No painel de problemas, você terá um completo desrciption de todas as incompatibilidades:

Vamos corrigir o problema de sintaxe em primeiro lugar., Se você se lembrar, PSScriptAnalyzer fornece uma correção sugerida para este problema. VSCode integra-se com PSScriptAnalyzer as correções sugeridas e pode aplicá-las, se você clicar na lâmpada ou com Ctrl+barra de Espaço quando a região está sob o cursor:

Aplicar essa alteração, o script é agora:

A outras incompatibilidades não tem correções; agora PSUseCompatibleCommands sabe quais comandos estão disponíveis em cada plataforma, mas não é o que a substitua quando um comando não está disponível., Então, nós apenas precisa aplicar PowerShell conhecimento:

Vamos acabar com algo como isto (a implementação específica é importante, mas nós temos algo que irá funcionar em todas as versões):

Você deve notar que, à medida que você digita, VSCode exibe a nova análise do que está escrito e o verde squigglies soltar. Quando terminarmos, teremos um atestado de saúde limpo para a compatibilidade do script:

isto significa que você agora será capaz de usar este script em todas as versões PowerShell que você precisa para atingir., Melhor, você agora tem uma configuração em seu espaço de trabalho de modo que você escreve mais scripts, há uma verificação contínua para a compatibilidade. E se seus alvos de compatibilidade mudarem, tudo que você precisa fazer é mudar seu arquivo de configuração em um lugar para apontar para seus alvos desejados, em que ponto você vai obter análise para suas plataformas de alvo atualizadas.

resumo

Esperemos que neste post do blog você tenha alguma idéia das novas regras de compatibilidade que vêm com PSScriptAnalyzer 1.18.,

cobrimos como configurar e usar a regra de verificação de compatibilidade de sintaxe, PSUseCompatibleSyntax, e a regra de verificação de comandos, PSUseCompatibleCommands, ambos usando uma configuração hashtable e um arquivo de configuração PSD1.

Nós também analisamos usando as regras de compatibilidade com a extensão PowerShell para VSCode, onde eles vêm por padrão a partir da versão 1.12.0.

Se tiver a versão mais recente da extensão PowerShell para VSCode (1.12.1), poderá configurar o seu ficheiro de configuração e obter imediatamente a verificação da compatibilidade.,

no próximo post do blog, vamos ver como usar estas regras e PSUseCompatibleTypes (que verifica se os tipos.NET e os métodos estáticos estão disponíveis nas plataformas de destino) podem ser usados para ajudá-lo a escrever scripts que funcionam com plataformas cruzadas através do Windows e Linux usando tanto o PowerShell como o PowerShell Core.Rob Holt Engenheiro de Software