Uso do Visual Studio Code para desenvolvimento do PowerShell

  • Artigo

O VS Code (Visual Studio Code) é um editor de scripts multiplataforma da Microsoft. Junto com a extensão do PowerShell, ele fornece uma experiência rica e interativa de edição de scripts, facilitando a criação de scripts confiáveis do PowerShell. O Visual Studio Code com a extensão do PowerShell é o editor recomendado para escrever scripts do PowerShell.

Ele dá suporte às seguintes versões do PowerShell:

  • PowerShell 7.2 e versões posteriores (Windows, macOS e Linux)
  • Windows PowerShell 5.1 (somente Windows) com .NET Framework 4.8

Observação

O Visual Studio Code não é igual ao Visual Studio.

Introdução

Antes de começar, verifique se o PowerShell existe no seu sistema. Para cargas de trabalho modernas no Windows, macOS e Linux, confira os seguintes links:

Para cargas de trabalho tradicionais do Windows PowerShell, confira Como instalar o Windows PowerShell.

Importante

O ISE do Windows PowerShell ainda está disponível para o Windows. No entanto, ele não está mais no desenvolvimento ativo de recursos. O ISE funciona apenas com o PowerShell 5.1 e mais antigo. Como componente do Windows, ele continua com suporte oficial para correções de segurança e serviços de alta prioridade. Não há planos de remover o ISE do Windows.

Instalar o VS Code e a extensão do PowerShell

  1. Instale o Visual Studio Code. Para obter mais informações, confira a visão geral Configurar o Visual Studio Code.

    Há instruções de instalação para cada plataforma:

  2. Instale a extensão do PowerShell.

    1. Inicie o aplicativo do VS Code digitando code em um console ou code-insiders se você instalou o Visual Studio Code Insiders.
    2. Inicie o Abertura rápida no Windows ou no Linux pressionando Ctrl+P. No macOS, pressione Cmd+P.
    3. Em Abertura rápida, digite ext install powershell e pressione Enter.
    4. A exibição Extensões será aberta na barra lateral. Selecione a extensão do PowerShell da Microsoft.
    5. Clique no botão Instalar na extensão do PowerShell da Microsoft.
    6. Após a instalação, se o botão Instalar mudar para Recarregar, clique em Recarregar.
    7. Depois que o VS Code for carregado novamente, você estará pronto para editar.

Por exemplo, para criar um arquivo, clique em Arquivo > Novo. Para salvá-lo, clique em Arquivo > Salvar e forneça um nome de arquivo, como HelloWorld.ps1. Para fechar o arquivo, clique no X ao lado do nome de arquivo. Para sair do VS Code, escolha Arquivo > Sair.

Instalando a extensão do PowerShell em sistemas restritos

Alguns sistemas são configurados para exigir a validação de todas as assinaturas de código. Você poderá receber o seguinte erro:

Language server startup failed.

Esse problema pode ocorrer quando a política de execução do PowerShell é definida pela Política de Grupo do Windows. Para aprovar manualmente os Serviços do Editor do PowerShell e a extensão do PowerShell para VS Code, abra um prompt do PowerShell e execute o seguinte comando:

Import-Module $HOME\.vscode\extensions\ms-vscode.powershell*\modules\PowerShellEditorServices\PowerShellEditorServices.psd1

O sistema mostrará a mensagem Você deseja executar o software desse editor não confiável? Digite A para executar o arquivo. Em seguida, abra o VS Code e verifique se a extensão do PowerShell está funcionando corretamente. Se você ainda tiver problemas para começar, fale conosco em Problemas do GitHub.

Escolha de uma versão do PowerShell para ser usada com a extensão

Com o PowerShell instalado juntamente com o Windows PowerShell, agora é possível usar uma versão específica do PowerShell com a extensão do PowerShell. Esse recurso analisa alguns caminhos conhecidos em diferentes sistemas operacionais para descobrir locais de instalação do PowerShell.

Siga as etapas a seguir para escolher a versão:

  1. Abra a Paleta de comandos no Windows ou Linux com Ctrl+Shift+P. No macOS, use Cmd+Shift+P.
  2. Pesquise por Sessão.
  3. Clique em PowerShell: mostrar menu de sessão.
  4. Escolha a versão do PowerShell que deseja usar na lista.

Se você instalou o PowerShell em um local não típico, talvez ele não apareça inicialmente no menu de sessão. Você pode estender o menu de sessão adicionando seus próprios caminhos personalizados conforme descrito abaixo.

O menu de sessão do PowerShell também pode ser acessado pelo ícone {} no canto inferior direito da barra de status. Passar o mouse sobre esse ícone ou selecioná-lo exibe um atalho para o menu de sessão e um ícone de alfinete pequeno. Se você selecionar o ícone de alfinete, o número da versão será adicionado à barra de status. O número da versão é um atalho para o menu de sessão que exige menos cliques.

Observação

Fixar o número de versão replica o comportamento da extensão em versões do VS Code anteriores ao 1.65. A versão 1.65 do VS Code alterou as APIs que a extensão do PowerShell usa e padronizou a barra de status para extensões de idioma.

Definições de configuração para o Visual Studio Code

Primeiro, caso você não esteja familiarizado com a maneira de alterar as configurações no VS Code, recomendamos ler a documentação de configurações do Visual Studio Code.

Depois de ler a documentação, você pode adicionar definições de configuração no settings.json.

{
    "editor.renderWhitespace": "all",
    "editor.renderControlCharacters": true,
    "files.trimTrailingWhitespace": true,
    "files.encoding": "utf8bom",
    "files.autoGuessEncoding": true
}

Caso não queira que essas configurações afetem todos os tipos de arquivos, o VS Code também permite configurações por idioma. Crie uma configuração específica a um idioma colocando as configurações em um campo [<language-name>]. Por exemplo:

{
    "[powershell]": {
        "files.encoding": "utf8bom",
        "files.autoGuessEncoding": true
    }
}

Dica

Para saber mais sobre a codificação do arquivo no VS Code, confira Entendendo a codificação do arquivo. Confira também Como replicar a experiência do ISE no VS Code para obter outras dicas sobre como configurar o VS Code para edição no PowerShell.

Adição dos seus caminhos do PowerShell ao menu de sessão

É possível adicionar outros caminhos executáveis do PowerShell ao menu de sessão por meio de uma configuração do Visual Studio Code: powershell.powerShellAdditionalExePaths.

Você pode fazer isso usando a GUI:

  1. Na Paleta de Comandos, pesquise e selecione Abrir Configurações do Usuário. Ou use o atalho de teclado no Windows ou no Linux Ctrl+,. No macOS, use Cmd+,.
  2. No editor Configurações, pesquise Caminhos de Exe Adicionais do PowerShell.
  3. Clique em Adicionar Item.
  4. Em Chave (em Item), forneça sua escolha de nome para esta instalação adicional do PowerShell.
  5. Em Valor (em Valor), forneça o caminho absoluto para o executável em si.

Você pode adicionar quantos caminhos adicionais quiser. Os itens adicionados aparecem no menu de sessão com a chave fornecida como o nome.

Como alternativa, você pode adicionar pares chave-valor ao objeto powershell.powerShellAdditionalExePaths em seu settings.json:

{
    "powershell.powerShellAdditionalExePaths": {
        "Downloaded PowerShell": "C:/Users/username/Downloads/PowerShell/pwsh.exe",
        "Built PowerShell": "C:/Users/username/src/PowerShell/src/powershell-win-core/bin/Debug/net6.0/win7-x64/publish/pwsh.exe"
    },
}

Observação

Antes da versão 2022.5.0 da extensão, essa configuração era uma lista de objetos com as chaves exePath e versionNamenecessárias. Uma alteração interruptiva foi introduzida para dar suporte à configuração por meio da GUI. Se você tiver definido essa configuração anteriormente, converta-a no novo formato. O valor fornecido para versionName agora é a Chave e o valor fornecido para exePath agora é o Valor. Você pode fazer isso com mais facilidade redefinindo o valor e usando a interface Configurações.

Para configurar a versão padrão do PowerShell, defina o valor powershell.powerShellDefaultVersion para o texto exibido no menu de sessão (o texto usado para a chave):

{
    "powershell.powerShellAdditionalExePaths": {
        "Downloaded PowerShell": "C:/Users/username/Downloads/PowerShell/pwsh.exe",
    },
    "powershell.powerShellDefaultVersion": "Downloaded PowerShell",
}

Depois de definir essa configuração, reinicie o VS Code ou recarregue a janela atual do VS Code na Paleta de Comandos e digite Developer: Reload Window.

Se você abrir o menu de sessão, agora verá as instalações adicionais do PowerShell.

Dica

Compilar o PowerShell na origem é uma ótima maneira de testar sua compilação local do PowerShell.

Depuração com o Visual Studio Code

Depuração sem espaço de trabalho

No VS Code versão 1.9 (ou posterior), é possível depurar scripts do PowerShell sem abrir a pasta que contém o script do PowerShell.

  1. Abra o arquivo de script do PowerShell com Arquivo > Abrir Arquivo...
  2. Defina um ponto de interrupção – selecione uma linha e pressione F9
  3. Pressione F5 para iniciar a depuração

Você deverá ver o painel de ações Depuração, que permite que você interrompa o depurador, execute em etapas, retome e pare a depuração.

Depuração do workspace

A depuração do workspace refere-se à depuração no contexto de uma pasta que você abriu no menu Arquivo usando Abrir Pasta... . A pasta que você abrir normalmente é a pasta do projeto do PowerShell ou a raiz do repositório Git. A depuração do workspace permite definir várias configurações de depuração diferentes de depurar apenas o arquivo aberto no momento.

Siga estas etapas para criar um arquivo de configuração de depuração:

  1. Abra a exibição Depurar no Windows ou Linux pressionando Ctrl+Shift+D. No macOS, pressione Cmd+Shift+D.

  2. Clique no link criar um arquivo launch.json.

  3. No prompt Selecionar Ambiente, escolha PowerShell.

  4. Escolha o tipo de depuração que você deseja usar:

    • Iniciar o Arquivo Atual – inicie e depure o arquivo na janela do editor atualmente ativa
    • Iniciar Script – inicie e depure o arquivo ou comando especificado
    • Sessão Interativa – depure os comandos executados no Console Integrado
    • Anexar – anexe o depurador a um processo de host do PowerShell em execução

O VS Code cria um diretório e um arquivo .vscode\launch.json na raiz da sua pasta do workspace para armazenar a configuração de depuração. Se os arquivos estiverem em um repositório Git, normalmente você desejará confirmar o arquivo launch.json. O conteúdo do arquivo launch.json e:

{
  "version": "0.2.0",
  "configurations": [
      {
          "type": "PowerShell",
          "request": "launch",
          "name": "PowerShell Launch (current file)",
          "script": "${file}",
          "args": [],
          "cwd": "${file}"
      },
      {
          "type": "PowerShell",
          "request": "attach",
          "name": "PowerShell Attach to Host Process",
          "processId": "${command.PickPSHostProcess}",
          "runspaceId": 1
      },
      {
          "type": "PowerShell",
          "request": "launch",
          "name": "PowerShell Interactive Session",
          "cwd": "${workspaceRoot}"
      }
  ]
}

Esse arquivo representa os cenários comuns de depuração. Ao abrir este arquivo no editor, você vê um botão Adicionar configuração... . É possível clicar nesse botão para adicionar mais configurações de depuração do PowerShell. Uma configuração útil a adicionar é PowerShell: Iniciar Script. Com essa configuração, é possível especificar um arquivo contendo os argumentos opcionais usados sempre que você pressiona F5, não importa qual arquivo está ativo no editor.

Depois que a configuração de depuração for estabelecida, você poderá selecionar qual configuração deseja usar durante uma sessão de depuração. Selecione uma configuração na lista suspensa de configuração de depuração, na barra de ferramentas da exibição Depurar.

Solucionar problemas na extensão do PowerShell

Se você tiver problemas ao usar o VS Code para desenvolver scripts do PowerShell, confira o guia de solução de problemas no GitHub.

Recursos úteis

Há alguns vídeos e postagens no blog que podem ser úteis para você começar a usar a extensão do PowerShell para o VS Code:

vídeos

Postagens no blog

Código-fonte do projeto de extensão do PowerShell

O código-fonte da extensão do PowerShell pode ser encontrado no GitHub.

Se você tem interesse em contribuir, as solicitações de pull são uma ótima opção. Siga a documentação de desenvolvedor no GitHub para começar.