How to: Define and Install a Modeling Extension

Article
02/04/2013

In Visual Studio Ultimate, you can define extensions to modeling diagrams. In this manner, you can adapt the diagrams and models to your own needs. For example, you can define menu commands, UML profiles, validation constraints and toolbox items. You can define several components in a single extension. You can also distribute these extensions to other Visual Studio Ultimate users in the form of a Visual Studio Integration Extension (VSIX). You can create a VSIX using a VSIX project in Visual Studio.

You should have Visual Studio SDK installed.

Requirements

Visual Studio 2010 SDK
Visual Studio 2010 Visualization and Modeling SDK. For more information, see Visual Studio Visualization and Modeling SDK on Code Gallery.

Creating a Modeling Extension Solution

To define a modeling extension, you must create a solution containing these projects:

A Visual Studio Integration Extension (VSIX) project. This generates a file that acts as an installer for the components of your extension. In the New Project dialog, expand Visual C# or Visual Basic, then click Extensibility. In the middle column, click VSIX Project.
A class library project, required for components that include program code.

If you want to make an extension that has several components, you can develop them in a single solution. You need only one VSIX project, and you add the components as contents to the VSIX definition.

Components that do not require code, such as custom toolbox items and custom UML profiles, can be added directly to the VSIX project without using separate projects. Components such as menu commands that require program code are more easily defined in a separate project.

To set up a VSIX project

If you are creating a component with code, it is easiest to create the class library project first. You will add your code to that project.
Create a VSIX project.
1. In Solution Explorer, right-click the solution, point to Add, and then click New Project.
2. Under Installed Templates, expand Visual C# or Visual Basic, then click Extensibility. In the middle column, click VSIX Project.
Set the VSIX project as the startup project of the solution.
- In Solution Explorer, right-click the VSIX project and then click Set as StartUp project.
Open source.extension.vsixmanifest. The file opens in the manifest editor.
Set the name and descriptive fields of the VSIX.
Click Select Editions and select the Visual Studio editions you want your extension to run on.
Add your components to the Content list.
1. Click Add Content.
2. For a component with code:
  
  At Select a content type, select MEF Component.
  
  At Select a source, click Project and select the name of your class library project.
  
  For other component types, see the links in the next section.

Developing the Component

For each component such as a menu command or gesture handler, you must define a separate handler. The following table summarizes the different kinds of handler.

Extension type	Topic	How each component is typically declared
Menu Command	How to: Define a Menu Command on a Modeling Diagram	[ClassDesignerExtension] // or other diagram types [Export(typeof(ICommandExtension))] public class MyCommand : ICommandExtension {...
Drag-and-drop or double-click	How to: Define a Drop and Double-Click Handler on a Modeling Diagram	[ClassDesignerExtension] // or other diagram types [Export(typeof(IGestureExtension))] public class MyGesture : IGestureExtension {...
Validation Constraint	How to: Define Validation Constraints for UML Models	[Export(typeof( System.Action<ValidationContext, object>))] [ValidationMethod(ValidationCategories.Save \| ValidationCategories.Menu)] public void ValidateSomething (ValidationContext context, IClassifier elementToValidate) {...}
Work Item link event handler	How to: Define a Work Item Link Handler	[Export(typeof(ILinkedWorkItemExtension))] public class MyWorkItemEventHandler : ILinkedWorkItemExtension {...
UML Profile	How to: Define a Profile to Extend UML	Not defined with program code. Instead, define the component type in source.extension.vsixmanifest as follows. Component Type = Custom Extension Type = Microsoft.VisualStudio.UmlProfile
Toolbox Item	How to: Define a Custom Modeling Toolbox Item	Not defined with program code. Instead, define the component type in source.extension.vsixmanifest as follows. Component Type = Custom Extension Type = Microsoft.VisualStudio.ArchitectureTools.CustomToolboxItems

Running an Extension During its Development

To run an extension during its development

In the Visual Studio Debug menu, click Start Debugging.

The project builds, and a new instance of Visual Studio starts in Experimental mode.
- Alternatively you can click Start Without Debugging. This reduces the time taken to start the program.
Create or open a modeling project in the experimental instance of Visual Studio, and create or open a diagram.

Your extension will load and run.
If you used Start Without Debugging but you want to use the debugger, go back to the main instance of Visual Studio. On the Debug menu, click Attach to Process. In the dialog box, select the experimental instance of Visual Studio, which has the program name devenv.

To run the extension in the main instance of Visual Studio, follow the steps in Installing and uninstalling an extension.

Installing and uninstalling an extension

You can install a Visual Studio extension both on your own computer and on other computers.

To install an extension

In your computer, find the .vsix file that was built by your extension project.
1. In Solution Explorer, right-click your project, and then click Open Folder in Windows Explorer.
2. Locate the file bin\*\YourProject.vsix
Copy the .vsix file to the target computer on which you want to install the extension. This can be your own computer or another one.
- The target computer must have one of the editions of Visual Studio that you specified in source.extension.vsixmanifest.
On the target computer, double-click the .vsix file.

Visual Studio Extension Installer opens and installs the extension.
Start or restart Visual Studio.

To uninstall an extension

On the Tools menu, click Extension Manager.
Expand Installed Extensions.
Select the extension, and then click Uninstall.

Rarely, a faulty extension fails to load and creates a report in the error window, but does not appear in Extension Manager. In that case, you can remove the extension by deleting the file from the following location where %LocalAppData% is typically DriveName:\Users\UserName\AppData\Local:

%LocalAppData%\Microsoft\VisualStudio\10.0\Extensions