Edit Code Directly on an InterSystems Server

Add a Virtual Folder to Your Workspace

To quickly create a virtual folder in your current workspace which accesses all the user-created classes and routines within a single namespace on your server, perform the following steps:

1. Navigate to the InterSystems view container by selecting the InterSystems button in the Activity Bar.

2. In the InterSystems Servers view, expand the server you want to connect to. If necessary, sign into the server.

3. Expand your target server’s Namespaces directory.

4. • To view or edit source code across an entire namespace:

     1. Hover over the target namespace to reveal its command buttons, as illustrated in the following image:

        

   • To view or edit source code for a single project only:

     1. Expand the directory for the namespace which contains the target project.

     2. Expand the Projects directory for that namespace.

     3. Hover over the target project to reveal its command buttons, as illustrated in the following image:

        

     For more information about projects, see Work with Projects.

5. Select the appropriate command button for your use case:

   • Select the edit (pencil) button to add a virtual isfs:// folder to your workspace. The isfs protocol allows you to make direct edits to the code on the server.

   • Select the view (eye) button to add a virtual isfs-readonly:// folder to your workspace. The isfs-readonly protocol allows you to view code on the server, but prevents you from making any changes to it.

   • Hold the Alt or Option key while selecting the edit or view button to add a folder that also gives you access to server-side web application files (such as .csp files).

   For an entire namespace, the virtual folder has a URI with the form isfs://server:namespace/ or isfs-readonly://server:namespace. For a virtual project folder, the URI has the form isfs://server:namespace/?project=projectName or isfs-readonly://server:namespace/?project=projectName.

   Note:

   The string isfs which appears in the URI for folders configured for server-side editing stands for InterSystems File Service. It is a simple protocol which was created by InterSystems to implement the VS Code FileSystemProvider APIOpens in a new tab. This API allows a remote location to be represented as a local one. It works well for making artefacts in an InterSystems IRIS namespace look like local files.

If you require more granular control over the contents of your virtual folder, see Configure a Custom Virtual Folder.

Once you have added a virtual folder, VS Code opens the Explorer view showing the added namespace. In the following image, the workspace includes the Sample and User packages in the src folder on the client, and the Sample and User packages in the USER namespace on the server, with read-only access:

When you add a virtual folder to an empty or unsaved workspace, VS Code stores configuration settings for this virtual folder within a temporary file. You can save these workspace settings for later access in an arbitrarily-named file with a .code-workspace extension. You can also configure workspace settings by modifying this .code-workspace file directly, as described in Editing the Workspace File.

Editing the Workspace File

When you use the ObjectScript extension to add a server-side virtual folder to an empty or unsaved VS Code workspace, the extension stores the configuration details in a temporary file. If you want to save a workspace configuration for later access, you can do so in an arbitrarily-named file with the .code-workspace extension.

The .code-workspace file is a JSON file which you can edit directly. What follows is a simple example:

{
  "folders": [
    {
      "name": "iris184:USER",
      "uri": "isfs://iris184:user"
    }
  ],
  "settings": {}
}

• The "name" property provides a name for this server-side folder.

• The "uri" property indicates the location of documents on the server. The supplied value has three components:

  • The first component can be either isfs or isfs-readonly. These values specify that the folder is on an InterSystems IRIS server. isfs-readonly specified read-only access.

  • The value following the / (forward slash) specifies the name of the server.

  • The value following the : (colon) specifies the namespace in lowercase characters.

• The "settings" object can contain any other settings you wish to configure for your workspace.

To add more root folders to your workspace, giving you access to code in a different namespace, or on a different server, use the context menu on your existing root folder to invoke the Add Server Namespace to Workspace... command. This command is also available in the Command Palette.

The example which follows describes a two-folder workspace in which the second folder gives read-only access to the %SYS namespace:

{
  "folders": [
    {
      "name": "iris184:USER",
      "uri": "isfs://iris184:user"
    },
    {
      "name": "iris184:%SYS (read-only)",
      "uri": "isfs-readonly://iris184:%sys"
    }
  ],
  "settings": {}
}

Root folders can be re-sequenced using drag/drop in the Explorer view, or by editing the order their definition objects appear within the "folders" array in the JSON.

Advanced Workspace Configurations

The following is a more complex example of a .code-workspace file:

{
  "folders": [
    {
      "name": "myapp",
      "path": ".",
    },
    {
      "uri": "isfs://myapp",
      "name": "server",
    },
    {
      "uri": "isfs://myapp:user",
      "name": "user",
    },
    {
      "uri": "isfs://myapp:%sys",
      "name": "system",
    },
    {
      "uri": "isfs://user@hostname:port?ns=%SYS",
      "name": "system (alternative syntax)",
    }
  ],
  "settings": {
    "files.exclude": {},
    "objectscript.conn": {
      "active": true,
      "username": "_system",
      "password": "SYS",
      "ns": "MYAPP",
      "port": 52773,
    }
  }
}

This example defines a workspace with the following features:

• The workspace contains multiple virtual folders, corresponding to multiple namespaces on the same InterSystems IRIS server.

• The connection settings for the server are defined at the workspace level in the "settings" section. Any other workspace-level settings would be defined in this section.

• The workspace includes a local folder with "myapp" defined as the root display name (the "name" property). This matches the "myapp" query in the isfs:// URI for one of the virtual folders. This correspondence allows you to maintain specialized “folder-level” settings for the virtual folder in a /.vscode/settings.json file in the local folder. See Configure an InterSystems Server to Maintain Folder-Specific Settings for more information.

Important:

Although technically possible, InterSystems strongly discourages users from combining server-side virtual folders and client-side local folders within the same workspace.

isfs://server:namespace{csp_application}?csp

"uri": "isfs://myserver:user/csp/user?csp"

Configure an InterSystems Server to Maintain Folder-Specific Settings

Within a VS Code workspace, settings which apply to a single root folder are defined in a settings.json file, placed in a /.vscode/ subfolder. These settings take precedence over settings defined .code-workspace for actions within that folder.

If you want to configure folder-specific settings for a server-side virtual folder (including code snippets and debugging configurations), you must configure the InterSystems server to serve a /.vscode/settings.json file.

Use the Management Portal for your target InterSystems IRIS server to create a web applicationOpens in a new tab named _vscode by performing the following steps:

1. Navigate to the Create New Web Application page (illustrated in the image below) from the Management Portal home page by selecting System Administration > Security > Applications > Web Applications, then Create New Web Application.

   

2. Enter the following values:

   • Name: —enter /_vscode

   • Description — a brief description

   • Namespace — select %SYS

   • Enable Application — select

   • Enable — select CSP/ZEN

   • Allowed Authentication Methods — select Password

   • CSP File Settings: Physical Path — enter a physical path appropriate for your platform and your installation folder

   • CSP File Settings: Web Settings — clear the Auto Compile option

3. Save the configuration.

If you have an isfs-type workspace root folder that connects to a namespace on this server as a user with the %DB_IRISSYS:READ privilege, you can now write and read folder-specific settings. The image below illustrates the location of folder-specific settings in the VS Code Settings Editor:

To create a folder-specific snippets file by selecting the Preferences: Configure User Snippets command:

To edit the server-side namespace-specific files for all namespaces directly through VS Code, add an isfs-type root folder with the following URI:

isfs://servername:%sys/_vscode?csp

For a single namespace (for example, USER) the URI would be as follows:

isfs://servername:%sys/_vscode/USER?csp