How to: Define and Install a Modeling Extension

  • Article

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

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

  1. On the File menu, choose New, Project.

  2. Under Installed Templates, select Visual C# or Visual Basic, then choose Class Library.

To create a VSIX project

  1. 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.

  2. Create a VSIX project.

    1. In Solution Explorer, in the shortcut menu of the solution, choose Add, New Project.

    2. Under Installed Templates, expand Visual C# or Visual Basic, then select Extensibility. In the middle column, choose VSIX Project.

  3. 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.

  4. Open source.extension.vsixmanifest. The file opens in the manifest editor.

  5. On the MetaData tab, set the name and descriptive fields of the VSIX.

  6. On the Install Targets tab, choose New and set the Ultimate and Premium editions of Visual Studio.

  7. On the Assets tab, add your components to the Visual Studio extension.

    1. Choose New.

    2. 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

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 Gesture 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

(To be defined)

Toolbox Item

How to: Define a Custom Modeling Toolbox Item

(To be defined)

Running an Extension During its Development

To run an extension during its development

  1. 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.

  2. 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.

  3. 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.

  1. In your computer, find the .vsix file that was built by your extension project.

    1. In Solution Explorer, on the shortcut menu of your project, and then choose Open Folder in Windows Explorer.

    2. Locate the file bin\*\YourProject.vsix

  2. 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.

  3. On the target computer, open the .vsix file, for example by double-clicking it.

    Visual Studio Extension Installer opens and installs the extension.

  4. Start or restart Visual Studio.

To uninstall an extension

  1. On the Tools menu, click Extension Manager.

  2. Expand Installed Extensions.

  3. 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\11.0\Extensions

See Also

Concepts

How to: Define a Profile to Extend UML

How to: Define a Custom Modeling Toolbox Item

How to: Define Validation Constraints for UML Models

How to: Define a Menu Command on a Modeling Diagram