Desenvolvimento moderno de extensões para VS Code: o básico

De acordo com as estatísticas de programação da WakaTime de 2022, o Microsoft Visual Studio (VS) Code é atualmente o editor de código-fonte mais popular. Embora muitas vezes seja classificado como um editor de código-fonte, ele também pode ser usado como um ambiente de desenvolvimento integrado (IDE) completo. Basta adicionar o conjunto certo de extensões do Visual Studio Code Marketplace.

O apelo do VS Code vai muito além da possibilidade de personalização. Embora haja uma infinidade de plugins disponíveis, às vezes é necessário criar sua própria extensão. Esta série foi criada justamente para isso.

Nesta parte da série Desenvolvimento moderno de extensões para VS Code, vamos falar sobre diferentes tipos de extensão, explorar a arquitetura típica das extensões do VS Code e conhecer algumas práticas recomendadas para desenvolvê-las. Este artigo é uma introdução que estabelece uma base sólida antes de nos aprofundarmos no próximo post.

Tipos de extensão do VS Code

No Visual Studio Code Marketplace, as extensões e os plugins são organizados em grupos chamados tipos ou categorias de extensão, de acordo com suas diferentes funções e recursos. A maneira mais fácil de acessar essas categorias é pela versão web do marketplace, mas você também pode acessá-las na interface da visualização Extensões do Visual Studio Code, usando a tag @category: na barra de pesquisa:

Ao navegar por essa lista, você pode começar a se perguntar o que esses grupos realmente significam. O que faz uma extensão ser um formatador e outra, um tema?

Veja a seguir alguns dos tipos de extensão mais comuns no Visual Studio Code Marketplace e no Open VSX Registry, um registro de extensões de código aberto, mantido pela comunidade, para extensões do Visual Studio Code (VS Code).

Temas

Com mais de 10 mil opções, os temas são um dos tipos de extensão mais comuns no Visual Studio Code Marketplace. Eles permitem mudar a aparência da interface do VS Code, incluindo painéis, menus e área de texto.

Para pesquisar todos os plugins de temas, use o filtro @category:"Themes":

Algumas extensões de tema são específicas para determinados componentes ou plugins. Por exemplo, o plugin C/C++ Themes, apresentado anteriormente, oferece um conjunto de temas otimizados visualmente para desenvolvimento em C/C++, com melhorias para a coloração semântica.

Os temas de cores geralmente são criados e configurados com JSON e podem ser personalizados com facilidade. Você encontra as opções workbench.colorCustomizations e editor.tokenColorCustomizations em Configurações do usuário.

Em geral, as extensões de tema têm uma finalidade principalmente estética e estão entre as mais fáceis de desenvolver. No entanto, elas também podem contribuir para a acessibilidade e melhorar a experiência geral de programação.

Extensões funcionais

As extensões funcionais reúnem diferentes categorias de extensões que adicionam recursos ao VS Code, como linters (@category:"linters"), notebooks (@category:"notebooks"), formatadores (@category:"formatters"), testes (@category:"testing"), visualizações (@category:"visualization"), linguagens de programação (@category:"programming languages"), depuradores (@category:"debuggers") e integrações de gerenciamento de cadeia de suprimentos (SCM) (@category:"scm providers").

No entanto, como a Microsoft e o VS Code oferecem um número limitado de tags de categoria, algumas categorias podem não descrever com precisão a finalidade de uma extensão. Por exemplo, Snyk Security está categorizada como linter e extensão de linguagem de programação. Embora a extensão Snyk Security possa parecer uma ferramenta de lint, ela faz muito mais do que isso. Seu principal objetivo é aumentar a segurança dos seus projetos de desenvolvimento de software. Ela identifica vulnerabilidades de código aberto e no código, problemas de licença, configurações inseguras de infraestrutura como código (IaC) e muito mais:

Na verdade, plugins do VS Code como o Snyk Security também podem ajudar a aprimorar o desenvolvimento de extensões. A Snyk verifica automaticamente se as dependências da sua extensão são seguras, se os projetos estão configurados corretamente e se o código tem qualidade e segurança.

Trechos de código e atalhos

As extensões de trechos de código e atalhos ajudam você a personalizar o mapa de teclas do VS Code (@category:"keymaps") e os recursos de trechos de código (@category:"snippets"). Por exemplo, o REST Client é uma extensão multilíngue que gera trechos e modelos para solicitações HTTP:

Já o Eclipse Keymap adiciona ao VS Code as combinações de teclas da IDE Eclipse. Isso é útil para desenvolvedores Java que usam o Eclipse como IDE principal e podem ter interesse em migrar para o VS Code:

Pacotes

Há dois tipos de pacotes: pacotes de idiomas (@category:"language packs") e pacotes de extensões (@category:"extension packs"). Os pacotes de idiomas contêm dados de localização, como traduções de texto e configurações de teclado. Por exemplo, o Pacote de Idioma Chinês (Simplificado) (简体中文) permite substituir o idioma padrão da interface do VS Code pelo chinês simplificado.

O VS Code também permite mudar o idioma de exibição depois que você instala o pacote de idiomas. Se quiser ajudar com as traduções e contribuir para a criação de um pacote de idiomas, considere participar do projeto de localização da comunidade do VS Code.

Além disso, os pacotes de extensões reúnem várias extensões em uma única instalação. Em geral, eles seguem um tema ou oferecem um ambiente de desenvolvimento pronto para começar. Por exemplo, o Python Extension Pack inclui a extensão Python for VS Code, além de Python Environment Manager, Python Indent e autoDocstring - Python Docstring Generator.

Ao clicar no botão Install do Python Extension Pack, o VS Code instala simultaneamente todas as extensões do pacote que ainda não estiverem instaladas:

Em resumo, os pacotes de extensões evitam que você precise baixar várias extensões individualmente. Isso é especialmente útil ao configurar espaços de trabalho para linguagens sem suporte direto (ou oficial) da Microsoft. Também é uma ótima maneira de empacotar todas as suas extensões personalizadas do VS Code.

Depois de decidir que tipo de extensão você quer desenvolver, é hora de começar a definir a estrutura.

A arquitetura típica das extensões do VS Code

O Extension Host do VS Code é responsável por executar as extensões. Ele usa o manifesto da extensão (package.json) para localizar o ponto de entrada e executá-lo de acordo com os eventos de ativação. Esses eventos de ativação também são declarados no arquivo de manifesto. Eles permitem definir os gatilhos das extensões, por exemplo, quando um comando é executado ou uma linguagem específica é selecionada.

O arquivo package.json também contém uma lista de dependências essenciais para o projeto da sua extensão. Entre elas está o módulo @types/vscode, que permite integrar sua extensão à API do VS Code.

Observação: O módulo @types/vscode substitui o pacote `vscode-extension-vscode`, que foi descontinuado e não deve ser referenciado no arquivo package.json nem em qualquer outro lugar do projeto.

O manifesto da extensão também contém um conjunto de pontos de contribuição. Eles permitem controlar como os recursos da extensão são acionados no VS Code. Por exemplo, você pode configurar um comando ou item de menu para chamar sua extensão.

O arquivo de entrada da extensão contém seu comportamento principal. Ele depende principalmente do módulo vscode, que deve ser sempre a primeira importação da extensão:

export function activate(context: vscode.ExtensionContext) {
    //Instructions and Commands
}

O módulo vscode contém a API do VS Code, que oferece um conjunto de interfaces para ampliar os recursos do VS Code. Entre elas está a interface de extensão, com os recursos necessários para gerenciar, configurar e criar extensões.

O método activate da interface de extensão permite definir o que ela faz quando é ativada e é a próxima etapa no arquivo de entrada:

export function activate(context: vscode.ExtensionContext) {
    //Instructions and Commands
}

Esse código funciona de maneira semelhante a um manipulador de eventos: declara um conjunto de comandos executados quando ocorre um evento. Você também pode incluir uma chamada e uma exportação da função deactivate:

export function deactivate(context: vscode.ExtensionContext) {}

Isso permite fazer a limpeza da extensão após a ativação ou execução.

Os arquivos de entrada podem ser escritos em TypeScript ou JavaScript, mas o uso do primeiro é recomendado. De qualquer forma, projetos de extensão em TypeScript e JavaScript devem incluir um arquivo config, pois ele define um diretório como a pasta raiz do projeto e ajuda o compilador a localizá-lo. O arquivo config também inclui várias propriedades e opções do compilador. Use o arquivo tsconfig.json nos projetos TypeScript e o arquivo jsconfig.json nos projetos JavaScript.

O diretório do projeto da sua extensão também contém dois arquivos adicionais na pasta .vscode:

1. tasks.json

O tasks.json define um conjunto de tarefas específicas de pasta, projeto ou espaço de trabalho, que o VS Code deve executar quando acionadas. Essas tarefas consistem principalmente em instruções e configurações de compilação do projeto. Como o VS Code compila suas extensões usando gerenciadores de pacotes como o npm, por exemplo, o arquivo tasks.json do projeto da extensão costuma fazer referência a eles, como neste exemplo:

	"type": "npm",
	"script": "watch",
	"problemMatcher": "$ts-webpack-watch",
	"isBackground": true,
	"presentation": {
		"reveal": "never",
		"group": "watchers"
	},
	"group": {
		"kind": "build",
		"isDefault": true
	}

Este exemplo de tasks.json define um monitor de compilação que verifica se há erros e avisos nos processos de compilação do projeto. O script usa principalmente o npm para executar e empacotar o detector de problemas ts-webpack-watch.

2. launch.json

O launch.json define como o VS Code deve executar (ou depurar) suas extensões depois que elas forem compiladas. Ele inclui informações sobre o ambiente de execução usado pela extensão:

"configurations": [
    {
        "name": "Run Extension",
        "type": "extensionHost",
        "request": "launch",
        "args": [
            "--extensionDevelopmentPath=${workspaceFolder}"
        ],
        "outFiles": [
            "${workspaceFolder}/dist/**/*.js"
        ],
        "preLaunchTask": "${defaultBuildTask}"
    },
]

Este exemplo de launch.json é uma configuração que define as instruções para iniciar uma extensão do VS Code, incluindo a localização do código-fonte e dos executáveis empacotados.

Um diretório básico de projeto de extensão tem esta aparência:

Project Parent Folder
├── .vscode
│   ├── launch.json     
│   └── tasks.json                
├── src
│   └── extension.ts    //Extension Entry File
├── package.json       	//Manifest
├── tsconfig.json  

Práticas recomendadas para desenvolver extensões do VS Code

Devido à estrutura das extensões do VS Code, é fácil deixar de lado alguns fundamentos. Mas, para desenvolver extensões com eficiência, você precisa seguir certos princípios, incluindo estas práticas recomendadas:

Teste suas extensões a fundo

Se você pretende publicar sua(s) extensão(ões) em algum Visual Studio Code Marketplace compatível, evite incluir código com defeitos. Para isso, garanta que sua extensão seja bem testada com diferentes técnicas de avaliação de software, como testes unitários (quando aplicável) e testes rigorosos de cenários.

Você não precisa usar plugins ou bibliotecas externas para testar suas extensões do VS Code, mas o próprio VS Code oferece mecanismos e ferramentas para testes de integração. Em particular, o Extension Development Host permite testar suas extensões em um ambiente separado da instância oficial do VS Code.

Não se esqueça de que os usuários avaliam e comentam as extensões no Visual Studio Code Marketplace, por isso é importante testá-las a fundo. Não coloque a reputação da sua marca em risco ao lançar um produto com bugs ou inseguro.

Armazene dados confidenciais com o máximo de segurança

O VS Code evoluiu a maneira de salvar e armazenar dados do usuário. Antes da versão 1.53 do VS Code, as informações dos usuários eram tratadas pela interface ExtensionContext, mas essa solução não era eficiente.

Hoje, a melhor maneira de gerenciar informações confidenciais no VS Code é usar o recurso SecretStorage.

Siga as diretrizes de experiência do usuário (UX) do VS Code da Microsoft

A Microsoft tem um conjunto de diretrizes de experiência do usuário (UX) que ajudam a garantir que as extensões estejam alinhadas à arquitetura e aos padrões do VS Code. Recomendamos que você conheça todas elas, mas dê atenção especial às que se aplicam às funcionalidades da sua extensão.

Por exemplo, sua extensão pode não incluir componentes visuais sofisticados, como webviews, mas talvez os recursos principais sejam complexos o bastante para justificar um guia interativo. Esse tutorial interativo de início rápido ajuda novos usuários a se familiarizarem com os recursos da extensão. Como boa prática, os desenvolvedores devem garantir que o software tenha uma boa documentação, tanto no código quanto nas instruções de uso.

Além disso, facilite ao máximo os primeiros passos. Isso significa incluir as imagens e os elementos visuais necessários. A Microsoft recomenda usar SVGs com as cores de tema da API do VS Code.

As melhores extensões do VS Code se integram à interface de forma tão natural que é quase impossível diferenciá-las dos recursos nativos do VS Code.

Empacote suas extensões

Como o VS Code pertence à Microsoft, é fácil esquecer que ele — assim como suas variantes — é um aplicativo multiplataforma. Além do Windows, o VS Code está disponível nas versões mais recentes do macOS e em distribuições Linux baseadas em Debian e Red Hat. Por isso, suas extensões devem seguir os princípios fundamentais do VS Code e funcionar em todas as plataformas compatíveis com o VS Code.

A melhor maneira de fazer isso é com o empacotamento. A Microsoft recomenda usar o esbuild para empacotar extensões do VS Code, devido à velocidade e à eficiência da ferramenta. O webpack é outra boa opção.

Além disso, com a crescente adoção da plataforma como serviço (PaaS), é importante garantir que suas extensões sejam compatíveis com o Visual Studio Code para a Web. Somente extensões empacotadas funcionam perfeitamente nessa versão baseada na Web.

Além disso, tanto o esbuild quanto o webpack podem minificar seu código. A minificação remove textos desnecessários e altera os nomes de membros, como métodos, funções e variáveis. Infelizmente, isso pode mudar o comportamento do código. Por exemplo, já houve casos de código-fonte que usa as funções Function.prototype.name e toString() apresentar problemas após a minificação.

A verdade é que muitos minificadores têm essas limitações. Se você suspeitar que o minificador do webpack está causando problemas no código, pode desativá-lo temporariamente até identificar a causa.

Por outro lado, o esbuild não faz a minificação a menos que você a solicite explicitamente com a opção --minify flag, o que dá a você mais controle sobre o processo.

Os desenvolvedores também devem garantir que as dependências essenciais estejam otimizadas para o empacotamento. Infelizmente, tentar empacotar dependências dinâmicas provavelmente fará com que o processo falhe. Essas dependências devem ser declaradas como estáticas ou excluídas usando externals. Os desenvolvedores podem usar o dependency-check da Snyk para facilitar esse processo.

Proteja suas extensões

O Visual Studio Code Marketplace verifica ativamente se há conteúdo malicioso em novas extensões e atualizações. Além disso, os usuários do VS Code podem denunciar extensões inseguras pelo link Denunciar abuso. Apesar dessas medidas preventivas, porém, o Visual Studio Code Marketplace não está livre de conteúdo malicioso.

Uma pesquisa publicada pela Snyk identificou várias extensões vulneráveis no Visual Studio Code Marketplace, capazes de expor sistemas a diferentes tipos de ataques, como falsificação de requisição do lado do servidor e travessia de diretórios.

Muitas dessas extensões não são criadas com intenção maliciosa. Os desenvolvedores simplesmente não priorizam a segurança porque desconhecem os riscos ou não têm tempo. As medidas de segurança devem ser consideradas e implementadas desde o início do ciclo de desenvolvimento.

Isso pode parecer uma tarefa difícil, mas, com ferramentas como a Snyk, você não precisa criar suas próprias práticas e verificações de segurança. A Snyk oferece um plano gratuito, para que qualquer desenvolvedor possa usar e integrar seus principais recursos.

Além disso, a Snyk sabe que o desenvolvimento de software moderno acontece em ritmo acelerado. Ao permitir que você conecte seu perfil do GitHub ou do Google, a Snyk facilita a criação de uma conta. E você não precisa usar a interface Web da Snyk para se autenticar ou acessar os recursos da plataforma. Você pode usar a Snyk CLI ou uma das várias integrações, incluindo a extensão para VS Code:

Ela verifica não só problemas de segurança no código que você escreve, mas também nos módulos e bibliotecas dos quais ele depende. A interface da extensão da Snyk para VS Code é uma versão compacta da interface Web. Ela se integra a vários elementos da interface do VS Code, incluindo os diagnósticos, a visualização de problemas/painel e o editor. Com ela, você pode identificar quais linhas do seu código podem expor sua extensão a ataques:

Como alguns módulos ou dependências podem ser colocados em sandbox quando sua extensão é publicada, nem sempre é necessário protegê-los manualmente. Por exemplo, você pode usar o painel de análise da Snyk para ignorar linhas ou arquivos que considerar irrelevantes para a segurança do projeto:

Por padrão, a Snyk VS Code Extension monitora e verifica seu projeto automaticamente enquanto você o desenvolve. Mas você também pode configurar a extensão para funcionar quando e como preferir:

No fim das contas, você decide como integrar a extensão ao seu fluxo de trabalho.

Conclusão

Este guia reúne tudo o que você precisa saber para começar a desenvolver extensões do VS Code. Nele, você conheceu a estrutura básica dessas extensões, incluindo como o manifesto da extensão se conecta ao arquivo de entrada. Além disso, aprendeu algumas boas práticas para dar os primeiros passos.

O mais importante é garantir que suas extensões atendam aos padrões de UX da Microsoft e sejam seguras. Com a Snyk, a plataforma de segurança desenvolvida para desenvolvedores, você verifica se suas extensões usam código-fonte de alta qualidade e dependências seguras. A Snyk oferece uma ampla variedade de integrações, incluindo um plugin para VS Code que ajuda a realizar e automatizar verificações de qualidade e segurança nos seus projetos.