How to start Using VsCode

Introduction

In the next few weeks, my coworkers are planning to start using VSCode to code with InterSystems' products. Among the many advantages of that, I would emphasize being able to connect with other technologies, such as GitHub, with ease. Besides, VSCode also offers an extensive extensions store, where you can find many free add-ons that make coding faster and more efficient. Last but not least, to conquer the heart of every developer, it is open source.

With that being said, let's start the tutorial. Feel free to skip some steps if you're comfortable doing them alone.

Step 1 - Download and install VSCode

Search for "VSCode download" or click this link to download from the official page. Select the correct installation for your computer and execute the file downloaded.


Once the executable runs, you will be requested to agree with the license, select a few preferences (which are very personal so I shall not extend this text talking about them), and install. 

 

Step 2 - Install InterSystems extensions

Open your VSCode on the extensions tab and search for ObjectScript Extension Pack on the marketplace.



Install the complete pack.

 

Step 3 - Configure your VSCode for your instances

Once you have the extensions installed, you should have an InterSystems tab. You can select it and click "+" on the servers section, as shown below, and you will be prompted for some information about the connection such as host, port, username, and password.

Otherwise, you can go to your VSCode general settings.json file, which you can find by clicking the "manage" gear   on the bottom left side of the screen, selecting configurations, and clicking the "Open Settings (JSON)"    on the top right side.

There, you can paste the following JSON fragment, editing it so it points to your instance.

"intersystems.servers": {
        "[YOUR SERVER NAME]": {
            "webServer": {
                "scheme": "http",
                "host": "127.0.0.1",
                "port": 53472
            },
            "username": "_system"
        }

Step 4.1 - Connect to a server and namespace to develop locally

Again on the InterSystems tab, select the Explorer section and click the "Choose server and namespace" button.

You should be prompted to select among the servers added on the last step, your username and password, and a namespace.

Next, still on the same tab you can use the Explore or the Projects section to choose classes and/or projects that you would like to export. If you choose this kind of development, you can open the exported files on a VSCode workspace and connect with GitHub, for instance.

Step 4.2 - Connect to a server and namespace to develop in the server (my preference)

Open the InterSystems tab on the servers section and choose a server.

You can choose a project and click the pencil to open it on your workspace in edit mode or click the eye to open it in read mode.

Likewise, you can select between the same options directly on the namespace to open all of its files in the workspace (my preference)

Either way, you might be prompted for a username and password once again. 

 

Step 5 - Coding

On the explorer tab, after the last step, you will find your workspace section to look like the image below.

You can create a file and new folders by clicking with the right button on your mouse on a directory, selecting "new file" and naming it with the pattern FOLDERNAME.FILENAME.cls. In other words, you should name the folders by separating names with dots. The name right before the last dot will be the actual file name and the name after the last dot should be the extension for COS files, cls.

For example, you can name your file like the image below, "folderone.foldertwo.filename.cls", inside the User folder, and click enter.

By doing that you should have the following directory and file automatically created.

Now, you are ready to code as you would in Studio.

Some more tips

- You can press Ctrl+Shift+V to open .int files.

- Be careful: unlike Studio, Ctrl+S in VSCode will compile the file besides saving it.

- Now I will show you the best feature I've met so far by coding with VSCode. This is pure gold. Imagine that you have a developer's instance for the first phases of a project, another instance for testing with your clients, and maybe even another one for production. It can be outrageous to migrate the files and changes between the instances in Studio. However, if you are using VSCode, it is quite simple.

On the Explorer tab, open the source and the target file. For example, if I have a file defining some persistent data, and I added some fields on my development server, and I would like to bring them to my production server, I will open the developer file and the production file for the same persistent data (There is a discussion about opening many servers or namespaces in the next topic).

Once they're both open, they will appear in the "Open Editors" section.

Select the source file with the right button on your mouse and click "Select to compare". Right-click the target file and choose "Compare with selected".
BAM! You will have this beautiful comparison file open, as shown below.

The bar on the right side of the screen shows the differences between the files, and you can use it to navigate synchronously through them. Red and green means that something differs in the files. Red means that there is some text on the source file that is not in the target. Green means there is some text in the target file that is not in the source. 

Click the arrows in the middle to bring the changes from the source to the target.

Also, click on the two-sided arrow button on the top right side corner of the screen to change the sides of the files: the source will be the target and vice versa.

Pressing Ctrl+S with this editor open will save and compile both files.

- You can open multiple instances and namespaces at once in your workspace, as long as your computer can handle it. However, just so you can have an idea, for the last few weeks I've been working with two heavy namespaces from different instances, Studio, Microsoft Teams (which is scandalously heavy), and two more apps to connect with database and APIs, all at once, with a computer with the configuration 8GB RAM and CPU 2.10 GHz. The only thing that sometimes got a little slow was Studio.

Further discussion

I would love to talk about debugging with VSCode. I still haven't found someone who honestly likes it better than Studio's debug tools. I, for instance, am not very familiar with using VSCode debugging tools with InterSystems products, and even though Studio is way heavier I still prefer to leave it open when I need to debug. How do you combine those technologies? Which tools do you prefer from each idle?