Figure 2: Reaching the Extension Manager. Visual Studio Extensions. Navigate to the ProjectTemplateXamarin.mpack file. Figure 3: The ProjectTemplate location.

Visual Studio for Mac consists of a set of modules called Extension Packages. You can use Extension Packages to introduce new functionality to Visual Studio for Mac, such as support for an additional language or a new Project template.

Extension packages build from the extension points of other extension packages. Extension points are placeholders for areas that can be expanded upon, such as a menu or the list of IDE Commands. An extension package can build from an extension point by registering a node of structured data called an extension, such as a new menu item or a new Command. Each extension point accepts certain types of extensions, such as a Command, Pad, or FileTemplate. A module that contains extension points is called an add-in host, as it can be extended by other extension packages.

To customize Visual Studio for Mac, you can create an extension package that builds from extension points contained in add-in hosts within pre-existing libraries in Visual Studio for Mac, as illustrated by the following diagram:

In order for an extension package to build from Visual Studio for Mac, it must have extensions that build from pre-existing extension points within the Visual Studio for Mac IDE. When an extension package relies on an extension point defined in an add-in host, it is said to have a dependency on that extension package.

The benefit of this modular design is that Visual Studio for Mac is extensible -- there are many extension points that can be built upon with custom extension packages. Examples of current extension packages include support for C# and F#, debugger tools, and Project templates.

Note

If you have an Add-in Maker project that was created before Add-in Maker 1.2, you need to migrate your project as outlined in the steps here.

This section looks at the different files generated by the Add-in Maker and the data a command extension requires.

Attribute files

Extension packages store metadata about their name, version, dependencies, and other information in C# attributes. The Add-in Maker creates two files, AddinInfo.cs and AssemblyInfo.cs to store and organize this information. Extension packages must have a unique ID and namespace specified in their Addin attribute:

Extension packages must also declare dependencies on the extension packages that own the extension points they plug into, which are automatically referenced at build time.

Furthermore, additional references can be added via the Add-in reference node in the solution pad for the project, as depicted by the following image:

They also have their corresponding assembly:AddinDependency attributes added at build time. Once the metadata and dependency declarations are in place, you can focus on the essential building blocks of the extension package.

Extensions and extension points

An extension point is a placeholder that defines a data structure (a type), while an extension defines data that conforms to a structure specified by a specific extension point. Extension points specify what type of extension they can accept in their declaration. Extensions are declared using type names or extension paths. See the Extension Point reference for a more in-depth explanation on how to create the extension point that you need.

The extension/extension point architecture keeps the development of Visual Studio for Mac fast and modular.

Command Extensions

Command Extensions are extensions that point to methods that are called every time it is executed.

Command Extensions are defined by adding entries to the /MonoDevelop/Ide/Commands extension point. We defined our extension in Manifest.addin.xml with the following code:

The extension node contains a path attribute that specifies the extension point that it is plugging into, in this case /MonoDevelop/Ide/Commands/Edit. Additionally, it acts as a parent node to the Command. The Command node has the following attributes:

• id - Specifies the identifier for this Command. Command Identifiers must be declared as enumeration members, and are used to connect Commands to CommandItems.
• _label - The text to be shown in menus.
• _description - The text to be shown as a tooltip for toolbar buttons.
• defaultHandler - Specifies the CommandHandler class that powers the Command

A CommandItem extension that plugs into the /MonoDevelop/Ide/MainMenu/Edit extension point is demonstrated in the following code snippet:

A CommandItem places a Command specified in its id attribute into a menu. This CommandItem is extending the /MonoDevelop/Ide/MainMenu/Edit extension point, which makes the Command's label appear in the Edit Menu. Note that the ID in the CommandItem corresponds to the ID of the Command node, InsertDate. If you remove the CommandItem, the Insert Date option would disappear from the Edit Menu.

Command Handlers

The InsertDateHandler is an extension of the CommandHandler class. It overrides two methods, Update and Run. The Update method is queried whenever a Command is shown in a menu or executed via key bindings. By changing the info object, you can disable the Command or make it invisible, populate array commands, and more. This Update method disables the command if it can't find an active Document with a TextEditor to insert text into:

You only need to override the Update method when you have special logic for enabling or hiding the Command. The Run method executes whenever a user executes a Command, which in this case occurs when a user selects the Command from the Edit Menu. This method inserts the date and time at the caret in the text editor:

Declare the Command type as an enumeration member within DateInserterCommands:

The Command and CommandItem are now tied together - the CommandItem calls the Command when the CommandItem is selected from the Edit Menu.

IDE APIs

For information on the scope of areas that are available for development, see the Extension Tree Reference and the API Overview. When building advanced extension packages, also refer to Developer Articles. Below is a partial list of areas for customization:

• Pads
• Key Binding Schemes
• Policies
• Code formatters
• Project file formats
• Preferences panels
• Options Panels
• Debugger Protocols
• Debugger visualizers
• Workspace layouts
• Solution pad tree nodes
• Source editor margins
• Unit test engines
• Code generators
• Code snippets
• Target frameworks
• Target runtime
• VCS back-ends
• Refactoring
• Execution handlers
• Syntax highlighting

Extending The New Editor

Visual Studio for Mac introduces a new native Cocoa text editor UI built on top of the same editor layers from Visual Studio on Windows.

One of the many benefits of sharing the editor between Visual Studio and Visual Studio for Mac is that code targeting the Visual Studio editor can be adapted to run on Visual Studio for Mac.

Note

The new editor supports only C# files at this time. Other languages and file formats will open in the legacy editor. The legacy editor does however implement some of the Visual Studio Editor APIs described below.

Visual Studio Editor Overview

Before touching on extension details specific to Visual Studio for Mac, it is helpful to understand more about the shared editor itself. Below are a few resources that may deepen this understanding:

With those resources in hand, the primary concepts that you need to be familiar with are an ITextBuffer and an ITextView:

• An ITextBuffer is an in-memory representation of text that can be changed over time. The CurrentSnapshot property on ITextBuffer returns an immutable representation of the current contents of the buffer, an instance of ITextSnapshot. When an edit is made on the buffer, the CurrentSnapshot property is updated to the latest version. Analyzers can inspect the text snapshot on any thread and its contents is guaranteed to never change.

• An ITextView is the UI representation of how ITextBuffer is rendered on screen in the editor control. It has a reference to its text buffer, as well as Caret, Selection, and other UI-related concepts.

For a given MonoDevelop.Ide.Gui.Document, you can retrieve the associated underlying ITextBuffer and ITextView via Document.GetContent<ITextBuffer>() and Document.GetContent<ITextView>() respectively.

Additional Information

Note

We are currently working on improving the extensibility scenarios for Visual Studio for Mac. If you are creating extensions and need additional help or information, or would like to provide feedback, please fill in the Visual Studio for Mac Extension Authoring form.

See also

Increase the power of Visual Studio Code through Extensions

The features that Visual Studio Code includes out-of-the-box are just the start. VS Code extensions let you add languages, debuggers, and tools to your installation to support your development workflow. VS Code's rich extensibility model lets extension authors plug directly into the VS Code UI and contribute functionality through the same APIs used by VS Code. This topic explains how to find, install, and manage VS Code extensions from the Visual Studio Code MarketPlace.

Browse for extensions

You can browse and install extensions from within VS Code. Bring up the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of VS Code or the View: Extensions command (⇧⌘X (Windows, Linux Ctrl+Shift+X)).

This will show you a list of the most popular VS Code extensions on the VS Code Marketplace.

Each extension in the list includes a brief description, the publisher, the download count, and a five star rating. You can click on the extension item to display the extension's details page where you can learn more.

Note: If your computer's Internet access goes through a proxy server, you will need to configure the proxy server. See Proxy server support for details.

Install an extension

To install an extension, click the Install button. Once the installation is complete, the Install button will change to the Manage gear button.

Extension details

On the extension details page, you can read the extension's README as well as review the extension's:

• Contributions - The extension's additions to VS Code such as settings, commands and keyboard shortcuts, language grammars, debugger, etc.
• Changelog - The extension repository CHANGELOG if available.
• Dependencies - Lists if the extension depends on any other extensions.

If an extension is an Extension Pack, the Extension Pack section will display which extensions will be installed when you install the pack. Extension Packs bundle separate extensions together so they can be easily installed at one time.

Extensions view commands

You can run various Extensions view commands by clicking on the Extensions view's ..More Actions button.

There are commands to show:

• The list of currently installed extensions
• The list of outdated extensions that can be updated
• The list of currently enabled/disabled extensions
• The list of recommended extensions based on your workspace
• The list of globally popular extensions

You can sort the extension list by Install Count or Rating in either ascending or descending order. You can learn more about extension search filters below.

Search for an extension

You can clear the Search box at the top of the Extensions view and type in the name of the extension, tool, or programming language you're looking for.

For example, typing 'python' will bring up a list of Python language extensions:

If you know the exact identifier for an extension you're looking for, you can use the @id: prefix, for example @id:octref.vetur. Additionally, to filter or sort results, you can use the filter and sort commands, detailed below.

Manage extensions

VS Code makes it easy to manage your extensions. You can install, disable, update, and uninstall extensions through the Extensions view, the Command Palette (commands have the Extensions: prefix) or command-line switches.

List installed extensions

By default, the Extensions view will show the extensions you currently have enabled, all extensions that are recommended for you, and a collapsed view of all extensions you have disabled. You can use the Show Installed Extensions command, available in the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) or the More Actions (..) drop-down menu, to clear any text in the search box and show the list of all installed extensions, which includes those that have been disabled.

Uninstall an extension

To uninstall an extension, click the gear button at the right of an extension entry and then choose Uninstall from the drop-down menu. This will uninstall the extension and prompt you to reload VS Code.

Disable an extension

If you don't want to permanently remove an extension, you can instead temporarily disable the extension by clicking the gear button at the right of an extension entry. You can disable an extension globally or just for your current Workspace. You will be prompted to reload VS Code after you disable an extension.

If you want to quickly disable all installed extensions, there is a Disable All Installed Extensions command in the Command Palette and More Actions (..) drop-down menu.

Extensions remain disabled for all VS Code sessions until you re-enable them.

Enable an extension

Similarly if you have disabled an extension (it will be in the Disabled section of the list and marked Disabled), you can re-enable it with the Enable or Enable (Workspace) commands in the drop-down menu.

There is also an Enable All Extensions command in the More Actions (..) drop-down menu.

Extension auto-update

VS Code checks for extension updates and installs them automatically. After an update, you will be prompted to reload VS Code. If you'd rather update your extensions manually, you can disable auto-update with the Disable Auto Updating Extensions command that sets the extensions.autoUpdatesetting to false. If you don't want VS Code to even check for updates, you can set the extensions.autoCheckUpdates setting to false.

Update an extension manually

If you have extensions auto-update disabled, you can quickly look for extension updates by using the Show Outdated Extensions command that uses the @outdated filter. This will display any available updates for your currently installed extensions. Click the Update button for the outdated extension and the update will be installed and you'll be prompted to reload VS Code. You can also update all your outdated extensions at one time with the Update All Extensions command. If you also have automatic checking for updates disabled, you can use the Check for Extension Updates command to check which of your extensions can be updated.

Recommended extensions

You can see a list of recommended extensions using Show Recommended Extensions, which sets the @recommendedfilter. Extension recommendations can either be:

• Workspace Recommendations - Recommended by other users of your current workspace.
• Other Recommendations - Recommended based on recently opened files.

See the section below to learn how to contribute recommendations for other users in your project.

Ignoring recommendations

To dismiss a recommendation, click on the extension item to open the Details pane and then press the Ignore Recommendation button. Ignored recommendations will no longer be recommended to you.

Configuring extensions

VS Code extensions may have very different configurations and requirements. Some extensions contribute settings to VS Code, which can be modified in the Settings editor. Other extensions may have their own configuration files. Extensions may also require installation and setup of additional components like compilers, debuggers, and command-line tools. Consult the extension's README (visible in the Extensions view details page) or go to the extension page on the VS Code Marketplace (click on the extension name in the details page). Many extensions are open source and have a link to their repository on their Marketplace page.

Command line extension management

To make it easier to automate and configure VS Code, it is possible to list, install, and uninstall extensions from the command line. When identifying an extension, provide the full name of the form publisher.extension, for example ms-python.python.

Example:

You can see the extension ID on the extension details page next to the extension name.

Extensions view filters

The Extensions view search box supports filters to help you find and manage extensions. You may have seen filters such as @installed and @recommended if you used the commands Show Installed Extensions and Show Recommended Extensions. Also, there are filters available to let you sort by popularity or ratings and search by category (for example 'Linters') and tags (for example 'node'). You can see a complete listing of all filters and sort commands by typing @ in the extensions search box and navigating through the suggestions:

Here are the Extensions view filters:

• @builtin - Show extensions that come with VS Code. Grouped by type (Programming Languages, Themes, etc.).
• @disabled - Show disabled installed extensions.
• @installed - Show installed extensions.
• @outdated - Show outdated installed extensions. A newer version is available on the Marketplace.
• @enabled - Show enabled installed extensions. Extensions can be individually enabled/disabled.
• @recommended - Show recommended extensions. Grouped as Workspace specific or general use.
• @category - Show extensions belonging to specified category. Below are a few of supported categories. For a complete list, type @category and follow the options in the suggestion list:
  • @category:themes
  • @category:formatters
  • @category:linters
  • @category:snippets

These filters can be combined as well. For example: Use @installed @category:themes to view all installed themes.

If no filter is provided, the Extensions view displays the currently installed and recommended extensions.

Sorting

You can sort extensions with the @sort filter, which can take the following values:

• installs - Sort by Marketplace installation count, in descending order.
• rating - Sort by Marketplace rating (1-5 stars), in descending order.
• name - Sort alphabetically by extension name.

Categories and tags

Extensions can set Categories and Tags describing their features.

You can filter on category and tag by using category: and tag:.

Supported categories are: [Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs]. They can be accessed through IntelliSense in the extensions search box:

Note that you must surround the category name in quotes if it is more than one word (for example, category:'SCM Providers').

Tags may contain any string and are not provided by IntelliSense, so review the Marketplace to find helpful tags.

Install from a VSIX

You can manually install a VS Code extension packaged in a .vsix file. Using the Install from VSIX command in the Extensions view command drop-down, or the Extensions: Install from VSIX command in the Command Palette, point to the .vsix file.

You can also install using the VS Code --install-extension command-line switch providing the path to the .vsix file.

You may provide the --install-extension multiple times on the command line to install multiple extensions at once.

If you'd like to learn more about packaging and publishing extensions, see our Publishing Extensions topic in the Extension API.

Workspace recommended extensions

A good set of extensions can make working with a particular workspace or programming language more productive and you'd often like to share this list with your team or colleagues. You can create a recommended list of extensions for a workspace with the Extensions: Configure Recommended Extensions (Workspace) command.

In a single folder workspace, the command creates an extensions.json file located in the workspace .vscode folder where you can add a list of extensions identifiers ({publisherName}.{extensionName}).

In a multi-root workspace, the command will open your .code-workspace file where you can list extensions under extensions.recommendations. You can still add extension recommendations to individual folders in a multi-root workspace by using the Extensions: Configure Recommended Extensions (Workspace Folder) command.

An example extensions.json could be:

which recommends two linter extensions, TSLint and ESLint, as well as the Chrome debugger extension.

An extension is identified using its publisher name and extension identifier publisher.extension. You can see the name on the extension's detail page. VS Code will provide you with auto-completion for installed extensions inside these files.

.

VS Code prompts a user to install the recommended extensions when a workspace is opened for the first time. The user can also review the list with the Extensions: Show Recommended Extensions command.

Next steps

Here are a few topics you may find interesting..

• Extension API - Start learning about the VS Code extension API.
• Your First Extension - Try creating a simple Hello World extension.
• Publishing to the Marketplace - Publish your own extension to the VS Code Marketplace.

Common questions

Where are extensions installed?

Extensions are installed in a per user extensions folder. Depending on your platform, the location is in the following folder:

• Windows%USERPROFILE%.vscodeextensions
• macOS~/.vscode/extensions
• Linux~/.vscode/extensions

You can change the location by launching VS Code with the --extensions-dir <dir> command-line option.

Whenever I try to install any extension, I get a connect ETIMEDOUT error

You may see this error if your machine is going through a proxy server to access the Internet. See the Proxy server support section in the setup topic for details.

Can I download an extension directly from the Marketplace?

Some users prefer to download an extension once from the Marketplace and then install it multiple times from a local share. This is useful when there are connectivity concerns or if your development team wants to use a fixed set of extensions.

To download an extension, navigate to the details page for the specific extension within the Marketplace. On that page, there is a Download Extension link in the Resources section, which is located on the right-hand side of the page.

Once downloaded, you can then install the extension via the Install from VSIX command in the Extensions view command drop-down.

Can I stop VS Code from providing extension recommendations?

Yes, if you would prefer to not have VS Code display extension recommendations in the Extensions view or through notifications, you can modify the following settings:

• extensions.showRecommendationsOnlyOnDemand - Set to true to remove the RECOMMENDED section.
• extensions.ignoreRecommendations - Set to true to silence extension recommendation notifications.

The Show Recommended Extensions command is always available if you wish to see recommendations. Option for windows excel for mac.