Visual Studio Code extensions demystified

When I tried for the first time Visual Studio Code on my Mac I remained quite impressed about its performances.
The investment Microsoft did during the last few years on this editor is really remarkable, considering also that it’s an open source software and not a commercial one.
As you know with Visual Studio Code you can create your own extensions and then share with the community inside the marketplace.
This for me was just an interesting and quick pet project before going back the my reactive studies, but it is worth to share it

I created a simple extensions for retrieving all the annotations in my Javascript projects grouping per categories inside the output panel or in a markdown file.

vscode-annotations-panel

You can download the extension called vscode-annotations directly from the marketplace or inside the extensions panel in Visual Studio Code editor.
If you want instead take a look to the source, feel free to clone the project from Github.

 

extensionpanel

First steps

If you wanna quickly start working on an extension, there is a Yeoman generator provided by the Visual Studio Code team that will create the folder structure and the necessary files for publishing your extension later on.
In order to use it just run these commands in your terminal window:

npm install -g yo generator-code
yo code

During the generation, the interactive generator will ask if you prefer working with Typescript or pure Javascript, in my case I picked the latter one.
After that you will have your project ready and you can start to have fun with Visual Studio Code!
if you prefer start with the classic Hello World project feel free to check Microsoft tutorial.

In my annotations extension what I’ve done is just providing 3 commands available in the command palette (CMD+SHIFT+P or View > Command Palette) :

. output all the annotations in the file opened inside the editor
. output all the annotations in a specific project
. export all the annotations in a specific project to a Markdown file

The first two will create an output panel inside the editor showing the annotations present inside a specific file or an entire workspace, the third one will create a markdown file with all the annotations for a specific project.

When you want to create a command inside the command palette, you need to set it up in few files, the first one is the package.json:

"activationEvents": [
     "onCommand:extension.getAnnotations",
     "onCommand:extension.getAllAnnotations",
     "onCommand:extension.createAnnotationsOutput"
 ]

and then in the commands array:

"contributes": {
    "commands": [
    {
        "command": "extension.getAnnotations",
        "title": "ANNOTATIONS: check current file"
    },
    {
        "command": "extension.createAnnotationsOutput",
        "title": "ANNOTATIONS: export markdown file"
    },
    {
        "command": "extension.getAllAnnotations",
        "title": "ANNOTATIONS: check current project"
    }]
 }

so in the commands array we are just defining the label that will be inside the command palette and the action that should be triggered when the user selects a specific command.
Then we will need to add each of them in the extension.js file (created by the scaffolder) inside the activate method that will be triggered once the editor will have loaded your extension:

vscode.commands.registerCommand('extension.getAnnotations', function () {
    // extension code here
 });

Just with these few lines of code you can see the expected results of having your commands present in the palette

vscode-annotations-palette

Microsoft is providing a well documented APIs for interacting with the editor, obviously, because it’s based on Electron bear in mind that you can also use Node.js APIs for extending the functionalities of your extension, for instance to create a file or interacting with the operating system.

Working with the workspace

When you want to interact with the editor manipulating files or printing inside the embedded console you need to deal with the workspace APIs.
In order to do that you need to become confident with a couple of objects of the vscode library:

  • window
  • workspace

With window and workspace you can handle end to end the editor UI and the project selected.
Window object is mainly use to understand what’s happening inside a file meanwhile an user is editing it.
You can also use the window object for showing notification or error messages or change the status bar

With the workspace object instead, you will be able to manage all the interactions that are happening inside the menu or editor interface.
Workspace object is useful when you want to iterate trough the project files or if you need to understand which files are currently open in the editor and when they will be closed for instance.

In my extension I used these 2 objects for showing a notification to the user:

vscode.window.showErrorMessage('There aren\'t javascript files in the open project!');

for interacting with the output panel:

vscode.window.createOutputChannel(outputWin_NAME);

[....]

outputWin.appendLine(`FILE -> file://${doc.fileName}`);
outputWin.appendLine("-----------------------------------------");
outputWin.appendLine(getBody(data, OUTPUT_PANEL_CONFIG))
outputWin.appendLine(OUTPUT_PANEL_CONFIG.newline);

outputWin.show(true);

and for iterating and opening a javascript file present inside a proejct:

vscode.workspace.openTextDocument(file.path)

[...]

vscode.workspace.findFiles('**/*.js', '**/node_modules/**', 1000).then(onFilesRetrieved)

Debugging an extension

Considering you are developing an extension for an editor you can easily debug what you are doing simply running the extension debug mode (F5 or fn+F5 from your macbook).

screen-shot-2017-01-31-at-04-06-39

Few suggestions regarding the debug mode:

  • console.dir doesn’t work, console.log will substitute what console.dir does if you are inspecting an object but not an array!
  • when an error occurs it’s not very self-explained (kudos to Facebook for the react native errors handling, best implementation ever!) so you will need to follow the stack trace as usual

Publishing an extension

Last part of this brief post will be related to the submission of your extension to the Visual Studio Code marketplace.
Also in this case Microsoft did a good job creating an extensive guide on how to do that, few suggestions also in this case:

  • in order to submit an extension in the marketplace you will need to create a Microsoft and a Visual Studio Team Service accounts
  • when you create the Personal Access Token for publishing your extension, bear in mind to set access to all accounts and all scope otherwise you could end up with a 401 or 404 error when you try to publish the extension
    screen-shot-2017-01-31-at-04-26-47
  • vsce command line tool is pretty good in order to create a publisher identity and super fast to publish an application on the marketplace.
    Considering that is a CLI tool you can also automate few part of the publishing process (increasing release number for instance) adding a scripts in your package.json
  • to make your extension more accessible in the marketplace, remember to add the keywords array inside the package.json with meaningful words and the appropriate category, at the moment there are the following categories available:
    Debuggers
    Extension Packs
    Formatters
    Keymaps
    Languages
    Linters
    Snippets
    Themes
    Other

    screen-shot-2017-01-31-at-22-14-31

Wrap up

There could be tons of other things to do and to discover for developing a Visual Studio Code extension but I think that could be a good recap of the lessons learnt for creating one that you could use along with the Microsoft guide.

Advertisements

I tell you a story…

Long, long time ago there was a company called Adobe that changed the aim of a great platform like Flash, so Flash became from “write once, run everywhere” to a platform where developers could create games, mobile apps and desktop apps but not everywhere.
But a day Adobe decide to collaborate with Microsoft to create a Flash Player with amazing performance on tablets and on desktop too, and that moment my brain started to imagine a new future, maybe impossible, maybe a nightmare or maybe a dream…come with me in this fantastic story!

We can start with Adobe side, they donate Flex framework to Apache foundation, so MXML, FalconJS, Blaze and so on are now in this great foundation where communities are working on the new release of Flex framework 4.8.
Adobe is working a lot on HTML5 and JS side to create new tools for designers and they are moving fast on mobile side too with Phonegap.
Adobe stuff are mainly (or trying to be) cross-platform, so contents made with Adobe solutions work on Android, iOS, Mac OS X and Windows.

In the other hand we have Microsoft with C# (that is powerful and easy to write for a Flash Platform developer with good skills in development), XAML (the Microsoft answer to Flex), WPF, XNA and Silverlight; an ecosystem dedicated mainly to Microsoft OS from desktop to XBox.
Microsoft is trying to promote JS on develop contents for its new operating system: Windows 8.
Microsoft has Expression Studio that is the “poor baby” for a web designer that is more comfortable with Photoshop, Illustrator, Flash so with the Creative Suite!

Last week everybody read about the Adobe and Microsoft partnership for delivering Flash Player on Windows 8 (desktop & metro), but if they are working on that, maybe a day they’ll talk about AIR… this is they key of the story.

Try to imagine.

Adobe has a total penetration of Flash Player on desktop, with AIR you can work easily on desktop and on iOS, Android and QNX OS (BlackBerry one) then they are working on new tools for the future of web on HTML 5, CSS3 and JS like Muse, Edge and Dreamweaver too.
Microsoft has a lot of money they don’t have a cross platform ecosystem (there are some third party solutions like Mono but are not the same), they have strong technologies and partnership (Nokia for example).

And what do you think will happen if Microsoft plans to buy Adobe?!

Imagine a day where a developer using Visual Studio and writing C# and XAML could define to export own project on desktop with AIR, or better on mobile OS or in a browser in HTML5 with the same (I mean the SAME) base of code, same tools of development and an amazing integrating workflow from the idea to the software delivery…so WOW!!!
Bringing the powerful of Microsoft and the smart technologies of Adobe could be an amazing opportunities for both companies, and for developers too, to innovate in the best way ever the multimedia era.

This could be a real dream… what is missing now, probably, is to find a driver that lead the multimedia scenario because everyday we receive tons of emails about new framework, new technologies, new programming languages and developers are scared to bring a direction because probably it will not be the right one, probably next week or next month they will have to study another one and another one again…

Dear reader, try to imagine a world where you can really focused on create the silver bullet software, without think which will be the new JS framework or which are the new features of the latest Flex release… a world where you have only to think about contents in the best… maybe it could be a dream or maybe could be a the best place to live… sorry… to code.

UPDATE

There is another fact that I remember only now… by the end of 2010 Adobe and Microsoft CEOs meet in Microsoft headquarters to talk about what?!
It could be another indication of my conspiracy theory… maybe we’ll have some surprises next year!

Silverlight on mobile vs (maybe) AIR mobile ?

I don’t write on Silverlight mobile version yet because I was waiting more news from MIX and I also talked with Italian Microsoft guys and others developers.

So, Silverlight will be out the second quarter of 2008 but with 1.0 version and if you take a look at desktop version you know that isn’t so powerful!
In the end of 2008 we could see 2.0 Beta version and finally in the second quarter of 2009 Silverlight 2 will install in mobile devices.
The last version in so interesting, they add a very good zoom functionality and they add .net framework built in the player.
Mobile version will be use in IE browser for PDA so probably the same way on Nokia, so the first question is:
Can I interact OS on Nokia and PDA to save and manipulate data like desktop version or I’ll have some security issues?

Another thing that I see is a good video look and feel, I’d like to know what kind of video files I could play on own mobile player.
It could be interesting how Microsoft decide to update own mobile player on devices…

I think that Adobe must start to take new way to deliver and help own developers to create mobile contents, we have a cool platform but with a lots limits and also there is a bad interaction with OS.

Sincerly I hope that Adobe could develop the AIR mobile version because with this technology we could take new market quotes and opportunities.
AIR is the new powerfull technology that helps developers and desginers to deliver own contents with a new interaction way, if you can create an online app with Flex and then porting it on desktop and finally porting it on own mobile device… that it could be COOOOOL!

My 2 cents

Feel free to comment and share your view!