Connect a Workspace to Your InterSystems Server

Once you have defined a connection profile for your InterSystems® server, you can connect to the server to your workspace using the InterSystems ObjectScript extension for Visual Studio Code (VS Code).

The procedures for connecting vary depending on whether you are setting up your workspace for client-side editing or server-side editing. Comparing Client-Side and Server-Side Workspaces helps you decide which workflow and workspace configuration is appropriate for your use case. You can then proceed to the instructions which correspond to your chosen configuration.

Regardless of your chosen configuration, the InterSystems Server Manager provides a common mechanism for authenticating the connection to the an InterSystems which is common to both workflows. Sign into a Server describes that mechanism.

Note:

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

Compare Client-Side and Server-Side Workspaces

All editing in VS Code takes place within a workspace. However, the structure and contents of your workspace will vary depending upon whether you intend to perform client-side or server-side edits.

With client-side editing, source code files are either created in a filesystem location on the client machine or they are exported from an InterSystems server to the client’s local filesystem location and then edited there. Edited code is then imported into an InterSystems IRIS server, where it can be compiled, run, and debugged. Because all client-side edits are saved locally, a client-side editing configuration is recommended if you use a local version control system.
With server-side editing, source code files can be edited directly on the InterSystems IRIS server. VS Code’s multi-root workspace featureOpens in a new tab allows you to edit source files stored within different namespaces and even different servers simultaneously. Edits made on the server-side can be run and debugged on the server immediately. A server-side editing configuration is recommended if your source code is managed by a server-side source control solution (see Integrating InterSystems IRIS with Source Control SystemsOpens in a new tab for more information).

Note:

If you are migrating from InterSystems Studio, you may prefer to use server-side editing in VS Code, which mirrors the editing workflow in Studio.

Important:

InterSystems strongly discourages performing both client-side and server-side editing within a single workspace. Doing so introduces considerable risks: client-side and server-side changes may conflict; client-side edits may not be tracked by server-side source control solutions, or vice versa.

Client-Side: Single-Root, Local Folder

When you perform client-side editing—that is, when you work on a project by editing copies of source code files which are stored on your client’s local filesystem—it usually makes the most sense to collect (and source control) all files associated with a project within a single local directory. Accordingly, a workspace which is configured for client-side editing usually consists of a single root folder, corresponding to that local directory.

Settings for such single-root workspaces can be maintained in two files, stored in a /.vscode/ subfolder within the root folder:

/.vscode/settings.json, for general settings. The ObjectScript extension creates this file when you connect a server, if it does not already exist; refer to Editing the settings.json File section which follows, .
/.vscode/launch.json, for debugging configurations. See Run and Debug Your ObjectScript Code for information about how to use this file.

When you open a folder in VS Code (using the File > Open Folder... menu option, for example), VS Code checks for the existence of these files within a /.vscode/ subfolder and attempts to initialize any settings it finds within them. This means that once you have defined a connection to an InterSystems server within a local workspace folder’s /.vscode/settings.json file, that connection is made available whenever that folder is open as the current VS Code workspace.

See Edit Code Locally on Your Client Machine to connect a local workspace folder to an InterSystems server and get started with client-side editing.

Server-Side: Multi-Root, Virtual Folders

On the other hand, server-side editing involves enacting changes to code directly on the server. This may be preferable in situations where source control solution interfaces directly with your server.

An InterSystems server provides access to a set of code documents at a URI which uses either the isfs:// or isfs-readonly:// protocol. Leveraging VS Code’s multi-root workspace feature, the InterSystems ObjectScript extension represents this access to server-side documents as a virtual root folder within the workspace.

Information about the virtual folder or virtual folders which comprise a given server-side workspace can be saved locally as a file with the .code-workspace extension, so that the workspace can be recreated in a latter session (using the File > Open Workspace from File... menu option, for example). Other workspace settings are also stored within the .code-workspace file. See Editing the Workspace Settings File for further details.

Note:

It is still possible to define folder-level settings within a multi-root workspace by defining /.vscode/settings.json or /.vscode/launch.json files within a folder. However, keep in mind that folder-level settings will override settings in a workspace-level .code-workspace file, and conflicts between related settings may lead to unexpected behavior.

If you wish to configure folder-level settings for a server-side virtual folder, additional steps are required: see Configure an InterSystems Server for Folder-Specific Settings.

See Edit Code Directly on an InterSystems Server to add a virtual folder to your workspace and get started with server-side editing.

Sign into a Server

Whether you are editing on the client-side or server-side, the InterSystems Server Manager brokers the process of authenticating and connecting to your InterSystems servers through the authentication provider it implements, InterSystems Server Credentials.

You can initiate a connection with an InterSystems server by expanding a server entry within the InterSystems Servers tree view. Alternatively, you can by connecting a server namespace using the ObjectScript Explorer or the InterSystems Projects Explorer, or by invoking analogous commands using the Command Palette), you must perform the following steps:

VS Code displays a dialog requesting permission to connect, such as the one illustrated in the following image:
Note that depending on the action which initiated the connection attempt, this dialog may name a different ObjectScript extension pack extension. Select Allow to allow the extension to connect.
If the intersystems.servers connection profile for the server which you are connecting to does not specify a username, provide one in response to the prompt to do so.
Provide the password for the specified user when prompted, as illustrated in the following image:
After you type in your password:
- Press ‘Enter’ to authenticate your connection to the InterSystems server for this session only. (VS Code will prompt you
- Select the key button to save it securely in your workstation’s operating system keychain. This allows InterSystems Server Credentials to retrieve the password and authenticate your connection to the InterSystems server during subsequent VS Code sessions; it will not be necessary to reenter it.
  
  Important:
  
  This is the recommended method for storing and managing your InterSystems server passwords. While InterSystems Server Manager also supports storing passwords in plaintext in the user-level settings.json file’s server connection profiles, this method is insecure.

Manage Signed-In Accounts

Select the Accounts generated description: accounts button button in the VS Code Activity Bar to manage currently signed-in InterSystems server accounts.

generated description: authprov accountsmenu

For each currently signed-in account, the Accounts menu provides you with the following options:

Select Manage Trusted Extensions to remove an extension from the list of extensions which you have previously allowed to use these account credentials.
Select Sign Out allows you to sign out of this account.

Note:

By default, InterSystems Server Credentials provides you the option to delete the password for an account when you sign out. To modify this behavior, change theintersystemsServerManager.credentialsProvider.deletePasswordOnSignout setting.