From 86170d0fa03f1658157de566e9a4f13348ab569d Mon Sep 17 00:00:00 2001 From: Guanzhou Date: Thu, 24 Sep 2026 14:05:08 -0400 Subject: [PATCH] Simplify VS Code setup caption and fix extension troubleshooting The caption promised an install prompt that never shows on managed devices, and the guide's recovery steps didn't cover old extension versions, --force, or the reload needed after updating. --- app/components/QuickStartTabs.tsx | 19 ++++--------------- app/page.tsx | 2 -- app/services/articleService.ts | 9 +++++---- app/services/externalLinks.ts | 3 --- tests/quickStart.test.ts | 20 ++++++++++++-------- 5 files changed, 21 insertions(+), 32 deletions(-) diff --git a/app/components/QuickStartTabs.tsx b/app/components/QuickStartTabs.tsx index 97e1f1b..836841d 100644 --- a/app/components/QuickStartTabs.tsx +++ b/app/components/QuickStartTabs.tsx @@ -7,7 +7,6 @@ import CommandSnippet from "./CommandSnippet"; type QuickStartTabsProps = { dockerCommand: string; vscodeDeepLinkUrl: string; - vscodeMarketplaceUrl: string; dockerDocsUrl: string; vscodeDocsUrl: string; }; @@ -22,7 +21,6 @@ type TabId = (typeof TABS)[number]["id"]; export default function QuickStartTabs({ dockerCommand, vscodeDeepLinkUrl, - vscodeMarketplaceUrl, dockerDocsUrl, vscodeDocsUrl, }: QuickStartTabsProps) { @@ -145,25 +143,16 @@ export default function QuickStartTabs({ id="quickstart-vscode-setup-caption" className="mt-3 text-sm leading-6 text-gray-400" > - Requires{" "} + Don't have VS Code?{" "} - VS Code - - . You may be prompted to install the{" "} - - DocumentDB extension - - . + Download it + {" "} + first.

When setup finishes, select Open Connection. diff --git a/app/page.tsx b/app/page.tsx index ccd5d03..dc1b157 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -3,7 +3,6 @@ import Link from "next/link"; import QuickStartTabs from "./components/QuickStartTabs"; import { documentdbKubernetesOperatorQuickStartUrl, - documentdbVsCodeExtensionMarketplaceUrl, documentdbVsCodeLocalQuickStartDeepLink, } from "./services/externalLinks"; import { getMetadata } from "./services/metadataService"; @@ -370,7 +369,6 @@ export default function Home() { diff --git a/app/services/articleService.ts b/app/services/articleService.ts index e499ce1..6feedbd 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -643,7 +643,7 @@ Install the extension from the VS Code marketplace, or run: code --install-extension ms-azuretools.vscode-documentdb \`\`\` -If VS Code prompts you to reload after installation, do that before creating a connection. +To update an older install, add \`--force\`; without it the command keeps the version you have. Reload VS Code after installing or updating, because the running window keeps using the previous version until then. ## Set up DocumentDB Local @@ -652,7 +652,7 @@ Use guided setup to let the extension provision DocumentDB Local and save its co 1. Open setup using any of these: - Select the DocumentDB icon in the activity bar, expand **Your own DocumentDB** in the Connections view, and select **Set up DocumentDB Local**. - Run **DocumentDB: Set up DocumentDB Local** from the Command Palette. - - Open \`vscode://ms-azuretools.vscode-documentdb/local\` from your browser and confirm the prompts. If the extension is not installed, VS Code offers to install it first. This needs extension version 0.10.1 or later. + - Open \`vscode://ms-azuretools.vscode-documentdb/local\` from your browser and confirm the prompts. This needs extension version 0.10.1 or later, so install or update the extension first; the link cannot always install it for you. 2. On the **Introduction** step, select **Continue**. Nothing is downloaded or created until the next step. 3. On the **Configure** step, review the defaults and select **Start DocumentDB Local**. The defaults give you an available port (starting at \`10260\`), generated credentials, the \`latest\` official image, and optional sample data. Expand the advanced options to set the port, image tag, or credentials yourself. 4. Wait for setup to finish. The extension creates a container named \`vscode-documentdb-local\` with a persistent volume, then waits until the database accepts connections. @@ -723,8 +723,9 @@ After the connection works, the extension can help you continue without leaving If setup or the connection does not work on the first try: -- If the browser link does nothing, confirm the extension is installed and up to date, then run **DocumentDB: Set up DocumentDB Local** from the Command Palette instead -- If VS Code reports **No extension gallery service configured**, it could not reach a marketplace to install the extension for you. On managed devices that use a private marketplace, this can happen when the link is also what starts VS Code. Open the link again once VS Code has loaded, or install the extension yourself with \`code --install-extension ms-azuretools.vscode-documentdb\` and then open the link again +- If the browser link does nothing, confirm VS Code is installed and that you allowed the browser to open it. If VS Code opens but setup does not start, install or update the extension, reload VS Code, and open the link again, or run **DocumentDB: Set up DocumentDB Local** from the Command Palette instead +- If VS Code reports that **a DocumentDB deep-link was opened without a connection string**, the extension is older than 0.10.1. Run \`code --install-extension ms-azuretools.vscode-documentdb --force\`, reload VS Code, and open the link again +- If VS Code reports **No extension gallery service configured**, or nothing happens when the extension is missing, the link could not install it for you. This is common on managed devices that use a private marketplace. Install the extension yourself with \`code --install-extension ms-azuretools.vscode-documentdb\`, then open the link again - If setup reports that Docker is unreachable, fix what it names (Docker not running, or Docker set to Windows containers rather than Linux) and select **Continue setup**; nothing has been created at that point - Verify the extension is installed and reload VS Code if the DocumentDB view does not appear - Confirm your local DocumentDB instance is actually running before you connect diff --git a/app/services/externalLinks.ts b/app/services/externalLinks.ts index 7a3ada9..e1070b7 100644 --- a/app/services/externalLinks.ts +++ b/app/services/externalLinks.ts @@ -14,8 +14,5 @@ export const documentdbKubernetesOperatorQuickStartUrl = export const documentdbKubernetesOperatorGitHubUrl = 'https://github.com/documentdb/documentdb-kubernetes-operator'; -export const documentdbVsCodeExtensionMarketplaceUrl = - 'https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb'; - export const documentdbVsCodeLocalQuickStartDeepLink = 'vscode://ms-azuretools.vscode-documentdb/local'; diff --git a/tests/quickStart.test.ts b/tests/quickStart.test.ts index 202c9ae..b96d35d 100644 --- a/tests/quickStart.test.ts +++ b/tests/quickStart.test.ts @@ -9,10 +9,7 @@ import { vscodeExistingConnectionSectionTitle, } from '../app/lib/docsAnchors'; import { getArticleByPath } from '../app/services/articleService'; -import { - documentdbVsCodeExtensionMarketplaceUrl, - documentdbVsCodeLocalQuickStartDeepLink, -} from '../app/services/externalLinks'; +import { documentdbVsCodeLocalQuickStartDeepLink } from '../app/services/externalLinks'; const html = renderToStaticMarkup(createElement(Home)); const cardStart = html.indexOf('id="run-with-docker"'); @@ -137,10 +134,12 @@ describe('homepage local quick start', () => { const captionStart = guided.indexOf('id="quickstart-vscode-setup-caption"'); const caption = guided.slice(captionStart, guided.indexOf('

', captionStart)); - expect(caption).toContain('Requires'); - expect(caption).toContain('href="https://code.visualstudio.com/"'); - expect(caption).toContain('You may be prompted to install'); - expect(caption).toContain(`href="${documentdbVsCodeExtensionMarketplaceUrl}"`); + // One click covers VS Code with or without the extension; only VS Code itself must come first. + expect(caption).toMatch( + /Don't have VS Code\? ]*href="https:\/\/code\.visualstudio\.com\/">Download it<\/a> first\./, + ); + expect(caption).not.toContain('marketplace.visualstudio.com'); + expect(caption).not.toContain('vscode:extension/'); expect(guided).not.toContain('>Install the extension { expect(guideContent).toContain('DocumentDB: Set up DocumentDB Local'); expect(guideContent).toContain('No extension gallery service configured'); expect(guideContent).toContain('code --install-extension ms-azuretools.vscode-documentdb'); + // Without --force the CLI keeps an older version, and old versions reject the /local link. + expect(guideContent).toContain('code --install-extension ms-azuretools.vscode-documentdb --force'); + expect(guideContent).toContain('opened without a connection string'); + expect(guideContent).toContain('Reload VS Code after installing or updating'); + expect(guideContent).not.toContain('VS Code offers to install it first'); }); });