Tutorial moderno de desenvolvimento de extensões para VS Code: criando uma extensão segura

O sucesso e a influência de Microsoft Visual Studio (VS) Code se devem, em grande parte, à sua capacidade de extensão. Embora seja frequentemente classificado como um editor de código, com o conhecimento e as extensões certas, ele pode fazer muito mais. Por exemplo, também pode ser usado como navegador da web, processador de texto ou sistema de gerenciamento de arquivos. A Microsoft também incentiva os desenvolvedores a aproveitar a extensibilidade do VS Code, tornando a API do VS Code o mais acessível possível.

O desenvolvimento de extensões para VS Code evoluiu muito desde o lançamento da ferramenta, em 2016. O processo está mais simples e é mais amigável para desenvolvedores. Ainda assim, há considerações e práticas específicas que você precisa conhecer antes de começar a criar sua própria extensão.

No nosso primeiro artigo sobre o desenvolvimento moderno de extensões para VS Code, abordamos os conceitos básicos do desenvolvimento para VS Code, incluindo a arquitetura e os diferentes tipos de extensões que você pode criar. Neste artigo, você vai colocar esse conhecimento em prática e aprender a criar e programar sua própria extensão para VS Code.

Criando uma extensão para VS Code

Neste tutorial, você vai aprender a criar uma extensão multifuncional para VS Code e implementar diferentes tipos de extensões. O projeto concluído está disponível neste repositório do GitHub.

Estruture o projeto da extensão para VS Code

Você precisa de alguns itens para acompanhar este tutorial. Além do VS Code, VS Codium ou VS Code Insiders, instale as seguintes ferramentas:

• Node.js

• Git

Você vai usá-los para instalar o Yeoman e o gerador de extensões do VS Code. Esse gerador cria a estrutura inicial da sua extensão, para que você não precise escrever tudo do zero. Se você optar por criar o projeto com TypeScript (recomendado neste artigo), também recomendamos instalar o TypeScript + Webpack Problem Matcher para facilitar a identificação e a correspondência de erros de código.

Depois de instalar o Node.js e o Git, abra o interpretador de linha de comando de sua preferência (Prompt de Comando, PowerShell, Terminal etc.) e execute o seguinte comando:

npm install -g yo generator-code

A instalação do Yeoman e do gerador de extensões do VS Code leva alguns instantes:

Quando a instalação terminar, use o terminal para acessar a pasta do projeto (onde você pretende armazená-lo) e execute o seguinte comando:

yo code

Isso inicia a CLI do Yeoman, que pede que você escolha o tipo de projeto para criar a estrutura inicial. Recomendamos escolher a opção New Extension (TypeScript). No entanto, se você se sentir mais à vontade com JavaScript, selecione a segunda opção:

Em seguida, o gerador pede um nome para a extensão. Escolha algo simples, como "Minhas ferramentas de edição". Você também precisa informar um identificador para a extensão, como editor-tools.

Use a seguinte descrição para sua extensão: "Uma coleção de ferramentas simples de edição para VS Code." Em seguida, decida se você quer inicializar um repositório Git para o projeto. Você também pode optar por fazer isso manualmente mais tarde.

Agora, você precisa escolher se quer empacotar o código-fonte com webpack. Confirme que sim e selecione npm como gerenciador de pacotes:

O gerador de extensões leva alguns instantes para criar a estrutura do projeto. Quando terminar, ele perguntará se você quer abrir o projeto na edição do VS Code disponível no seu sistema. Confirme pressionando Enter. O código-fonte do projeto será aberto em uma nova janela do VS Code:

Observação: Neste tutorial, usamos Visual Studio Code 1.79, npm 9.5.1 e Yeoman 4.3.1. Portanto, o processo de inicialização do projeto pode variar um pouco dependendo das versões que você está usando. Adapte as etapas conforme necessário. Se você não gosta de usar CLIs e prefere uma configuração gráfica, instale o Yeoman Application Wizard para projetos futuros.

Prepare o projeto

É possível que a sua versão do Yeoman tenha criado a estrutura do projeto com referência ao módulo vscode no arquivo package.json. Embora esse módulo ainda seja amplamente usado, ele foi descontinuado por motivos de segurança. Se esse for o seu caso, atualize o projeto.

Para preparar o projeto, primeiro verifique se o pacote @types/vscode está instalado e declarado como dependência de desenvolvimento. Use o Explorer do VS Code para abrir o arquivo package.json do projeto, que contém todas as dependências.

Depois de abrir o arquivo package.json, role para baixo até chegar ao objeto `"devDependencies"`. Verifique se a chave e o valor "@types/vscode": [version], estão definidos nele:

Além disso, verifique se o pacote @types/vscode tem um número de versão que corresponda à versão do mecanismo do VS Code. Para isso, role para cima no arquivo package.json até chegar ao objeto "engines". O número da versão do mecanismo do VS Code fica ao lado da chave "vscode":

Se o número da versão de @types/vscode não corresponder à versão do mecanismo, altere manualmente o número da versão de @type/vscode para que corresponda.

Se o pacote @types/vscode não estiver no arquivo package.json`, não tente baixá-lo e adicioná-lo manualmente. Use o npm para instalar e configurar os pacotes necessários. Para isso, abra o terminal de linha de comando e acesse a pasta raiz do projeto (cd editor-tools). Em seguida, digite e execute o seguinte comando:

npm install --save-dev @types/vscode

Verifique novamente o package.json e confirme que ele referencia todos os módulos necessários. Reforçando: o objetivo de garantir que seu projeto use o módulo vscode correto é assegurar que você está usando as bibliotecas mais seguras para criar sua extensão. Assim, sua extensão personalizada fica protegida.

A decisão de atualizar e dividir o antigo pacote npm do VS Code em dois pacotes separados foi motivada por vários fatores. Um dos principais motivos foi que o pacote original incluía dependências transitivas de um pacote comprometido chamado event-stream. Essa mudança buscou aumentar a segurança dos módulos do VS Code, além de melhorar o desempenho, reduzir a complexidade e introduzir novos recursos.  

 Ainda assim, vale a pena fazer algumas verificações preliminares de segurança e qualidade no projeto. Assim, você confirma que ele foi estruturado corretamente e com segurança.

Verifique seu projeto

Para verificar a segurança da instalação do projeto, você pode usar o Snyk. A maneira mais fácil de integrar as ferramentas do Snyk aos seus fluxos de trabalho no VS Code é instalar a extensão do Snyk depois de criar uma conta gratuita do Snyk.

Depois de instalar a extensão do Snyk, abra a janela Extensões e pesquise por "Snyk". Instale a versão release, que deve ser a primeira opção nos resultados da pesquisa:

Outra opção é adicionar a extensão oficial do Snyk pela versão web do Visual Studio Code Marketplace.

Depois de concluir a instalação, autentique-se e conecte a extensão do VS Code à sua conta do Snyk. Clique no selo do Snyk na barra lateral principal e, em seguida, em Trust workspace and connect:

O navegador padrão deve abrir a página de autenticação do Snyk. Clique no grande botão verde Authenticate. Após a autenticação, o Snyk exibirá uma mensagem confirmando que sua conta foi autenticada e que o Snyk está pronto para uso.

Recomendamos consultar a documentação oficial de configuração da extensão do Snyk para VS Code para configurar a extensão adequadamente. Também é recomendável recarregar ou reiniciar o VS Code depois de fazer essas alterações. Em seguida, volte à interface da extensão do Snyk no VS Code e clique no botão Enable Snyk Code and Start Scanning (se ele não estiver disponível, consulte a observação a seguir).  

Observação: Se o botão não estiver disponível, o Snyk deve começar a verificar o projeto automaticamente. Além disso, o VS Code pode pedir que você confirme se confia na pasta do projeto. Isso é normal. Se solicitado, clique no botão Trust Folder and Continue.

Se você estiver usando a configuração padrão da extensão do Snyk, ela deve executar automaticamente as verificações de segurança de código aberto e configuração. Um botão chamado Enable Snyk Code and start analysing deve aparecer na seção Code Security and Quality do painel do Snyk. O VS Code também pode exibir um botão Enable Snyk Code:

Ao clicar em qualquer um dos botões, a página Snyk Code Settings será aberta. Nela, você encontra uma breve descrição do que é o Snyk Code. Depois de ler, clique em Save changes: 

Volte à interface do VS Code e ao painel do Snyk. Após alguns instantes, as seções Code Security e Code Quality serão exibidas no painel do Snyk, que começará a fazer a verificação. 

Observe que o painel da interface da extensão é dividido em quatro partes:

1. Segurança de código aberto

2. Segurança de código

3. Configuração

4. Qualidade do código

Se as verificações de Code Security e Code Quality não começarem automaticamente, talvez seja necessário clicar no botão Play ao lado dos títulos. O botão Play aparece quando você passa o cursor sobre uma seção e permite executar uma nova verificação do projeto:

Após a primeira verificação, os resultados de Open Source Security and Configuration devem ser negativos (nenhuma vulnerabilidade ou problema encontrado). No entanto, Code Security e Code Quality exibirão alguns problemas e vulnerabilidades:

Expanda os resultados da análise para ver mais detalhes. A maioria dos problemas é insignificante, pois está nas dependências. Embora você possa alterar esses arquivos, é melhor ignorá-los.

Use o painel Analysis Results para revisar os alertas e ignorar ou definir exceções quando necessário (por exemplo, para módulos externos do projeto). Agora que você preparou o projeto, execute a extensão para ver o que acontece.

Execute sua extensão

Para executar a extensão, use o Explorer do VS Code para acessar o arquivo Editor-Tools/src/extension.ts. Para quem conhece padrões de projeto orientados a objetos em linguagens de programação como C# e Java, ele funciona de forma parecida com uma classe main.

O arquivo extension.ts deve conter o código de exemplo gerado pelo gerador de código de extensões do VS Code do Yeoman. Pressione F5 para testar esse código e qualquer outra alteração que você tenha feito na seção anterior.

Observação: O VS Code pode pedir que você especifique uma tarefa de compilação. Isso costuma acontecer quando não há uma tarefa padrão definida no arquivo tasks.json. Nesse caso, selecione npm: compile como tarefa de compilação.

Antes de iniciar o Extension Development Host, o VS Code pode exibir uma caixa de diálogo informando que há erros após a execução da tarefa de pré-inicialização npm: watch. Isso é normal. Marque a caixa Remember my choice in user settings e clique no botão Debug Anyway:

Quando o Extension Development Host for iniciado, abra a Command Palette pressionando Ctrl + Shift + P (no Windows) ou Shift + Command + P (no Mac). Em seguida, digite o comando Hello World no campo de texto da Command Palette. Uma pequena mensagem pop-up aparecerá no canto inferior direito:

Feche o Development Host para encerrar a sessão de execução e depuração da extensão. Na próxima seção, você finalmente vai criar sua extensão.

Crie e modifique sua extensão

Nesta seção, você vai criar uma funcionalidade simples para adicionar texto ao editor de texto ativo do VS Code. Na prática, ela funciona de forma semelhante ao preenchimento automático de aplicativos como o Excel.

Para começar, clique no explorador de arquivos do VS Code e crie um arquivo na pasta do código-fonte (SRC) do seu projeto, com o nome AutoFillExtension.ts:

Adicione o código a seguir ao arquivo AutoFillExtension.ts:

1import * as vscode from 'vscode';
2
3export function autofillMyAddress() {
4    //Retrieve the currently active text editor
5    const editor = vscode.window.activeTextEditor;
6    //Check if the editor is undefined
7    if (editor) {
8        //Insert text at the current position using an edit builder
9        editor.edit(editBuilder => {
10            editBuilder.insert(editor.selection.active,'Street 6260-112 Glenwood Ave'
11            +'\nCity/Town   Raleigh'
12            +'\nState/Province/Region   Nebraska'
13            +'\nZip/Postal Code 27612'
14            +'\nPhone Number    (919) 785-2864'
15            +'\nCountry United States'
16            +'\nLatitude    35.859171'
17            +'\nLongitude   -78.703853');
18        });
19    }
20}

Este código declara e exporta uma função chamada autoFillMyAddress. A função usa a window namespace da API do VS Code para obter o editor de texto ativo no momento (o painel do editor em foco na janela atual). Antes de adicionar texto a ele — um endereço fictício gerado aleatoriamente —, a função verifica se há um editor ativo. Para isso, usa uma instância da classe TextEditorEdit.

Depois de criar a extensão, você precisa registrá-la e chamá-la. Para isso, use o explorador de arquivos do VS Code para acessar o arquivo package.json. Você precisa adicionar um ponto de contribuição para que a funcionalidade da extensão possa ser chamada como um comando na interface do VS Code.

Role devagar pelo arquivo package.json até chegar ao objeto "contributes". Substitua o array "command" e seus valores pelo código a seguir:

"commands": [
    {
        "command": "editor-tools.fillAddress",
        "title": "Fill Address"
    }
]

Volte ao arquivo extension.ts do seu projeto e substitua o conteúdo pelo seguinte:

1// The module 'vscode' contains the VS Code extensibility API
2// Import the module and reference it with the alias vscode in your code below
3import * as vscode from 'vscode';
4import * as autofill from './AutoFillExtension';
5
6// This method is called when your extension is activated
7// Your extension is activated the very first time the command is executed
8export function activate(context: vscode.ExtensionContext) {
9    let disposable = vscode.commands.registerCommand('editor-tools.fillAddress',autofill.autofillMyAddress);
10
11    context.subscriptions.push(disposable);
12}
13
14// This method is called when your extension is deactivated
15export function deactivate() {}

Este código importa o módulo AutoFillExtension como um objeto autofill. Em seguida, usa activate para registrar o comando da extensão e adicioná-la à lista de assinaturas de ExtensionContext. Quando a extensão é desativada, o VS Code a descarta.

Agora é hora de depurar/executar sua extensão (F5). Para usá-la, abra ou crie um arquivo editável de qualquer tipo. Em seguida, abra a Paleta de Comandos e digite o comando Fill Address:

Agora vamos levar sua extensão a outro nível, aproveitando os recursos de diagnóstico do VS Code. Com essa funcionalidade adicional, ela pode verificar se o documento atual atende a um critério específico. Se não atender, a extensão exibirá uma mensagem de erro.

Feche o Extension Development Host e crie uma nova extensão na pasta src, chamada LineDiagnosticExtension.ts. Depois, adicione o conteúdo a seguir:

1import * as vscode from 'vscode';
2
3export function updateDiagnostic(collection: vscode.DiagnosticCollection) {
4    //clears previous errors
5    collection.clear;
6    //fetches current active text editor
7    let editor = vscode.window.activeTextEditor;
8    //ensures that active text editor is not undefined
9    if (editor) {
10        //fetches the document from the active text editor
11        let document = editor.document;
12        //fetches the number of lines
13        let lineCount = document.lineCount;
14        //verifies that the line count is not less than 8
15        if (lineCount < 8) {
16            //specifies the range to highlight and display errors over
17            const diagnosticrange = new vscode.Range(new vscode.Position(0, 0), new vscode.Position(lineCount-1, 10));
18            //sets the properties of VSCode's diagnostic features
19            collection.set(document.uri, [{
20                code: '',
21                message: 'Document has only ' + lineCount + ' line(s). The document must have at least 8 lines',
22                range: diagnosticrange,
23                severity: vscode.DiagnosticSeverity.Error,
24                source: '',
25                relatedInformation: [
26                    new vscode.DiagnosticRelatedInformation(new vscode.Location(document.uri, new vscode.Range(new vscode.Position(0, 0), new vscode.Position(7, 10))), 'Line Count')
27                ]
28            }]);
29        } else {
30            //if the line count is equal to or greater than 8, it clears all error messages
31            collection.clear();
32
33        }
34
35    }  
36
37}    

Este arquivo contém e exporta uma única função: updateDiagnostic(). Ela recebe um único argumento: DiagnosticCollection. A função usa a propriedade lineCount do módulo TextDocument para retornar o número de linhas do documento ativo. Se houver menos de oito linhas, ela gera uma mensagem de erro usando os recursos de diagnóstico do VS Code. Isso inclui uma janela pop-up flutuante e uma entrada no painel Problemas.

Em seguida, você precisa chamar UpdateDiagnostic() e registrá-la como parte da extensão. Abra o arquivo extension.ts e substitua o conteúdo pelo seguinte:

1// The module 'vscode' contains the VS Code extensibility API
2// Import the module and reference it with the alias vscode in your code below
3import * as vscode from 'vscode';
4import * as autofill from './AutoFillExtension';
5import * as linelimit from './LineDiagnosticExtension';
6
7// This method is called when your extension is activated
8// Your extension is activated the very first time the command is executed
9export function activate(context: vscode.ExtensionContext) {
10    //create a new diagnostic collection
11    const collection = vscode.languages.createDiagnosticCollection('line count diagnostics');
12    vscode.commands.registerCommand('editor-tools.fillAddress',autofill.autofillMyAddress);
13
14    //Initial run of the upDateDiagnostic method
15    linelimit.updateDiagnostic(collection);
16
17    //Subscribes a new event handler that activates when an edit or change is performed on a workspace document  
18    context.subscriptions.push(vscode.workspace.onDidChangeTextDocument(editorchangeevent => {      
19        if (editorchangeevent) {
20            linelimit.updateDiagnostic(collection);
21        }
22    }));
23
24}
25
26// This method is called when your extension is deactivated
27export function deactivate() {}

Este código importa LineDiagnosticExtension.ts usando o alias linelimit. Em seguida, define um novo DiagnosticCollection. Isso é executado apenas uma vez, quando a função activate é chamada. Depois de registrar o comando Fill Address, o código chama a função updateDiagnostic(), que também é executada uma vez quando o VS Code é aberto.

Para atualizar as informações de diagnóstico do VS Code, você precisa monitorar as alterações no documento. Por isso, este código registra um manipulador de eventos chamado OnDidChangeTextDocument(), que pertence ao workspace e monitora todas as edições de documentos no workspace atual.

Em seguida, o manipulador de eventos executa o método linelimit.updateDiagnostic. Como você tem duas extensões diferentes, precisa registrar ambas. No exemplo anterior, a extensão e o comando Fill Address só são registrados e adicionados à lista de assinaturas quando você executa o comando na Paleta de Comandos. Neste caso, porém, você quer que a extensão seja ativada quando o VS Code for inicializado.

O VS Code permite especificar os chamados eventos de ativação. Suas extensões só são ativadas quando ocorre um evento de ativação.

Abra o arquivo package.json do seu projeto. Role até encontrar o array activationEvents e adicione "*" como valor, entre colchetes. Isso força o VS Code a ativar todas as suas extensões em todos os eventos de ativação. Em geral, isso não é recomendado, pois aumenta o tempo de inicialização do VS Code. Mas, como estas são duas extensões simples, elas não devem afetar este projeto:

  "activationEvents": [
    "*"
  ],

Agora chegou a hora de executar e testar sua extensão. Para testá-la, crie um arquivo de texto e digite algo aleatório na área de edição. O VS Code deve sublinhar o texto em vermelho e adicionar uma mensagem ao painel de problemas:

Adicionar mais oito linhas deve limpar a mensagem de erro. Ou use o método Fill Address para facilitar:

Em seguida, execute o Snyk novamente para verificar a qualidade e a segurança do seu projeto. Confira os resultados da análise e ignore os alertas que não estiverem relacionados aos arquivos do projeto que você criou. Se encontrar notificações relevantes, siga as recomendações do Snyk para corrigir os problemas. Agora que você verificou a qualidade e a segurança da extensão, incluindo as dependências, é hora de publicá-la.

Empacote sua extensão

A Microsoft facilita o empacotamento e a publicação com a CLI VS Code Extensions (VSCE). Com essa ferramenta, você não precisa publicar sua extensão no Visual Studio Code Marketplace. Em vez disso, pode empacotá-la como um arquivo VSIX e compartilhá-la dessa forma. Você precisa do npm para instalar a CLI VSCE.

Abra o terminal de linha de comando que preferir e execute o comando npm a seguir. Não é necessário executá-lo em um diretório específico:

npm install -g @vscode/vsce

Depois de instalar o VSCE, acesse a pasta da extensão e execute o comando a seguir:

vsce package

Se você optou por não inicializar um repositório do GitHub para a extensão, talvez veja alguns avisos. Basta selecionar a opção yes para ignorá-los:

O processo de empacotamento não deve demorar muito. Quando terminar, você encontrará um novo arquivo na pasta raiz do projeto, chamado editor-tools-0.0.1.vsix (ou algo parecido):

Você pode usar esse arquivo para instalar a extensão na sua versão do VS Code. Abra o VS Code e acesse o painel de extensões. Clique no ícone de reticências na parte superior (Exibições e Mais Ações) e selecione Instalar do VSIX:

Será aberta uma janela para selecionar um arquivo. Use-a para localizar e selecionar sua extensão e clique no botão Instalar:

Depois da instalação, o VS Code exibirá uma notificação no canto inferior direito da tela:

Agora você poderá acessar as funcionalidades da extensão na sua instalação do VS Code.

Publique sua extensão

Se esta fosse uma extensão que quiséssemos publicar de fato no Visual Studio Code Marketplace, este seria o momento de fazê-lo. Em vez de publicar esta extensão de exemplo, vamos apenas explicar as etapas, sem que você precise executá-las.

Observação: não recomendamos acompanhar esta etapa na prática, pois não queremos encher o Marketplace de aplicativos de demonstração. Porém, você pode consultar as etapas a seguir se algum dia desenvolver uma extensão para disponibilizar ao público.

Para publicar seu pacote, você precisa criar uma conta do Azure DevOps para sua organização e usá-la para obter um token de acesso pessoal.

Use a página de gerenciamento de publicadores do Visual Studio Code Marketplace para criar um publicador. Lembre-se de que o nome do publicador e o nome de exibição precisam ser exclusivos.

Depois de criar um publicador, adicione ao arquivo package.json uma chave e um valor de publicador. A entrada deve usar o nome do publicador, não o nome de exibição:

"publisher": "publisher name" //Publisher name and value

"name": "editor-tools",
"displayName": "My Editor Tools",
"description": "A collection of simple editing tools for VSCode",
"version": "0.0.1",

Em seguida, entre no VSCE usando o nome (ID) do publicador e o token de acesso pessoal:

vsce login <publisher ID>

Depois de entrar, você pode publicar sua extensão com o VSCE executando o comando a seguir na pasta raiz do projeto:

vsce publish

Como alternativa, você pode enviar o VSIX manualmente pela página de gerenciamento de publicadores do Visual Studio Code Marketplace. Se optou por não empacotar a extensão durante a criação da estrutura inicial, pode fazer isso manualmente com webpack ou esbuild. O empacotamento pode melhorar a eficiência da extensão e o tempo de carregamento.

Talvez o empacotamento não seja necessário neste caso, mas pode ser para projetos futuros. Antes de empacotar, verifique se todas as dependências do seu projeto são seguras. Analise seus projetos com o Snyk para confirmar rapidamente se as bibliotecas e os módulos usados são seguros contra ameaças cibernéticas.

Além disso, como a tecnologia e a cibersegurança estão sempre mudando, suas dependências podem deixar de ser seguras, mesmo que sejam agora. Felizmente, você pode usar o Snyk para monitorar continuamente as dependências dos seus projetos. Se encontrar possíveis vulnerabilidades, o Snyk envia notificações por e-mail ou pelo Slack.

Conclusão

Neste tutorial, você aprendeu a criar uma extensão simples para o VS Code. O processo incluiu a inicialização do projeto com o gerador VSCE do Yeoman. Com isso, você conheceu a estrutura básica de uma extensão, aprendeu a registrar e ativar diferentes tipos de extensão usando o manifesto (package.json) e viu como empacotar, agrupar e publicar sua extensão.

Independentemente de você trabalhar com extensões do VS Code ou aplicativos web complexos, é importante levar a cibersegurança a sério. Mas isso nem sempre é fácil, especialmente com a adoção cada vez maior de integração contínua e desenvolvimento contínuo (CI/CD). Para ajudar, o Snyk oferece verificações automatizadas de qualidade e segurança de código, que garantem a conformidade com os padrões mais recentes do setor. Com o Snyk, você não precisa se preocupar em ficar para trás nas tendências de cibersegurança e nas práticas de programação segura: ele cuida desses aspectos para você.