How to: Define and Install a Modeling Extension
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.
Requirements
Visual Studio SDK, which you can obtain from Visual Studio Gallery.
Visual Studio Visualization and Modeling SDK, which you can obtain from 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.
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.
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 class library projects. Components that require program code are more easily defined in a separate class library project. Components that require code include gesture handlers, menu commands, and validation code.
To create a class library project for menu commands, gesture handlers, or validation
On the File menu, choose New, Project.
Under Installed Templates, select Visual C# or Visual Basic, then choose Class Library.
To create 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.
In Solution Explorer, in the shortcut menu of the solution, choose Add, New Project.
Under Installed Templates, expand Visual C# or Visual Basic, then select Extensibility. In the middle column, choose VSIX Project.
Set the VSIX project as the startup project of the solution.
- In Solution Explorer, on the shortcut menu of the VSIX project choose Set as StartUp project.
Open source.extension.vsixmanifest. The file opens in the manifest editor.
On the MetaData tab, set the name and descriptive fields of the VSIX.
On the Install Targets tab, choose New and set the Ultimate and Premium editions of Visual Studio.
On the Assets tab, add your components to the Visual Studio extension.
Choose New.
For a component with code, set these fields in the Add New Asset dialog box:
Type =
Microsoft.VisualStudio.MefComponent
Source =
A project in current solution
Project =
Your class library project
Embed in this folder =
(empty)
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. You can put several handlers in the same class library project. The following table summarizes the different kinds of handler.
Extension type |
Topic |
How each component is typically declared |
|---|---|---|
Menu Command |
[ClassDesignerExtension] // or other diagram types [Export(typeof(ICommandExtension))] public class MyCommand : ICommandExtension {... |
|
Drag-and-drop or double-click |
[ClassDesignerExtension] // or other diagram types [Export(typeof(IGestureExtension))] public class MyGesture : IGestureExtension {... |
|
Validation Constraint |
[Export(typeof( System.Action<ValidationContext, object>))] [ValidationMethod(ValidationCategories.Save | ValidationCategories.Menu)] public void ValidateSomething (ValidationContext context, IClassifier elementToValidate) {...} |
|
Work Item link event handler |
[Export(typeof(ILinkedWorkItemExtension))] public class MyWorkItemEventHandler : ILinkedWorkItemExtension {... |
|
UML Profile |
(To be defined) |
|
Toolbox Item |
(To be defined) |
Running an Extension During its Development
To run an extension during its development
In the Visual Studio Debug menu, choose Start Debugging.
The project builds, and a new instance of Visual Studio starts in Experimental mode.
- Alternatively you can choose 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.
Installing and uninstalling an extension
Perform the following steps to run your extension in the main instance of Visual Studio either on your own computer or on other computers.
In your computer, find the .vsix file that was built by your extension project.
In Solution Explorer, on the shortcut menu of your project, and then choose Open Folder in Windows Explorer.
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 on the Installation Targets tab of source.extension.vsixmanifest.
On the target computer, open the .vsix file, for example by double-clicking it.
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\12.0\Extensions
See Also
Concepts
How to: Define a Profile to Extend UML
How to: Define a Custom Modeling Toolbox Item