Tutorial moderno de desarrollo de extensiones para VS Code: cómo crear una extensión segura
2 de octubre de 2023
0 minutos de lecturaLa popularidad y la influencia de Microsoft Visual Studio (VS) Code se deben en gran medida a su capacidad de extensión. Aunque suele clasificarse como un editor de código, con los conocimientos y las extensiones adecuados puede ofrecer mucho más. Por ejemplo, también puedes usarlo como navegador web, procesador de texto o sistema de administración de archivos. Microsoft también anima a los desarrolladores a aprovechar la capacidad de extensión de VS Code y hace que la API de VS Code sea lo más accesible posible.
El desarrollo de extensiones para VS Code ha avanzado mucho desde que la herramienta se lanzó en 2016. Ahora es más sencillo y amigable para los desarrolladores. Sin embargo, aún hay algunas consideraciones y prácticas especiales que debes tener en cuenta antes de empezar a crear tu propia extensión.
En nuestra primera publicación sobre el desarrollo moderno de extensiones para VS Code, vimos los conceptos básicos, incluida su arquitectura y los distintos tipos de extensiones que puedes crear. En este artículo, te ayudaremos a poner esos conocimientos en práctica y te mostraremos cómo crear y programar tu propia extensión para VS Code.
Cómo crear una extensión para VS Code
En este tutorial, aprenderás a crear una extensión multifuncional para VS Code que te enseñará a implementar distintos tipos de extensiones. Puedes encontrar el proyecto terminado en este repositorio de GitHub.
Crear la estructura inicial del proyecto de tu extensión para VS Code
Necesitas algunas cosas para seguir este tutorial. Además de VS Code, VS Codium o VS Code Insiders, asegúrate de tener instaladas las siguientes herramientas:
Las usarás para instalar Yeoman y el generador de extensiones para VS Code. Este generador crea una estructura inicial para tu extensión, así no tienes que escribir todo desde cero. Si decides crear tu proyecto con TypeScript (la opción recomendada para esta publicación), te recomendamos instalar TypeScript + Webpack Problem Matcher, que facilita la detección y la identificación de errores de código.
Cuando tengas Node.js y Git instalados, abre la interfaz de línea de comandos que prefieras (Símbolo del sistema, PowerShell, Terminal, etc.) y ejecuta el siguiente comando:
La instalación de Yeoman y su generador de extensiones para VS Code tarda unos momentos:

Cuando termine la instalación, usa la terminal para ir a la carpeta de tu proyecto (donde planeas guardarlo) y ejecuta el siguiente comando:
Se abrirá la CLI de Yeoman y tendrás que elegir el tipo de proyecto cuya estructura inicial quieres crear. Te recomendamos elegir la opción New Extension (TypeScript). Sin embargo, si te sientes más cómodo con JavaScript, selecciona la segunda opción:

A continuación, el generador te pedirá que le pongas un nombre a tu extensión. Elige uno sencillo, como «My Editor Tools». También debes ingresar un identificador para la extensión, por ejemplo, editor-tools.
Usa esta descripción para tu extensión: «Una colección de herramientas sencillas de edición para VS Code». Después, decide si quieres inicializar un repositorio de Git para tu proyecto. También puedes inicializarlo manualmente más adelante.
En este punto, te preguntarán si quieres agrupar el código fuente con webpack. Confirma que sí y luego selecciona npm como administrador de paquetes:

El generador de extensiones tardará unos momentos en crear la estructura inicial del proyecto. Cuando termine, te preguntará si quieres abrir el proyecto en la edición de VS Code disponible en tu sistema. Confírmalo presionando Enter. El código fuente del proyecto se abrirá en una nueva ventana de VS Code:

Nota: En este tutorial se usan Visual Studio Code 1.79, npm 9.5.1 y Yeoman 4.3.1. Por lo tanto, el proceso de inicialización del proyecto puede variar ligeramente según las versiones que uses. Adapta los pasos según sea necesario. Si no te gusta usar CLI y prefieres una configuración gráfica, instala Yeoman Application Wizard para tus próximos proyectos.
Preparar el proyecto
Es posible que la versión de Yeoman que tienes haya creado la estructura del proyecto con una referencia al módulo vscode en el archivo package.json. Aunque este módulo todavía se usa mucho, está obsoleto por motivos de seguridad. Si es tu caso, asegúrate de actualizar el proyecto.
Para preparar el proyecto, primero asegúrate de que el paquete @types/vscode esté instalado y declarado como dependencia de desarrollo. Usa el Explorador de VS Code para abrir el archivo package.json del proyecto, que contiene todas sus dependencias.
Una vez que abras el archivo package.json, desplázate hacia abajo hasta llegar al objeto `"devDependencies"`. Asegúrate de que la clave y el valor "@types/vscode": [version], estén definidos dentro de ese objeto:

Además, debes asegurarte de que el número de versión del paquete @types/vscode coincida con la versión del motor de VS Code. Para hacerlo, desplázate hacia arriba en el archivo package.json hasta llegar al objeto "engines". Encontrarás el número de versión del motor de VS Code junto a la clave "vscode":

Si el número de versión de @types/vscode no coincide con la versión del motor, cambia manualmente el número de versión de @type/vscode para que coincida.
Si el paquete @types/vscode no aparece en el archivo package.json`, no intentes descargarlo y agregarlo manualmente. Usa npm para instalar y configurar los paquetes necesarios. Abre la terminal de línea de comandos y ve a la carpeta raíz del proyecto (cd editor-tools). Luego, ingresa y ejecuta el siguiente comando:

Vuelve a validar el archivo package.json y asegúrate de que haga referencia a todos los módulos necesarios. Recuerda que comprobar que tu proyecto use el módulo vscode correcto tiene como objetivo garantizar que uses las bibliotecas más seguras para crear tu extensión. Así, te aseguras de que tu extensión personalizada sea segura.
La decisión de actualizar y dividir el antiguo paquete npm de VS Code en dos paquetes separados se tomó por varios motivos. Uno de los más importantes fue que el paquete original incluía dependencias transitivas de un paquete comprometido llamado event-stream. Este cambio buscaba mejorar la seguridad de los módulos de VS Code, además de optimizar el rendimiento, reducir la complejidad e incorporar funciones nuevas.
Sin embargo, también deberías realizar algunas verificaciones preliminares de seguridad y calidad en tu proyecto. Así te asegurarás de que su estructura inicial se haya creado de forma correcta y segura.
Verificar el proyecto
Para verificar la seguridad de la instalación de tu proyecto, puedes usar Snyk. La forma más sencilla de integrar las herramientas de Snyk en tus flujos de trabajo de VS Code es instalar la extensión de Snyk después de crear una cuenta gratuita de Snyk.
Después de instalar la extensión de Snyk, abre la ventana de Extensions y busca «Snyk». Asegúrate de instalar la versión release, que debería ser la primera opción en los resultados de búsqueda:

También puedes agregar la extensión oficial de Snyk desde la versión web de Visual Studio Code Marketplace.
Cuando termine la instalación, autentícate y conecta la extensión de VS Code con tu cuenta de Snyk. Haz clic en la insignia de Snyk en la barra lateral principal y luego en Confiar en el espacio de trabajo y conectar:

Se debería abrir la página web de autenticación de Snyk en tu navegador predeterminado. Haz clic en el botón verde grande Authenticate. Cuando la autenticación se complete correctamente, Snyk mostrará un mensaje para informarte que tu cuenta se autenticó y que ya puedes usar Snyk.
Te recomendamos leer la documentación oficial de configuración de la extensión de Snyk para VS Code para configurar la extensión según tus necesidades. También es recomendable volver a cargar o reiniciar VS Code después de hacer estos cambios. Luego, regresa a la interfaz de la extensión de Snyk en VS Code y haz clic en el botón Enable Snyk Code and Start Scanning (si no está disponible, consulta la nota a continuación).
Nota: Si el botón no está disponible, Snyk debería empezar a analizar tu proyecto automáticamente. Además, VS Code podría pedirte que confirmes que confías en la carpeta del proyecto. Esto es normal. Si aparece el mensaje, haz clic en el botón Confiar en la carpeta y continuar.
Si usas la configuración predeterminada de la extensión de Snyk, Snyk debería ejecutar automáticamente los análisis de seguridad de código abierto y configuración. En la sección Seguridad y calidad del código del panel de Snyk debería aparecer un botón con la etiqueta Enable Snyk Code and start analysing. VS Code también podría mostrar el botón Enable Snyk Code:

Al hacer clic en cualquiera de los botones, se abrirá la página de configuración de Snyk Code. Allí encontrarás una breve descripción de Snyk Code. Después de leerla, haz clic en Guardar cambios:

Vuelve a la interfaz de VS Code y al panel de Snyk. Después de unos momentos, el panel de Snyk debería mostrar las secciones Seguridad del código y Calidad del código e iniciar el análisis.
Ten en cuenta que el panel de la interfaz de la extensión tiene cuatro secciones:
Seguridad de código abierto
Seguridad del código
Configuración
Calidad del código
Si las funciones de Seguridad del código y Calidad del código no empiezan a analizar automáticamente, es posible que debas seleccionar el botón Reproducir junto a sus títulos. El botón Reproducir aparece cuando pasas el cursor sobre una sección y te permite volver a analizar el proyecto:

Después del primer análisis, el escáner de seguridad de código abierto y configuración debería mostrar resultados negativos (no se encontraron vulnerabilidades ni problemas). Sin embargo, las secciones de seguridad del código y calidad del código mostrarán algunos problemas y vulnerabilidades:

Expande los resultados del análisis para ver más detalles. La mayoría de los problemas son insignificantes, ya que se encuentran en tus dependencias. Aunque puedes modificar esos archivos, es mejor omitirlos.
Usa el panel de Resultados del análisis para revisar las alertas, ignorarlas y definir excepciones cuando sea necesario (por ejemplo, para módulos de proyectos externos). Ahora que preparaste el proyecto, ejecuta la extensión para ver qué sucede.
Ejecutar la extensión
Para ejecutar la extensión, usa el Explorador de VS Code para ir al archivo Editor-Tools/src/extension.ts. Si conoces los patrones de diseño orientado a objetos de lenguajes de programación como C# y Java, este archivo funciona de forma similar a una clase main.
El archivo extension.ts debería contener el código de ejemplo que genera Yeoman con el generador de extensiones para VS Code. Presiona la tecla F5 para probar este código y cualquier otro cambio que hayas hecho en la sección anterior.
Nota: VS Code podría pedirte que especifiques una tarea de compilación. Esto suele ocurrir si no se configuró una tarea predeterminada en el archivo tasks.json. En ese caso, selecciona npm: compile como tarea de compilación.

Antes de iniciar el Host de desarrollo de extensiones, VS Code podría mostrar un cuadro de diálogo de error que te informa que hay errores tras ejecutar la tarea previa al inicio npm: watch. Esto es completamente normal. Marca la casilla Recordar mi elección en la configuración de usuario y haz clic en el botón Depurar de todos modos:

Cuando se inicie el Host de desarrollo de extensiones, abre la Paleta de comandos presionando Ctrl + Shift + P (en Windows) o Shift + Command + P (en Mac). Luego, ingresa el comando Hello World en el campo de texto de la Paleta de comandos. Aparecerá un pequeño mensaje emergente en la esquina inferior derecha:

Asegúrate de cerrar el Host de desarrollo para terminar la sesión de ejecución y depuración de la extensión. En la siguiente sección, por fin crearás tu extensión.
Crear y modificar tu extensión
En esta sección, crearás una funcionalidad sencilla para agregar texto al editor de texto activo de VS Code. Conceptualmente, funciona de forma similar a la función de autocompletar de aplicaciones como Excel.
Para empezar, haz clic en el explorador de archivos de VS Code y agrega un archivo nuevo al directorio del código fuente (SRC) de tu proyecto. Llámalo AutoFillExtension.ts:

Agrega el siguiente código al archivo AutoFillExtension.ts:
Este código declara y exporta una función llamada autoFillMyAddress. La función recupera el editor de texto activo (el panel del editor que tiene el foco de la ventana actual) mediante el espacio de nombres window de la API de VS Code. Comprueba que haya un editor activo antes de agregarle texto (una dirección ficticia generada al azar) mediante una instancia de la clase TextEditorEdit.
Una vez que hayas creado la extensión, debes registrarla y llamarla. Para hacerlo, usa el explorador de archivos de VS Code para buscar el archivo package.json. Debes agregar un punto de contribución para poder llamar a la funcionalidad de la extensión como un comando desde la interfaz de usuario de VS Code.
Desplázate lentamente hacia abajo por el archivo package.json hasta llegar al objeto "contributes". Reemplaza el arreglo "command" y sus valores con el siguiente código:

Vuelve al archivo extension.ts de tu proyecto y reemplaza su contenido por lo siguiente:
Este código importa el módulo AutoFillExtension como un objeto autofill. Luego, usa activate para registrar el comando de la extensión y agregarla a la lista de suscripciones de ExtensionContext. Cuando se desactiva la extensión, VS Code la elimina.
Ahora es momento de depurar y ejecutar tu extensión (F5). Para usarla, abre o crea un archivo nuevo (de cualquier tipo) que puedas editar. Luego, abre la paleta de comandos y escribe el comando Fill Address:

Ahora llevaremos tu extensión al siguiente nivel aprovechando las funciones de diagnóstico de VS Code. Con esta funcionalidad adicional, tu extensión puede comprobar si el documento actual cumple un criterio específico. Si no lo cumple, la extensión mostrará un mensaje de error.
Cierra Extension Development Host y crea una extensión nueva en la carpeta src llamada LineDiagnosticExtension.ts. Luego, agrega el siguiente contenido:
Este archivo contiene y exporta una única función: updateDiagnostic(). Acepta un solo argumento: DiagnosticCollection. La función usa la propiedad lineCount del módulo TextDocument para obtener el número de líneas del documento activo. Si tiene menos de ocho líneas, genera un mensaje de error mediante las funciones de diagnóstico de VS Code. Esto incluye una ventana emergente y una entrada en el panel Problemas.
A continuación, debes llamar a UpdateDiagnostic() y registrarla como parte de tu extensión. Abre el archivo extension.ts y reemplaza su contenido por lo siguiente:
Este código importa LineDiagnosticExtension.ts con el alias linelimit. Luego, define un nuevo objeto DiagnosticCollection. Esto se ejecuta una sola vez, cuando se llama a la función activate. Después de registrar el comando Fill Address, llama a la función updateDiagnostic(), que también se ejecuta una sola vez cuando se abre VS Code.
Para actualizar la información de diagnóstico de VS Code, debes detectar los cambios en el documento. Por eso, este código registra un controlador de eventos llamado OnDidChangeTextDocument(), que pertenece al espacio de trabajo y supervisa todas las ediciones de documentos en el espacio de trabajo actual.
A continuación, el controlador de eventos ejecuta el método linelimit.updateDiagnostic. Como tienes dos extensiones diferentes, debes registrar ambas. En el ejemplo anterior, la extensión y el comando Fill Address solo se registran y agregan a la lista de suscripciones cuando ejecutas el comando desde la paleta de comandos. En cambio, aquí quieres que se active al iniciar VS Code.
VS Code te permite especificar lo que se conoce como eventos de activación. Tus extensiones solo se activan cuando ocurre un evento de activación.
Abre el archivo package.json de tu proyecto. Desplázate hacia abajo hasta encontrar el arreglo activationEvents y agrega "*" como valor (entre los corchetes). Esto obliga a VS Code a activar todas tus extensiones ante cualquier evento de activación. Por lo general, no se recomienda hacerlo porque ralentiza el inicio de VS Code. Sin embargo, como estas son dos extensiones sencillas, no deberían afectar este proyecto:

Por fin, es momento de ejecutar y probar tu extensión. Para hacerlo, crea un archivo de texto nuevo y escribe cualquier cosa en el área de texto. VS Code debería subrayar el texto en rojo y agregar un mensaje al panel de problemas:

Si agregas ocho líneas más, el mensaje de error debería desaparecer. También puedes usar el método Fill Address para hacerlo más fácilmente:

Luego, vuelve a ejecutar Snyk para verificar la calidad y seguridad de tu proyecto. Revisa los resultados del análisis e ignora las alertas que no estén relacionadas con los archivos del proyecto que creaste. Si encuentras notificaciones pertinentes, sigue las recomendaciones de Snyk para corregir los problemas. Ahora que verificaste la calidad y seguridad de tu extensión y sus dependencias, es momento de publicarla.
Empaqueta tu extensión
Microsoft facilita el empaquetado y la publicación con su CLI de VS Code Extensions (VSCE). Con esta herramienta, no tienes que publicar tu extensión necesariamente en Visual Studio Code Marketplace. En su lugar, puedes empaquetarla como un archivo VSIX y compartirla de esa manera. Necesitas npm para instalar la CLI de VSCE.
Abre la terminal de línea de comandos que prefieras y ejecuta el siguiente comando de npm (no es necesario ejecutarlo en un directorio específico):
Una vez que hayas instalado VSCE, ve a la carpeta de tu extensión y ejecuta el siguiente comando:
Si antes decidiste no inicializar un repositorio de GitHub para tu extensión, es posible que aparezcan algunas advertencias. Puedes omitirlas con solo seleccionar la opción yes:

El proceso de empaquetado no debería tardar mucho. Cuando termine, encontrarás un archivo nuevo en la carpeta raíz de tu proyecto llamado editor-tools-0.0.1.vsix (o con un nombre similar):

Puedes usar este archivo para instalar la extensión en tu versión de VS Code. Abre VS Code y ve al panel de extensiones. Haz clic en el ícono de puntos suspensivos de la parte superior (Vistas y más acciones) y luego selecciona Instalar desde VSIX:

Se abrirá un explorador para seleccionar archivos. Úsalo para buscar y seleccionar tu extensión; luego, haz clic en el botón Instalar:

Una vez instalada, VS Code mostrará una notificación emergente cerca de la esquina inferior derecha de la pantalla:

Ahora deberías poder acceder a la funcionalidad de tu extensión desde tu versión de VS Code.
Publica tu extensión
Si esta fuera una extensión que quisiéramos publicar en Visual Studio Code Marketplace, este sería el momento de hacerlo. En lugar de publicar esta extensión de ejemplo, repasaremos los pasos sin que tengas que seguirlos.
Ten en cuenta: No recomendamos seguir este paso, ya que no queremos llenar Marketplace de aplicaciones de demostración. Sin embargo, puedes consultar los siguientes pasos si alguna vez desarrollas una extensión para uso público.
Para publicar tu paquete, debes crear una cuenta de Azure DevOps para tu organización y usarla para obtener un token de acceso personal.
Puedes usar la página de administración de publicadores de Visual Studio Code Marketplace para crear un publicador. Ten en cuenta que el nombre del publicador y el nombre para mostrar deben ser únicos.
Una vez que hayas creado un publicador, debes agregar una clave y un valor de publicador al archivo package.json. La entrada debe usar el nombre del publicador, no el nombre para mostrar:
Luego, inicia sesión en VSCE con el nombre (ID) del publicador y el token de acceso personal:

Después de iniciar sesión correctamente, puedes publicar tu extensión con VSCE ejecutando el siguiente comando en la carpeta raíz del proyecto de tu extensión:
También puedes cargar manualmente el VSIX en la página de administración de publicadores de Visual Studio Code Marketplace. Si durante el proceso de configuración inicial decidiste no agrupar tu extensión, puedes hacerlo manualmente con webpack o esbuild. La agrupación puede mejorar la eficiencia y los tiempos de carga de tu extensión.
Aunque en este caso quizá no sea necesario agrupar, sí podría serlo en tus proyectos futuros. Antes de hacerlo, asegúrate de que todas las dependencias de tu proyecto sean seguras. Analizar tus proyectos con Snyk puede confirmar rápidamente que tus bibliotecas y módulos sean seguros frente a ciberamenazas.
Además, como la tecnología y la ciberseguridad cambian constantemente, es posible que tus dependencias dejen de ser seguras, aunque lo sean ahora. Por suerte, puedes usar Snyk para supervisar continuamente las dependencias de tus proyectos. Si detecta posibles vulnerabilidades, Snyk te envía notificaciones por correo electrónico o Slack.
Conclusión
En este tutorial, aprendiste a crear una extensión sencilla para VS Code. El proceso incluyó inicializar el proyecto con el generador VSCE de Yeoman. Así, aprendiste cómo es la estructura básica de una extensión, cómo registrar y activar distintos tipos de extensiones mediante el manifiesto de la extensión (package.json), y cómo empaquetar, agrupar y publicar tu extensión.
Ya sea que trabajes con extensiones de VS Code o aplicaciones web complejas, debes tomarte en serio la ciberseguridad. Sin embargo, esto no siempre es fácil, sobre todo con la creciente adopción de la integración continua y el desarrollo continuo (CI/CD). Para ayudarte, Snyk ofrece comprobaciones automatizadas de la calidad y seguridad del código que garantizan el cumplimiento de los estándares más recientes del sector. Con Snyk, puedes dejar de preocuparte por quedarte atrás en las tendencias de ciberseguridad y las prácticas de programación segura, porque Snyk se encarga de estos aspectos por ti.
Protege tus pipelines con Snyk
Agrega cobertura de seguridad continua a tu CI/CD.
