Edit Code from a Client File System

This page describes how to use Visual Studio Code (VS Code) to edit source code files which are stored on a local or remote client file system and then deploy that code on your InterSystems® server. Compared with server-side editing, client-side editing is preferable in situations where you want to maintain, test, and source control a working copy of your code outside of the production server (or servers) where the code will ultimately be deployed.

The instructions which follow assume the following:

you have chosen a folder where you intend to store your source code files, and you have opened it as a workspace folder in VS Code.
(unless you have deployed your server as a Docker Compose service) you have already defined a connection profile for your server using the InterSystems Server Manager extension for VS Code.

Connect a Server to a Client-Side Workspace describes how to initialize the connection between a workspace folder and your InterSystems server using the InterSystems ObjectScript extension for VS Code. Once you have established a connection, you can export source code files from the server and make edits as needed.

By default, the extension synchronizes the code on your server to match any changes that you make to the contents of your client-side workspace folder while VS Code is open. Refer to Import Edits into the Server for instructions about how to modify this default setting, and how to manually import and compile code from your client-side workspace into the server.

For instructions on how to test and debug your code using the InterSystems ObjectScript Extension Pack for VS Code, refer to the Develop ObjectScript Unit Tests page and the Run and Debug Your ObjectScript Code page, respectively.

Important:

If you decide to edit the code for your project on the client side, remain consistent. Do not make edits directly on the server as well, as doing so introduces considerable risks: client-side and server-side changes may conflict and result in lost work; server-side edits may not be tracked by your client-side source control solution.

Connect a Server to a Client-Side Workspace

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

Open the folder where you want to store your client-side files.
Navigate to the InterSystems view container by selecting the InterSystems button in the Activity Bar.
Select the Choose Server and Namespace button within the InterSystems ObjectScript Explorer view or the InterSystems Projects Explorer view. (See Work with Projects for more information about projects.)
Use the menu to select an server from the list of existing InterSystems server connection profiles. Type + to add a new server connection profile.
Follow the prompts to sign into a server and select a namespace.

Alternatively, you can connect a client-side workspace to a server by invoking the ObjectScript: Connect Folder to Server Namespace command from the Command Palette and following the prompts provided.

This procedure creates a /.vscode/settings.json file in your workspace’s root-level folder (if it does not already exist), and appends an objectscript.conn object to this settings file for the server and namespace you have selected. The next time you open this workspace, VS Code will attempt to reconnect to this server and namespace. This procedure also adds the server and namespace to the status bar.

Edit Connection Settings (the settings.json File)

When you connect a server to a client-side workspace folder using the ObjectScript extension, the extension creates a /.vscode/settings.json file (if it does not already exist) and appends an objectscript.conn object to this settings file which describes this connection. In a simple case where a workspace folder is connected to a single InterSystems server, the settings.json file may look like this:

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

In most cases, it is sufficient to allow the ObjectScript extension to manage connections between your workspace and your InterSystems servers. In some cases, however, further configuration may be necessary. For example, you may wish to specify ObjectScript compilation flags for the server other than the default ones. You can perform many such configurations within the VS Code Settings Editor: select the tab for your workspace folder and then navigate to the Extension settings for the InterSystems ObjectScript extension.

Alternatively, you can modify the settings.json file directly. For example, to specify custom ObjectScript compilation flags, you would add an objectscript.compileFlags property as follows:

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

You can find more information about objectscript.compileFlags and other available settings on the Settings Reference page.

Export Code from the Server

To perform client-side edits to source code that exists on the server, export copies of source code files to your client-side workspace by performing the following steps:

If you have not already done so, connect your InterSystems server to a client-side workspace folder.
Navigate to the InterSystems view container by selecting the InterSystems button in the Activity Bar.
Within the ObjectScript Explorer view, locate and select the document or documents that you want to export from the server.
Right-click on your selection and select Export from the context menu.

Alternatively, you can export files by issuing the ObjectScript: Export Code from Server command from the Command Palette, and then selecting the desired files from the menu.

By default, the export command copies files into a /src/ subfolder within your workspace’s root folder. You can change this using the objectscript.export.folder setting. Refer to the InterSystems ObjectScript section of the Settings Reference for information about this and other settings which configure the behavior of the export command.

Note:

The ObjectScript extension can import documents which encode line endings using either the LF or CRLF control character sequence. However, when the extension retrieves a document from the server to display it in VS Code or to export it into a client-side workspace, it always uses LF line endings.

If you are using a client-side source control system, InterSystems recommends configuring how it handles line endings to accommodate this export behavior.

Import Edits into the Server

By default, the ObjectScript extension automatically synchronizes your InterSystems server to reflect any changes you make to files within the client-side workspace folder that it is connected to. The extension imports and compiles all changes that you make to those files within VS Code itself as well as all changes that you make to those files using other applications while VS Code is open (for example, by deleting a file using your operating system’s file browser or the rm shell command).

Note:

You can configure when the extension automatically synchronizes changes to client-side files by editing the objectscript.syncLocalChanges setting. By default, the value of this setting is "all", synchronizing all changes. When set to "vscodeOnly", the extension only synchronizes changes that you make within VS Code. When set to "none", the extension does automatically synchronize any changes.

You can configure whether or not the extension compiles changes automatically when you save them using the objectscript.compileOnSave setting.

When it is necessary to import code manually from a client-side workspace to a connected InterSystems server, you can do so by performing the following steps:

If you have not already done so, connect your workspace to the InterSystems server where you want to import your code.
Navigate to the Explorer view container by selecting the Explorer button in the Activity Bar.
Right-click on the file or folder which contains the code you want to import to access the context menu.
Select one of the following options from the context menu:
- Import and Compile — Imports the code onto the server and then attempts to compile it.
- Import Without Compilation — Imports the code onto the server, but does not attempt to compile it.

Tip:

By default, when you trigger the import of a file which you have modified, the ObjectScript extension prompts you to confirm that you want to overwrite the version of the file on the server. However, usually when you decide to edit code on the client-side, it is because you intend for the client-side files to act as the source of truth. In such circumstances, this safeguard is unnecessary and potentially risky: if you decline to overwrite the server-side version of a file by mistake, you could accidentally discard your work. To disable this prompting, change the objectscript.overwriteServerChanges setting to true.

Work with Other Document Types

In addition to code files such as classes and routines, the InterSystems ObjectScript extension for VS Code also supports client-side editing for other types of documents, including InterSystems IRIS Business Intelligence folder itemsOpens in a new tab (.dfi), data lookup table filesOpens in a new tab (.lut), and user-added file types.

The ObjectScript Explorer makes these documents available for export within a connected server-namespace’s Other directory. By default, the ObjectScript extension exports these documents into the connected client-side workspace folder’s /src/ subfolder, alongside other file types. If you set the objectscript.export.addCategory setting to true, the ObjectScript extension exports these documents into subfolders nested within the /src/ folder: ./src/dfi/ for .dfi files, ./src/oth/ for all others. The ObjectScript extension organizes .dfi files further when objectscript.export.atelier is set to true. For more information about this and other export settings, refer to the InterSystems ObjectScript settings reference.

You can import these documents from your client-side workspace as easily as you import other types of files. The ObjectScript extension imports .dfi files from a workspace folder onto the server using a name which matches the objectscript.export settings that you specify. When the extension imports any other supported document type from a workspace folder onto the server, it uses the last part of the file’s path on the client file system as the name of the file on the server. For example, a file with the client-side path /src/other/testalerts.lut would be imported onto the server as testalerts.lut.