Remote Explorer

As proposed in vscode-remote-release#926, the Remote Explorer is now a dedicated view container in VS Code and remote extensions can contribute custom tree views to it by leveraging Tree View API.

The view container name for Remote Explorer is remote. Following snippet contributes a tree view in Remote Explorer

"views": {
  "remote": [
    {
      "id": "sshHosts",
      "name": "Targets (SSH)",
      "when": "config.remote.SSH.enableHostsExplorer",
    }
  }
}

Sections: Targets, Details and Help

There will be three major sections in the Remote Explorer: Remote Targets, Connection Details and Help section.

Targets/Details

To contribute tree views under Targets or Details section, the only thing you need to add on topis group property. For example, we register the SSH targets/connection tree view under Targets section:

"views": {
  "remote": [
    {
      "id": "sshHosts",
      "name": "Targets (SSH)",
      "when": "config.remote.SSH.enableHostsExplorer",
      "group": "targets"
    }
  }
}

To contribute tree views under Connection Details section:

"group": "details"

Tree views contributed to Targets will be positioned at the top of Remote Explorer by default. Tree Views in Details section will be positioned right after Targets.

We can also use syntax "{group_name}@{number}" to control the default order of tree views under the same section. For example, "group": "targets@1" will be positioned before "group": "targets@2".

Note that SSH Targets registers itself as targets@1.

Help

Help section is a shared tree view for all Remote extensions. The data for the Help section is from a new contribution point remoteHelp:

"contributes": {
  "remoteHelp": {
    "getStarted": "https://aka.ms/vscode-remote/ssh/getting-started",
    "feedback": "https://aka.ms/vscode-remote/ssh/provide-feedback",
    "documentation": "https://aka.ms/vscode-remote/ssh",
    "issues": "https://aka.ms/vscode-remote/ssh/issues"
  }
}

Remote Explorer will always position the Help section at the bottom of the view container. In a local window, if there are more than one remote extensions contributing remoteHelp, we will show a quick pick with the contributing extensions when users click on a Help entry

When a remote window is opened, it will directly open the help entry from the extension which contributes the active remoteName.

View contribution convention

We might want to have some conventions about when a view should be contributed to Remote Explorer. Current proposals from vscode-remote-release#926 are

• When the window is local
  • Remote extensions should contribute Targets
  • Remote extension should contribute Help entries
• When the window is remote
  • Remote extensions can contribute Connection Details by checking remoteName and remoteConnectionState
  • Remote extensions can contribute Targets only for remoteName they own

Icons, states and actions

To ensure a consistent experience across tree views contributed by different Remote extension, we may want to use the same set of icons (icons repo) and actions when appropriate. Icons/states/actions used in SSH Explorer now are

Host

VM Status	Tooltip	Icon
Running	VM is running	vm-running.svg
Active	VM is active	vm-active.svg
Starting	VM is starting	vm-pending.svg
Stopping	VM is stopping	vm-pending.svg
Stopped	VM was stopped	vm-stopped.svg
Default		vm.svg

Folder

Status	Tooltip	Icon
Active	{folder} on {host}	folder-active.svg
Default	{folder} on {host}	folder.svg

Actions

Action Title	Icon
Start VM	run.svg
Stop VM	primitive-square.svg
Connect to Host in New Window	empty-window.svg
Open on SSH Host in New Window	folder-opened.svg
Remove From Recent List	close.svg