Other<\/strong>, but it could be one of:<\/p>\n[Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, Other, Extension Packs]<\/pre>\nThe activationEvents<\/strong> section lists all the things that should cause VS Code to load the extension. By default, VS Code will only load an extension when something happens to warrant it. If you have no PowerShell code, then you don’t get the PowerShell extension, for example. The activationEvent<\/strong> added by yo code<\/strong> is :extension.sayHello<\/strong>. The first part, onCommand<\/strong>, means that when someone opens the command palette and runs the command helloWorld<\/strong>, the extension is called for the first time in that instance of vs code.<\/p>\nThe main<\/strong> property tells VS Code where to find the extension, in this case, .\/out\/extension<\/strong>. What this means is that you will need to have a JavaScript file in the directory out<\/strong> called extension.js<\/em>. If you have run the watcher task or the build task, then you should indeed have that as the ts<\/em> file will be compiled into the .js<\/em> file. The .js<\/em> file should also export a function called activate<\/strong>:<\/p>\n![\"C:\\Users\\ed\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\6-extension-js.png\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/c-users-ed-appdata-local-microsoft-windows-inetca-18.png\")
<\/p>\n
Back in the package.json<\/em> file, you will see the contributes<\/strong> section. In this example, there is just a single command.:<\/p>\n \"contributes\": {\r\n \"commands\": [\r\n {\r\n \"command\": \"extension.sayHello\",\r\n \"title\": \"Hello World\"\r\n }\r\n ]\r\n },<\/pre>\nThis has a single command here, but you could contribute multiple commands or something else such as a window. This is an example I used to create a window in another extension I wrote for VS Code:<\/p>\n
\"contributes\": {\r\n \"commands\": [\r\n {\r\n \"command\": \"armJsonOutline.showGraph\",\r\n \"title\": \"ARM: Show Dependency Graph\",\r\n \"when\": \"resourceLangId == 'json'\"\r\n },\r\n {\r\n \"command\": \"armJsonOutline.openArmOutline\",\r\n \"title\": \"ARM: Start Outliner\",\r\n \"when\": \"resourceLangId == 'json'\"\r\n },\r\n {\r\n \"command\": \"armJsonOutline.stopArmOutline\",\r\n \"title\": \"ARM: Stop Outliner\"\r\n },\r\n {\r\n \"command\": \"armJsonOutline.testExpression\",\r\n \"title\": \"ARM: Test Expression\"\r\n }\r\n ],\r\n \"views\": {\r\n \"explorer\": [\r\n {\r\n \"id\": \"armJsonOutline\",\r\n \"name\": \"ARM Template Outline\",\r\n \"when\": \"resourceLangId == 'json'\"\r\n }\r\n ]\r\n },\r\n \"menus\": {}\r\n },<\/pre>\nThe things to notice here are that the commands and views should only be visible when a JSON document is open, so, as well as the command definitions, I have also included a when<\/strong> property. This really contributes to the goal of having VS Code as lightweight as possible; if you don’t need something then, it isn’t loaded. This is a great benefit over Visual Studio where everything is loaded unless you explicitly disable it.<\/p>\nNow that the package.json<\/em> file has been discussed, you can explore the sample application. If you open the file src\/extension.ts<\/em> you will can see you first glimpse of TypeScript code:<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-44.png\")
<\/p>\n
There is function called activate<\/strong> which is being exported. This will be executed because in the package.json<\/em> file, you have:<\/p>\n\"main\": \".\/out\/extension\",<\/pre>\nIt will be called when someone runs the command sayHello<\/em>. When the activate<\/strong> function is called, debug line is logged, console.log<\/strong>, and then it registers a command using:<\/p>\nVS Code.commands.registerCommand<\/pre>\nThis takes two parameters, the first is the name of the command to register. In this case, it is extension.sayHello<\/strong>. The second parameter is a function that will get executed when the command is run. The sequencing is a little odd here but to clarify what happens:<\/p>\n\n- A user runs a command or event that is in the activationEvents<\/strong> section in the package.json <\/em>file.<\/em><\/li>\n
- If the activate<\/strong> function has not been executed since VS Code was launched, then activate<\/strong> is called.<\/li>\n
- The activate<\/strong> function then registers any commands it would like to and does any initialization work it needs.<\/li>\n
- If the command the user called is registered by the activate<\/strong> function, then that command itself is executed.<\/li>\n<\/ul>\n
This means you can have multiple commands all registered using the same activate<\/strong> function without having to pre-register them before the extension is required.<\/p>\nThen when the activate<\/strong> function returns, the registered handler is executed, because the user originally ran the extension.sayHello<\/strong> command:<\/p>\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/ts2.png\")
<\/p>\n
In the example, the command displays a message saying Hello World!. <\/em>I will change this to Hello Simple Talk<\/strong> and then press F5<\/strong> so VS Code should build and run the extension in a development version of VS Code.<\/p>\nOnce you start the development version, you can open the command palette and run Hello World<\/em>. When you do that, VS Code calls the activate<\/strong> function which registers the extension.sayHello<\/strong> command. When activate<\/strong> completes, the sayHello<\/strong> command is executed and displays the message Hello Simple Talk<\/em>.<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-45.png\")
<\/p>\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-46.png\")
<\/p>\n
Debugging<\/h2>\n
Even though the code that gets executed is that compiled from TypeScript to JavaScript, you can still debug the TypeScript using the debugger. You can set a breakpoint in the TypeScript function where you display the message box by either, highlighting the line you are interested in and choosing Toggle breakpoint <\/em>from the Debug<\/em> menu or pressing F9<\/strong>, or just clicking the space to the left of the line numbers.<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-47.png\")
<\/p>\n
When you run the extension under the debugger and execute Hello World<\/em>, the VS Code debugger stops at the breakpoint, and you can do the standard things like evaluating any variables or viewing a stack trace:<\/p>\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/ts3.png\")
<\/p>\n
This ability to execute JavaScript code and debug the TypeScript is made possible because, when the TypeScript compiler outputs the JavaScript file, it also outputs a map file which contains all the information the debugger needs to translate the JavaScript locations and objects back to the TypeScript locations and objects:<\/p>\n
![\"C:\\Users\\ed\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\12-javascript-map.png\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/c-users-ed-appdata-local-microsoft-windows-inetca-20.png\")
<\/p>\n
Extending the example and using tests<\/h2>\n
So far, the example doesn’t really do that much, so it\u2019s time to expand the extension to count the number of words in the active document. The first thing to do is to add a new command to package.json<\/em> by adding the extension.countWords<\/strong> to the commands<\/strong> array:<\/p>\n \"commands\": [\r\n {\r\n \"command\": \"extension.sayHello\",\r\n \"title\": \"Hello World\"\r\n },\r\n {\r\n \"command\": \"extension.countWords\",\r\n \"title\": \"Count Words\"\r\n }\r\n ] <\/pre>\nNote, the commands are configured with extension<\/strong>. This is effectively the namespace. To keep this from clashing with anything else, I normally use the name of the extension instead of extension<\/strong>. If you are going to publish your extension, you should choose a different prefix.<\/p>\nOnce you have a new command, you should also tell VS Code that it should call the activate<\/strong> function if the new command is called. Otherwise, unless someone happens to run Hello World<\/em>, the command won’t have been registered, and VS Code will show an error to the user. Update activationEvents<\/strong> so that it includes the new command:<\/p>\n \"activationEvents\": [\r\n \"onCommand:extension.sayHello\",\r\n \"onCommand:extension.countWords\"\r\n ],<\/pre>\nNow, you must implement the command, so go back to the src\/extension.ts<\/em> file. After registering extension.sayHello<\/strong>, add a new VS Code.commands.registerCommand<\/strong> for the new command. To test that package.json<\/em> has been set up correctly, just copy and paste helloWorld<\/strong> (changing the variable name that is returned from registerCommand<\/strong> so that you can save both of the subscriptions) and test it to make sure that when you call extension.countWords<\/strong>, you get a message box:<\/p>\n![\"C:\\Users\\ed\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\13-new-command.png\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/c-users-ed-appdata-local-microsoft-windows-inetca-21.png\")
<\/p>\n
Now you know that you have package.json<\/em> set up correctly, you can expand the code to read the current document, count the words, and display the word count:<\/p>\n if(vscode.window.activeTextEditor === undefined || \r\n vscode.window.activeTextEditor.document === undefined){\r\n return;\r\n }\r\n let text = vscoode.window.activeTextEditor.document.getText();\r\n \r\n function countWords(str) {\r\n \/\/from https:\/\/stackoverflow.com\/questions\/18679576\/counting-words-in-string\r\n return str.trim().split(\/\\s+\/).length;\r\n }\r\n vscode.window.showInformationMessage(`Document contains: ${countWords(text)} words`);<\/pre>\nThe code will first check to see if there is an active document. If there isn’t, then it will fail to read the text. If there is an extension that throws an exception, it doesn’t crash VS Code, but the user gets an error message to say the extension died which isn’t very nice. By using the when<\/strong> facility, you could just get the command to show when a document is chosen, but there is still a chance a user could choose the command and then close the active window.<\/p>\n\"commands\": [\r\n {\r\n \"command\": \"armJsonOutline.showGraph\",\r\n \"title\": \"ARM: Show Dependency Graph\",\r\n \"when\": \"resourceLangId == 'json'\"\r\n },<\/pre>\nThis would still throw an exception, so it\u2019s best to check that it is still valid:<\/p>\n
if(VS Code.window.activeTextEditor === undefined || \r\n VS Code.window.activeTextEditor.document === undefined){\r\n return;\r\n }<\/pre>\nThe next line grabs a copy of the text from the active window:<\/p>\n
let text = VS Code.window.activeTextEditor.document.getText();<\/pre>\nOnce it has the text, it uses a function downloaded from Stack Overflow to count the words:<\/p>\n
function countWords(str) {\r\n \/\/from https:\/\/stackoverflow.com\/questions\/18679576\/counting-words-in-string\r\n return str.trim().split(\/\\s+\/).length;\r\n }<\/pre>\nNote that this was straight JavaScript. You could turn it into a safer version if you add type information to it:<\/p>\n
function countWords(str : string) : number {\r\n \/\/from https:\/\/stackoverflow.com\/questions\/18679576\/counting-words-in-string\r\n return str.trim().split(\/\\s+\/).length;\r\n }<\/pre>\nYou now know that str<\/strong> is a string, and the function returns a number. Finally, it shows a message box with the results of calling the countWords<\/strong> function:<\/p>\nVS Code.window.showInformationMessage(`Document contains: ${countWords(text)} words`);<\/pre>\nYou can use ${}<\/strong> to embed TypeScript commands inside a string. This only works where you use backticks `<\/strong> to surround the characters.<\/p>\nIf you run this and open a document, you will get a message about how many words there are in the document:<\/p>\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-49.png\")
<\/p>\n
Unit Testing<\/h2>\n
Included in the sample extension are some tests in: src\/test\/extension.tests.ts<\/em>. If you take the code that counts the words in the document and make it testable by putting it into its own file which you could call from either the tests or the extension code, you could write some tests to verify that it works.<\/p>\nThe first thing to do is to create a new wordCounter.ts<\/em> file under src<\/em>. In this file, you will export the wordCounter<\/strong> function so that you can call it from other places. In TypeScript, if you do not export a function, it is like making it private to the file. Add this text to the new file:<\/p>\n'use strict';\r\n export function countWords(str : string) : number {\r\n \/\/from https:\/\/stackoverflow.com\/questions\/18679576\/counting-words-in-string\r\n return str.trim().split(\/\\s+\/).length;\r\n }<\/pre>\nIf you wanted to, you could have created a TypeScript \u2018class\u2019 to do this work for you. In this case, a \u2018function\u2019 is more than enough. Save the new file, and, if you have a watcher task running or you run the build command in the out<\/em> folder, you should see a wordCount.js<\/em> and map file created automatically:<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-50.png\")
<\/p>\n
Open the src\/tests\/extension.tests.ts<\/em> file and add a new suite<\/strong> at the bottom:<\/p>\nsuite(\"wordCounter Tests\", () => {\r\n \r\n }); <\/pre>\nTo use the wordCounter<\/strong> code, you must add an import <\/strong>to it under the other imports:<\/p>\nimport {countWords} from '..\/wordCounter';<\/pre>\nIn this case, you just want the single function, but you could import all the exported functions and classes from a file. You will note the ..\/<\/strong>. This is used because the tests are being compiled in a subdirectory of the src<\/em> directory, so the tests need to navigate up a level to get to the code. When you import the wordCounter<\/strong> function in the extension, because they are in the same folder, you won’t need the ..<\/strong> part.<\/p>\nNow that you have imported the code, you can add a test:<\/p>\n
test(\"3 words with funny separators\", () => {\r\n assert.equal(3, countWords('a\\rnew\\tword'));\r\n });<\/pre>\n <\/p>\n
You can run the tests by opening the command palette and running Tasks: Run Test Task<\/em> and choosing npm:test<\/em>. Hopefully, you should see the test passing:<\/p>\n![\"C:\\Users\\ed\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\16-wordCounter-tests.png\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/c-users-ed-appdata-local-microsoft-windows-inetca-22.png\")
<\/p>\n
You can now modify the actual code to use the new shared wordCounter<\/strong> function. Open sec\/extension.ts<\/em> and add this import <\/strong>underneath the existing VS Code import:<\/p>\nimport {countWords} from '.\/wordCounter';<\/pre>\nDelete the local function, and then the aliased function should already be available. If you have a build watcher, you will see if this has succeeded or if there were any errors:<\/p>\n
![\"C:\\Users\\ed\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\17-build-update.png\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/c-users-ed-appdata-local-microsoft-windows-inetca-23.png\")
<\/p>\n
Publishing the Extension<\/h2>\n
<\/p>\n
Now that you have the extension, you will want to share it with others. You have two choices: you can create a VSIX (deployment package) and keep it private, or you can publish it to the Visual Studio Marketplace to share it with the world. Either way, you will need the vsce command line tool, so install that using:<\/p>\n
npm install -g vsce<\/pre>\nvsce performs some basic checks. One of them is that the README.md<\/em> file doesn’t contain the default text, so delete it all and write a nice README<\/em> for your extension. When you are ready to run execute this from the same directory that holds package.json<\/em>:<\/p>\nvsce package<\/pre>\nIf this succeeds, you will get an extension-version.vsix<\/em> file which can be loaded into VS Code using the command Extensions: Install from VSIX<\/strong>.<\/p>\nTo publish to the marketplace, you will need a personal access token or PAT which you can get from VSTS. To find a PAT that can be used to publish your extension, you need to go to any VSTS account that you log in using the same email that you used to create the publisher account. When you open VSTS, click on your name icon in the top right corner and choose security:<\/p>\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-51.png\")
<\/p>\n
Then click on Personal Access Tokens<\/em> and Add<\/em>. You will see the Create personal access token<\/em> screen. Give it a name, a length of time the token lasts for and most importantly, choose All Accessible Accounts<\/em>, under the scopes you need, Marketplace (publish)<\/em>:<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-52.png\")
<\/p>\n
If you click Create Token<\/em> at the bottom of the page, you will be given a token. Make a note of it as you will need to re-generate a new one if you lose it.<\/p>\nWhen you run vsce publish<\/strong>, it will ask you for your Personal Access Token<\/em>. Add the token you just saved, and the extension should be published and available to everyone in the market place.<\/p>\nConclusion<\/h2>\n
VS Code is a refreshing development experience, and the ability to quickly write extensions is a real benefit. Many users are actively downloading extensions from the marketplace. If you write a useful extension, then it can potentially be used by a considerable amount of people easily and efficiently. TypeScript and JavaScript have been given quite a bad reputation, but they are reasonably straightforward languages with plenty of help and tutorials available online.<\/p>\n
References<\/h2>\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-38.png\")
<\/p>\n![\"C:\\Users\\ed\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\0-yoman.png\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/c-users-ed-appdata-local-microsoft-windows-inetca-16.png\")
<\/p>\n![\"\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/TS1.png\")
<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-40.png\")
<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-41.png\")
<\/p>\n![\"C:\\Users\\ed\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\3-adding-mocha-dependency.png\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/c-users-ed-appdata-local-microsoft-windows-inetca-17.png\")
<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-42.png\")
<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2018\/04\/word-image-43.png\")
<\/p>\n