Skip to main content

Configure the InterSystems VS Code Extensions

Visual Studio Code (VS Code) settings enable you to customize various aspects of its behavior. The InterSystems extensions provide settings used to configure VS Code for ObjectScript development.


Many available settings are general to VS Code, and you can learn about them in the Visual Studio Code DocumentationOpens in a new tab. The InterSystems Server Manager, InterSystems ObjectScript, and InterSystems Language Server extensions supply additional settings which you can use to define InterSystems IRIS servers and connections to those servers.

VS Code stores these settings at several levels:

  • User — User settings are stored in a file location specific to you and apply globally to any instance of VS Code or any VS Code workspace that you open.

  • Workspace — a workspace is a set of directories you want to use when you’re working on a particular project. Workspace settings are stored in a file inside the workspace directory structure and apply to anyone who opens the workspace. See Configure Your Workspace for an InterSystems Project.

  • Folder — If more than one folder is present in a workspace, you can select the folder where the settings file is stored by selecting from the Folder drop down list.

See the User and Workspace SettingsOpens in a new tab section of the VS Code documentation for details.

For a list of all the settings which the InterSystems extensions contribute, see the Settings Reference.

Configure Your Workspace for an InterSystems Project

VS Code has a concept of a workspaceOpens in a new tab, which is a set of directories you want to use when you’re working on a particular project. In the simplest setup when you are working within a single directory, a VS Code workspace is just the root folder of your project. In this case you keep workspace-specific settings in two files inside a .vscode directory located at the root of your project. Those two files are settings.json, which contains most configuration settings, and launch.json, which contains debugging configurations.


Here is the simplest settings.json file content for an ObjectScript project (connection details are managed by the InterSystems Server ManagerOpens in a new tab, as described in Configuring a Server):

    "objectscript.conn": {
        "server": "iris",
        "ns": "USER",
        "active": true

If you need ObjectScript compilation flags other than the default ones, add an objectscript.compileFlags property to settings.json (more compileFlags information is available on the settings reference page):

    "objectscript.conn": {
        "server": "iris",
        "ns": "USER",
        "active": true, 
    "objectscript.compileFlags": "cuk/compileembedded=1"


Here is the simplest launch.json file content, with which you can debug the method Test in the class Example.Service, passing 2 parameters as input (see Running and Debugging for more information):

    "version": "0.2.0",
    "configurations": [
            "type": "objectscript",
            "request": "launch",
            "name": "Example.Service.Test", 
            "program": "##class(Example.Service).Test(\"answer\",42)"

If you want to debug a running process, launch.json should have a section like this, which will present a dropdown menu of running processes:

    "version": "0.2.0",
    "configurations": [
            "type": "objectscript",
            "request": "attach",
            "name": "Example-attach-to-process", 
            "processId": "${command:PickProcess}"

Note that configurations is an array, so you can define multiple configurations and choose the one to use from a dropdown menu in the Debug pane.

Multi-Root Workspaces and Server-Side Editing

If your project requires more than a single root folder, you need to use a feature called multi-root workspaces. See Multi-Root WorkspacesOpens in a new tab in the VS Code documentation.

In this case settings are stored in a file with a .code-workspace file extension. This workspace file can be located anywhere. It defines what root folders the workspace consists of, and may also store other settings that would otherwise be stored in settings.json or launch.json. Settings in a root folder’s .vscode/settings.json or .vscode/launch.json will override those in the workspace file, so be careful to use one or the other unless you truly need to leverage this flexibility.

You can have a workspace file even if you are only working with a single root folder.


If you are editing server-side code you must use a workspace file.

To edit InterSystems ObjectScript extension settings in a .code-workspace file in VS Code, perform the following steps:

  1. Open the workspace using File > Open Workspace from File.

  2. Select File > Preferences > Settings (Code > Preferences > Settings on Mac).

  3. Select the Workspace tab.

  4. Search for objectscript: conn and click on Edit in settings.json. This opens the .code-workspace file for that workspace.

The InterSystems Objectscript extension uses the multi-root workspaces feature to support Objectscript development directly in namespaces on InterSystems servers.

Configuring a Server

To add an InterSystems IRIS server, select the plus sign (+) in the title bar of the InterSystems Server view. For more information on this view, see InterSystems Server View.

Add server icon in Tools view title bar

When prompted, provide the following values:

  • Name of new server definition — an arbitrary name to identify this server.

  • Description (optional) — a brief description of the server.

  • Hostname or IP address of web server — the host name or IP address of the web server that publishes the web services for your target InterSystems server through the InterSystems Web GatewayOpens in a new tab.

  • Port of web server — the port number at which your web server hosts your target InterSystems server.

  • Path prefix of instance (optional) — if you are connecting to your target InterSystems server using a web server that hosts multiple InterSystems servers, the URL component which precedes the application path to identify the target serverOpens in a new tab.

  • Username — the username VS Code should use when it authenticates to this server.

  • Confirm connection type — the protocol used for connections. Possible values are http and https.


    Additional configuration may be necessary if you want to establish an HTTPS connection using a self-signed certificate.

You can create a configuration for a server that is not currently running.

Once you have entered these values, the extension stores the server definition in your user-level settings.json file, and the server appears at the top of the Recent folder in the InterSystems Server view. See Editing a Server Configuration.

Editing a Server Configuration

If you need to modify a server configuration, perform the following steps:

  1. Select File > Preferences > Settings (Code > Preferences > Settings on Mac) from the menu.

  2. Select the User settings level.

  3. Select Extensions from the outline section of the editor pane.

  4. Select InterSystems Server Manager from the list to find the InterSystems Server Manager area of the edit pane, as illustrated in the following screen shot:

    Server manager settings section

  5. Select Edit in settings.json.

You can also access the settings.json file within the InterSystems view container: select the ... (ellipsis) button in the title bar of the Servers view, and then select Edit Settings.

Edit settings option in Servers ... menu

A server configuration in the settings.json file has the following structure, populated with the values you entered when you configured the server:

    "intersystems.servers": {
        "iris-1": {
            "webServer": {
                "scheme": "http",
                "host": "localhost",
                "port": 443
            "username": "_SYSTEM"

The components of this server definition are as follows:

  • "iris-1" — the arbitrary name to identify the InterSystems IRIS server.

  • "webServer" — the collection of properties which define the web server you use to connect to the InterSystems IRIS server through the InterSystems Web GatewayOpens in a new tab.

    • "scheme" — the protocol used for connections ("http" or "https").


      Additional configuration may be necessary if you want to establish an HTTPS connection using a self-signed certificate.

    • "host" — the host name or IP address for the web server.

    • "port" — the port number for the web server.

    • "pathPrefix" — where applicable, the directory path under which the web server publishes the target InterSystems IRIS server’s web services.

  • "username" — the username VS Code uses to authenticate to the server.

  • "password" — password for the specified username. For security reasons, InterSystems strongly recommends authenticating through VS Code instead of specifying passwords as plaintext within the settings.json server definition.

Establish an HTTPS Connection Using a Self-Signed Certificate

Your organization may issue self-signed certificates to facilitate HTTPS connections to development or testing servers.

In order for VS Code to allow an HTTPS connection to an InterSystems server using a self-signed certificate, perform either of the following configuration changes:

  • Within the VS Code User SettingsOpens in a new tab, set variables as follows:

    • "http.proxyStrictSSL": false

    • "http.proxySupport": "fallback" or "http.proxySupport": "off"

    Then, save the configuration and reload VS Code.


    This configuration disables certificate checking, and is therefore inappropriate for use outside of a secure private network.

  • Add the self-signed certificate to your operating system’s root certificates. (Refer to the documentation for your operating system for specific instructions about how to do this.) Then, reload VS Code.

Configuring a Server Connection

To establish a connection between a server and a client-side workspace location, perform the following steps:

  1. Open the folder where you want to store your client-side files.

  2. Select the InterSystems view container button generated description: objectscript button in the Activity Bar. This action opens a dialog that allows you to select an existing server to connect to or provide the information to configure a new server definition.

  3. Follow the prompts to select a server and a namespace.

Once you have selected a server and namespace, connection configuration is complete. VS Code adds the server and namespace to the status bar.

You cannot create a connection to an InterSystems IRIS server if the InterSystems IRIS server is not running.

Editing a Server Connection

If you need to modify an existing server connection, perform the following steps:

  1. Select File > Preferences > Settings (Code > Preferences > Settings on Mac) from the menu bar.

  2. Select the Workspace settings level.

  3. Search for objectscript: conn.

  4. Select Edit in settings.json.

A connection configuration in the settings.json file has the following structure, populated with the values you specified when you configured the connection:

"objectscript.conn": {
  "ns": "USER",
  "server": "iris-1",
  "active": true,

The components of this configuration are as follows:

  • "ns" — namespace to use on the server

  • "server" — server name, as specified in the server configuration

  • "active" — boolean value specifying whether the connection is active.

Add Custom Entries to the Server Actions Menu

Clicking on the server and namespace in the status bar opens a list of the actions you can take for this server, as illustrated in the following image:

Server actions menu

You can add custom entries to this list using the objectscript.conn.links configuration object. This object consists of key-value pairs where the key is the label displayed in the menu and the value is the URI the action opens. The following variables are available for substitution in the URI:

  • ${host} — the hostname of the connected server. For example: localhost

  • ${port} — the port of the connected server.

  • ${serverURL} — the full connection string for the server, including the protocol, <baseURL> for your instance, and path prefix. For example: http://localhost:443/pathPrefix

  • ${ns} — the namespace that you are connected to. The value is URL encoded. For example: %25SYS or USER

  • ${namespace} — The raw namespace parameter for the connection. For example, user

  • ${classname} — the name of the class which is currently open, or an empty string if the currently opened document is not a class.

  • ${classnameEncoded} — a URL encoded version of ${classname}.

  • ${project} — the name of the server-side project which is currently open, or an empty string if no project is open.

  • ${username} — the username for the user account you are currently using to connect to the server.

Here is an example of a server action configuration:

"objectscript.conn": {
    "links": {
        "Portal Explorer": "${serverUrl}/csp/sys/exp/%25CSP.UI.Portal.ClassList.zen?$NAMESPACE=${ns}"

The preceding server action configuration adds an entry to the Server Actions menu, as illustrated in the following image:

Server action menu with custom action

FeedbackOpens in a new tab