How to: Navigate the UML Model

This topic introduces the main types of the UML model.

The Model Elements, Model, and Model Store

The types defined in the assembly Microsoft.VisualStudio.Uml.Interfaces.dll correspond to the types defined in the UML Specification, version 2.1.2.

Types in the UML Specification are realized as interfaces in Visual Studio Ultimate. The letter 'I' is prepended to the name of each type. For example: IElement, IClass, IInteraction, IOperation.

All the types except IElement inherit properties from one or more supertypes.

• For a summary of the model types, see Model Element Types.

• For full details of the API, see API Reference for UML Modeling Extensibility.

Relationships

Properties and relationships that are defined in the UML Specification are implemented as .NET properties.

Most relationships are navigable in both directions. A relationship corresponds to a pair of properties, with one property on the type at each end. For example, the properties IElement.Owner and IElement.OwnedElements represent two ends of a relationship. Therefore, this expression will always evaluate to true:

IElement c; ... c.OwnedElements.All(x => x.Owner == c)

Many relationships, such as IAssociation, are also represented by an object that can have its own properties.

If you delete an element from the model, any relationship in which it takes part is automatically deleted, and the property at the other end is updated.

If the UML Specification assigns a multiplicity of 0..1 to a property, it may have the value null. A multiplicity with maximum greater than 1 means that the .NET property has the type: IEnumerable<Type>.

For more information about traversing relationships, see How to: Navigate Relationships with the UML API.

The Ownership Tree

A model contains a tree of IElement objects. Every element has properties OwnedElements and Owner.

In most cases, the targets of the Owner and OwnedElements properties are also referenced by other properties that have more specific names. For example, every UML operation is owned by a UML class. Therefore IOperation has a property named Class, and in every IOperation object, Class == Owner.

The topmost element of the tree, which has no Owner, is a IModel. The IModel is contained within a IModelStore, in which it is the Root.

Every model element is created with an Owner. For more information, see How to: Create Elements and Relationships.

Shapes and Diagrams

Elements in the UML model can be displayed on diagrams. Different types of diagrams can display different subtypes of IElement.

In some cases, an element can appear on more than one diagram. For example, an IUseCase element can have several IShapes, which can appear on one diagram or different diagrams.

Shapes are arranged in a tree. The edges of the tree are represented by the ParentShape and ChildShapes properties. Diagrams are the only shapes that do not have parents. The shapes on the surface of a diagram are composed of smaller parts. For example, a class shape has compartments for attributes and operations.

For more information about shapes, see How to: Display a Model on Diagrams.

Access to the Model in Extensions

In Visual Studio extensions defined as MEF Components, you can declare properties that import information from the context in which the extension runs.

Attribute type	What this provides access to	More information
Microsoft.VisualStudio.ArchitectureTools.Extensibility.Presentation .IDiagramContext (in Microsoft.VisualStudio.ArchitectureTools.Extensibility.dll)	The current focus diagram.	How to: Define a Menu Command on a Modeling Diagram
Microsoft.VisualStudio.Modeling.ExtensionEnablement .ILinkedUndoContext (in Microsoft.VisualStudio.Modeling.Sdk.12.0.dll)	Allows you to group changes into transactions.	How to: Link Model Updates using Transactions
Microsoft.VisualStudio.Shell .SVsServiceProvider (in Microsoft.VisualStudio.Shell.Immutable.12.0.dll)	The host Visual Studio. From there you can access files, projects and other aspects.	How to: Open a UML Model by Using the Visual Studio API

To get the Context

Declare one or both of the following interfaces inside your extension class:

[Import] public IDiagramContext DiagramContext { get; set; }

The Managed Extensibility Framework (MEF) will bind these to definitions from which you can obtain the current diagram, model store, root object, and so on:

IDiagram diagram = this.DiagramContext.CurrentDiagram;
IClassDiagram classDiagram = diagram as IClassDiagram;
       // or diagrams of other types
IModelStore modelStore = diagram.ModelStore;
IModel model = modelStore.Root;
foreach (IDiagram diagram in modelStore.Diagrams) {...}
foreach (IElement element in modelStore.AllInstances<IUseCase>) {...}

To get the current selection

// All selected shapes and their elements
foreach (IShape shape in diagram.SelectedShapes)
{  
   IDiagram selectedDiagram = shape as IDiagram;
   if (selectedDiagram != null)
   { // no shape selected - user right-clicked the diagram
     ... Context.CurrentDiagram ...
   }
   else
   {
     IElement selectedElement = shape.Element;
   ...}
// All selected shapes that display a specfic type of element
foreach (IShape<IInterface> in 
   diagram.GetSelectedShapes<IInterface>()) 
{...}

Accessing another model or diagrams

You can:

• Use Visual Studio model bus to create links between elements in different models. For more information, see How to: Integrate UML Models with Other Models and Tools.

• Load a modeling project and diagrams in read-only mode without making it visible in the Visual Studio user interface. For more information, see How to: Read a UML Model in Program Code.

• Open a modeling project and its diagrams in Visual Studio, and then access the contents. For more information, see How to: Open a UML Model by Using the Visual Studio API.

See Also

Concepts

Extending UML Models and Diagrams

Programming with the UML API