feat: add workspaceFile property to devcontainer.json for auto-open…

[briansilah]

Summary

• Adds a customizations.vscode.workspaceFile property to devcontainer.json that specifies a .code-workspace file to open automatically when connecting to a remote environment (Codespace, Dev Container)
• If the workspace file doesn't exist at connection time (e.g., still being generated by postCreateCommand), VS Code falls back to the folder and shows a warning notification
• Addresses the long-standing UX gap for monorepo teams that generate workspace files during lifecycle hooks

Fixes microsoft/vscode-remote-release#3665

📄 Full Spec Document — design rationale, architecture, edge cases, security, and compatibility analysis

Problem

When a Codespace or Dev Container opens, VS Code connects to the workspaceFolder specified in devcontainer.json. Many teams — particularly those with monorepos — generate .code-workspace files during lifecycle hooks (e.g., postCreateCommand). There is currently no way to tell VS Code to automatically open
that workspace file. Users must:

1. Wait for the Codespace to fully load (opening the default folder)
2. Manually navigate to find the .code-workspace file
3. Click "Open Workspace" which triggers a full window reload

This creates a poor first-run experience, especially for large monorepos where the default folder view is overwhelming without workspace scoping.

Solution

// devcontainer.json
{
  "workspaceFolder": "/workspaces/myproject",
  "postCreateCommand": "generate-workspace-file.sh",
  "customizations": {
    "vscode": {
      "workspaceFile": "myproject.code-workspace"
    }
  }
}

Path is resolved relative to workspaceFolder. Must end in .code-workspace (schema-validated). If the file doesn't exist yet, VS Code falls back to the folder with a sticky warning notification.

Schema Changes (IntelliSense support)

• extensions/configuration-editing/schemas/devContainer.vscode.schema.json — add workspaceFile under customizations.vscode (+ deprecated top-level matching existing pattern)
• extensions/configuration-editing/schemas/attachContainer.schema.json — add workspaceFile alongside workspaceFolder

Server Changes (workspace file fallback)

• src/vs/server/node/webClientServer.ts — check workspace file existence via fs.stat in _handleRoot; if missing, clear workspaceUri and set workspaceFileFallback flag in workbench configuration

Client Changes (notification plumbing)

• src/vs/workbench/browser/web.api.ts — add workspaceFileFallback to IWorkbenchConstructionOptions
• src/vs/workbench/contrib/remote/browser/remoteWorkspaceFileFallback.ts — new RemoteWorkspaceFileFallbackNotifier contribution showing warning on fallback
• src/vs/workbench/contrib/remote/browser/remote.contribution.ts — register the contribution at WorkbenchPhase.AfterRestored

Tests

• src/vs/server/test/node/webClientServer.test.ts — 5 tests for server-side fallback logic
• src/vs/workbench/contrib/remote/test/browser/remoteWorkspaceFileFallback.test.ts — 5 tests for notification contribution

Data Flow

Server (webClientServer.ts)
→ receives --default-folder + --default-workspace from devcontainer CLI
→ fs.stat on workspace file
→ EXISTS: workspaceUri set → client opens workspace directly
→ MISSING: workspaceUri cleared, workspaceFileFallback=true → client opens folder + warning

Out of Scope (future work)

• Dev Container CLI: needs to read customizations.vscode.workspaceFile and pass --default-workspace to the server
• Glob support: e.g., "workspaceFile": "*.code-workspace" — deferred for simplicity
• File watcher: detect workspace file appearing after connect and offer to reopen

Test Plan

• Open a devcontainer.json in VS Code — verify IntelliSense shows workspaceFile under customizations.vscode with description and .code-workspace pattern validation
• Start VS Code server with --default-folder /tmp/test --default-workspace /tmp/test/missing.code-workspace — verify it opens the folder and shows a sticky warning notification
• Create a valid .code-workspace file at the path and restart — verify it opens the workspace file directly with no notification
• node test/unit/node/index.js --run out/vs/server/test/node/webClientServer.test.js — 5/5 pass
• node test/unit/browser/index.js --browser webkit --run out/vs/workbench/contrib/remote/test/browser/remoteWorkspaceFileFallback.test.js — 5/5 pass

[vs-code-engineering]

📬 CODENOTIFY

The following users are being notified based on files changed in this PR:

@bpasero

Matched files:

• src/vs/workbench/browser/web.api.ts

[Copilot]

Pull request overview

This PR adds support for automatically opening a .code-workspace file in remote environments (Dev Containers, Codespaces) by introducing a workspaceFile property in devcontainer.json. When the specified workspace file doesn't exist at connection time, VS Code falls back to opening the folder and displays a warning notification to the user.

Changes:

• Added workspaceFile schema property to devcontainer.json (both in customizations.vscode and as deprecated top-level property)
• Implemented server-side workspace file existence check with fallback logic in webClientServer
• Added workspaceFileFallback flag to IWorkbenchConstructionOptions API
• Created RemoteWorkspaceFileFallbackNotifier contribution to display warning notification
• Added comprehensive test coverage for both server-side and browser-side logic

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
extensions/configuration-editing/schemas/devContainer.vscode.schema.json	Added workspaceFile property under customizations.vscode with pattern validation and deprecation notice for top-level property
extensions/configuration-editing/schemas/attachContainer.schema.json	Added workspaceFile property to attach container schema with pattern validation
src/vs/server/node/webClientServer.ts	Implemented workspace file existence check using fs.promises.stat, with fallback to folder URI and flag propagation
src/vs/workbench/browser/web.api.ts	Added workspaceFileFallback optional boolean property to IWorkbenchConstructionOptions interface
src/vs/workbench/contrib/remote/browser/remoteWorkspaceFileFallback.ts	Created notification contribution that displays sticky warning when workspace file fallback occurs
src/vs/workbench/contrib/remote/browser/remote.contribution.ts	Registered RemoteWorkspaceFileFallbackNotifier with WorkbenchPhase.AfterRestored
src/vs/server/test/node/webClientServer.test.ts	Added comprehensive server-side tests for workspace file fallback logic
src/vs/workbench/contrib/remote/test/browser/remoteWorkspaceFileFallback.test.ts	Added browser-side tests for notification behavior under various conditions

[briansilah]

@microsoft-github-policy-service agree company="Microsoft"