Server-Side Editing

Configuring for Server-Side Editing

First configure the intersystems.servers entry for your server, as described in Configuring a Server.

Next, create a workspace for editing code directly on the server by performing the following steps:

1. Open VS Code. You must perform the following steps starting with no folder or workspace open, so if a folder or workspace is already open, close it.

2. Open the Explorer view, if it is not already visible.

3. Click the button labeled Choose Server and Namespace in the Explorer view, as shown in the image below:

   

4. Pick the name of an existing server configuration from the list, or click the + (plus) button to create a new server configuration.

   

5. Enter login credentials, if prompted.

6. Choose a namespace from the list retrieved from the target server.

   

7. Choose an access mode (editable or read-only) from the list.

   

8. Choose the category of files to display (code files, web application files, or contents of a server-side project).

   

   • If you chose to show web application files, choose an optional web application to show files from:

     

   • If you choose to show a project’s contents, choose the project:

     

   • If you create your own filter of files to display, pick the filter options:

     

9. If you want to reopen this workspace in the future, select File > Save Workspace As... to save the details of this workspace as a .code-workspace file.

Note that the ObjectScript Explorer view is not visible in the InterSystems view container. Because the files listed in the Explorer view are all on the server, the ObjectScript Explorer is not needed for this configuration.

The .code-workspace file is a JSON file which you can edit directly, as described in Workspaces. 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 resources 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 string isfs which appears in the "uri" for folders configured for server-side editing is an abbreviation created by InterSystems which stands for InterSystems File Service. It implements the VS Code FileSystemProvider APIOpens in a new tab, which lets you make any remote location look like a local one. It works well for making artefacts in an InterSystems IRIS namespace look like local files.

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": {}
}

Workspaces can also consist of a mixture of server-side folders and local folders. Use the context menu’s Add Folder to Workspace... option to add a local folder.

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.

Configuring Storage for Folder-Specific Settings

When you use VS Code to edit source code on the client, the settings model allows you to specify folder-specific settings in a .vscode\settings.json file located in a workspace root folder. These settings take precedence when you work under that workspace root folder.

If you use an isfs-type workspace to operate directly in a namespace on a server, you need to configure that server to support storing and serving up the .vscode\settings.json file. The .vscode subfolder of a workspace root folder also stores folder-specific code snippets and debug configurations. These are available when using this configuration.

Use the Management Portal for your InterSystems IRIS instance to create a web applicationOpens in a new tab named _vscode on the server. Select System Administration > Security > Applications > Web Applications, then Create New Web Application:

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

Be sure to 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:

You can also 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

Web Application (CSP) Files

To edit web application files (also known as CSP files) on a server, configure the URI as follows:

isfs://myserver:xxx{csp_application}?csp

For example, the following URI gives you access to the server-side files of the /csp/user application. The csp query parameter is mandatory and the suffix on the server name must specify the correct namespace for the web application. For example:

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

Changes you make to files opened from this root folder of your VS Code workspace will be saved onto the server.

Filters and Display Options

The query string of the "uri" property accepts several parameters that control filtering and display of the server-side entities. The examples below access the USER namespace on the server whose definition is named ‘myserver’.

• isfs://myserver:user/?generated=1 shows generated files as well as not generated files

• isfs://myserver:user/?project=prjname shows only files in project prjname. Cannot be combined with any other parameter.

• isfs://myserver:user/?mapped=0 hides files that are mapped from a non-default database

• isfs://myserver:user/?filter=%Z*.mac,%z*.mac — a comma-delimited list of search options, ignoring type. The default is *.cls, *.inc, *.mac, *.int. To see all files, use *.

• isfs://myserver:user/Utils?filter=*.cls shows only .cls files within the Utils package (or packages with names which begin with the string Utils).

  Note:

  As suggested by the preceding example, the wildcard character (*) cannot be used in a medial position within a filter string (for example, to filter by both an initial package name string and a file type). In other words, isfs://myserver:user/?filter=Utils*.cls would filter for files with the literal name Utils*.cls.

The options generated and mapped can be combined with each other, and with filter.

To modify the query parameters or name of an existing workspace folder, run the Modify Server-Side Workspace Folder... command from the Command Palette or the Explorer context menu.

Advanced Workspace Configurations

This section gives examples of some more complex workspace definitions for server-side editing.

Use File > New File to create a new file. Add content similar to the following example. Note that “my-project” in the isfs:// URI, should be the same as the “name” property (that is, the root display name) of any local folder where specialized settings for the connection are being stored in a .vscode/settings.json file.

{
  "folders": [
    {
      "name": "my-project",
      "path": ".",
    },
    {
      "uri": "isfs://my-project",
      "name": "server"
    }
  ],
  "settings": {
  }
}

Save the file, giving it an arbitrary name with the extension .code-workspace. VS Code shows you a button with an offer to open this workspace. Select the button.

The next time VS Code starts, two folders appear in the root directory with the names described in the .code-workspace file. Expand the server folder to see code on the configured server and namespace, routines and classes in one place. You can now edit this code. If you have SourceControl class, it should be configured the way, to export files in the same location which used in VS Code workspace.

The following is an example which implements a connection to multiple namespaces on the same InterSystems IRIS server:

{
  "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,
    }
  }
}