Enable Editing and Debugging with VS Code

To view, edit, and debug code on an InterSystems server, the InterSystems ObjectScript extensions for VS CodeOpens in a new tab communicate with the server’s /api/atelier web application through the Web Gateway. Depending on your web server installation, additional web server configuration steps may be necessary to facilitate this communication:

If you are using Apache, it is usually unnecessary to perform any additional configuration to use VS Code. However, if your Apache installation does not allow WebSockets by default, you must configure it to do so in order to use the ObjectScript extension’s debugging tool. Refer to the Apache documentation for detailed guidance: https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.htmlOpens in a new tab
If you are using Nginx, modify your configuration as described in Additional Configuration Required to Use IDEs.
If you are using IIS, perform the configuration steps which are described in the sections which follow.

IIS: Disable the WebDAV Module

The IIS WebDAV module (if it is installed) interferes with the Web Gateway when both are enabled to handle communication for an InterSystems IRIS instance’s /api/atelier application. This application provides the connection between the instance and VS Code.

To use VS Code with an InterSystems IRIS instance, you must remove the WebDAV Handler Mapping and disable the WebDAV Module for the relevant path. Depending on your web server configuration, this relevant path may be the instance prefix path, /<instancePrefix>/api, or /<instancePrefix>/api/atelier.

You can perform these configurations using the Internet Information Services Manager, or by editing the applicationHost.config file to include <remove> directives within the <location> directive block for the relevant path ({path}) as in the following example:

<location path="{path}">
  <system.webServer>
    <modules>
      <remove name="WebDAVModule" />
    </modules>
    <handlers>
      <remove name="WebDAV" />
    </handlers>
  </system.webServer>
</location>

For detailed instructions on configuring IIS, refer to the IIS documentation: https://learn.microsoft.com/en-us/iis/get-started/introduction-to-iis/iis-web-server-overviewOpens in a new tab.

After making changes to the IIS configuration, restart IIS to ensure they take effect.

IIS: Enable the WebSockets Feature (for Debugging)

The debugging tool in VS Code requires a WebSockets connection to the InterSystems IRIS instance. Ensure that the IIS WebSocket Protocol feature is enabled by performing the following steps:

Open the Windows Features manager by searching for Turn Windows features on or off, or by opening the Control Panel and selecting Programs > Programs and Features > Turn Windows Features on or off.
Select Internet Information Services > World Wide Web Service > Application Development Features.
Select WebSocket Protocol, if it is not already selected.
Select OK.
Restart IIS to ensure all changes take effect.

IIS: Allow Double Escaping (to Access Certain Packages)

For any file with a name which begins with the % (percent) character followed by two hexadecimal digits (that is, numerals between 0 and 9 or letters between a and f), IIS interprets these first three characters as an encoded hexadecimal character by default. As a result, VS Code cannot view or edit such a file.

If you must view or edit such a file, you must configure IIS Request Filtering to Allow double escaping, either globally or for the specific IIS application location which corresponds with your instance. You can modify this setting by using the IIS Manager or the command line interface (see https://learn.microsoft.com/en-us/iis/manage/configuring-security/configure-request-filtering-in-iisOpens in a new tab) or by setting the attribute allowDoubleEscaping="true" for the appropriate <requestFiltering> element within the IIS configuration file (see https://learn.microsoft.com/en-us/iis/manage/configuring-security/use-request-filteringOpens in a new tab).

Windows Only: Update InterSystems IRIS Server Manager

Redirect Documentation Links to Documentation Website