How to Construct a URL That Opens the Extension

The DocumentDB extension for Visual Studio Code supports activation through custom URLs, enabling you to integrate the extension seamlessly with your development environment and build deep links directly to your DocumentDB and MongoDB clusters. This powerful feature allows you to create shortcuts that can open specific connections, navigate to particular databases, or even jump directly to a collection view within the extension.

This URL-based activation is particularly useful for:

Development Workflow Integration: Create bookmarks or shortcuts that instantly connect to your frequently used databases
Team Collaboration: Share direct links to specific database resources with your team members
Documentation and Tutorials: Embed clickable links in documentation that open specific database connections
External Tool Integration: Allow other applications to launch the extension with pre-configured connections

URL Syntax

The prefix for URLs handled by this extension is:

vscode://ms-azuretools.vscode-documentdb

A link names what it wants in the path, and supplies arguments for it in the query:

vscode://ms-azuretools.vscode-documentdb/<action>?<parameters>

Supported Actions

Action	What it does	Parameters
`connect`	Opens a connection to a cluster, optionally navigating into it	`connectionString`, `database`, `collection`
`local`	Opens the DocumentDB Local setup wizard	none
`local/documentdb`	Opens the DocumentDB Local setup wizard	none

Only the actions in this table are recognized. A link naming anything else is refused with an explanatory message — the extension never treats the path as a command name, so a link cannot reach extension functionality that is not listed here.

Links written before actions existed keep working. A URL with no action, such as vscode://ms-azuretools.vscode-documentdb?connectionString=..., means connect. You do not need to update existing links.

local accepts an optional local resource type. Currently, documentdb is the only supported type, and omitting it defaults to documentdb, so /local and /local/documentdb are equivalent. Unsupported resource types and additional path segments are refused rather than silently opening a different setup experience.

Supported Parameters

These apply to the connect action.

The following table lists all supported URL parameters:

Parameter	Required	Description	Example Value
`connectionString`	Yes	The MongoDB/DocumentDB connection string (double URL-encoded)	`mongodb%253A%252F%252F...`
`database`	No	Name of the database to open after connection	`myDatabase`
`collection`	No	Collection to open (requires a database parameter or path)	`myCollection`

Parameter Details

connectionString: The core parameter that defines the database connection. Must be a valid DocumentDB or MongoDB connection string that has been double URL-encoded (see encoding section below). Note: While it’s possible to include a database name in the connection string, it’s recommended to use the separate database parameter instead to keep the API simple and consistent.
database: When provided, the extension will automatically navigate to the specified database after establishing the connection.
collection: The extension opens the Collection View for this collection. A database must be supplied either through the database parameter or in the connection-string path; otherwise the link is rejected before a connection is added or opened.

Double Encoding

The connectionString parameter must be encoded twice to ensure proper parsing. This is because the connection string itself contains special characters that need to be preserved through the URL parsing process.

Encoding Process

The encoding happens in two steps:

First encoding: Standard URL encoding of the connection string
Second encoding: URL encoding of the already-encoded string

For example, the string "mongo+srv://" would be transformed as follows:

Original string:
```
mongo+srv://
```
First encoding:
```
mongo%2Bsrv%3A%2F%2F
```
Second encoding (final result):
```
mongo%252Bsrv%253A%252F%252F
```

This double encoding ensures that the URL is correctly parsed by both the operating system and the extension.

Examples

Here are practical examples of URLs with their decoded connection strings for clarity:

Example 1: Basic Connection

vscode://ms-azuretools.vscode-documentdb?connectionString=mongodb%253A%252F%252Fusername%253Apassword%2540localhost%253A27017

Parameter	Decoded Value
`connectionString`	`mongodb://username:password@localhost:27017`

vscode://ms-azuretools.vscode-documentdb?connectionString=mongodb%253A%252F%252Fmyuser%253Amypass%2540localhost%253A27017&database=analytics

Parameter	Decoded Value
`connectionString`	`mongodb://myuser:mypass@localhost:27017`
`database`	`analytics`

This URL will connect to the database and automatically navigate to the analytics database.

Example 3: Direct Collection Access

vscode://ms-azuretools.vscode-documentdb?connectionString=mongodb%253A%252F%252Fadmin%253Asecret%2540localhost%253A27017%252Fecommerce&database=ecommerce&collection=orders

Parameter	Decoded Value
`connectionString`	`mongodb://admin:secret@localhost:27017/ecommerce`
`database`	`ecommerce`
`collection`	`orders`

This URL will connect to the database, navigate to the ecommerce database, and open the Collection View for the orders collection.

Example 4: Open the DocumentDB Local Setup Wizard

Use this to take someone from a web page to a running local DocumentDB without asking them to find anything in the UI. It carries no parameters, because there is no connection yet — that is what the wizard is for.

vscode://ms-azuretools.vscode-documentdb/local

The explicit resource-type form is equivalent:

vscode://ms-azuretools.vscode-documentdb/local/documentdb

When URL handling confirmations are enabled in the extension settings, either form shows one confirmation before opening the setup wizard.

How It Works

When you click a URL for the extension, the following process occurs:

Activation: The vscode:// prefix tells the operating system to activate VS Code. The ms-azuretools.vscode-documentdb segment activates the DocumentDB extension.
Action routing: The extension reads the action from the path. An unrecognized action is refused rather than guessed at, so a mistyped link never acts on parameters you did not intend for it.
Connection Handling (for connect):
- The extension parses the connectionString parameter and creates a new connection in the Connections View.
- If a connection with the same host and username already exists, the existing connection will be selected instead of creating a duplicate.
- Before a new connection is added, the extension shows its target (user, hosts, database, and collection) and asks you to confirm. This confirmation is always shown, even when URL handling confirmations are disabled in the extension settings; that setting only skips the follow-up prompts and links to connections you have already saved.
- TLS options that turn off certificate validation (such as tlsAllowInvalidCertificates) are removed from the connection string. A link can ask to turn off certificate validation only for a target on your own machine (localhost, 127.0.0.1, or ::1), and the extension always asks you first. For any other target, certificate validation stays on; you can change it later in the connection settings.
Navigation (if additional parameters are provided):
- If the database parameter is provided, the extension navigates to that database.
- If both database and collection parameters are provided, the extension opens the Collection View for the specified collection.

Additional Notes

Ensure the connectionString is valid and properly double-encoded to avoid connection errors.
The extension will handle authentication and connection establishment automatically.
If a mongodb+srv:// connection fails with querySrv EBADRESP or querySrv ECONNREFUSED, see Troubleshoot SRV DNS Lookups.
Invalid or malformed URLs will display appropriate error messages to help with troubleshooting.
A link is untrusted input: the set of actions it can reach is fixed by the extension, not derived from its command list. Adding a new action is a deliberate decision that the action is safe to trigger from someone else’s web page.