vscode-ext-commands

VS Code extension command contribution

This skill helps you to contribute commands in VS Code extensions

When to use this skill

Use this skill when you need to:

• Add or update commands to your VS Code extension

Instructions

VS Code commands must always define a title, independent of its category, visibility or location. We use a few patterns for each "kind" of command, with some characteristics, described below:

• Regular commands: By default, all commands should be accessible in the Command Palette, must define a category, and don't need an icon, unless the command will be used in the Side Bar.

• Side Bar commands: As a project naming convention, rather than a VS Code platform requirement, its name follows a special pattern, starting with underscore (_) and suffixed with #sideBar, like _extensionId.someCommand#sideBar for instance. Must define an icon, and may or may not have some rule for enablement; consider whether an enablement rule is needed for the command state. Side Bar exclusive commands should not be visible in the Command Palette. To hide one, add a Command Palette menu entry for the command whose when condition is always false; the underscore prefix alone does not hide it. Hiding a command from the Command Palette does not make it private, since other code or links can still run it, so its handler must check its arguments rather than trust the caller. Contributing it to the view/title or view/item/context, we must inform order/position that it will be displayed. If the user describes placement relative to another command or button, inspect the existing view/title or view/item/context entries and choose a matching group and order; ask the user if placement is unclear. Always define a when condition for every view/title and view/item/context entry, limited to the target view or tree item, so the command appears only where it belongs.

• Scope of changes: Only change the requested command entry, its matching menu entries and its handler. Ask the user before changing unrelated keybindings or other contributions.

• Handler: Each declared command also needs a handler registered in the extension code, and the command id must match exactly between the contribution and the code.