Navigating and Updating Layer Models in Program Code

This topic describes the elements and relationships in layer models, which you can navigate and update in Visual Studio Ultimate by using program code.

For more information about layer diagrams from the user's point of view, see Layer Diagrams: Reference and Layer Diagrams: Guidelines.

The Microsoft.VisualStudio.ArchitectureTools.Extensibility.Layer model described in this topic is a façade on a more general Microsoft.VisualStudio.GraphModel model. If you are writing a menu command or gesture extension, use the Layer model. If you are writing a layer validation extension, it is easier to use the GraphModel.

Transactions

When you update a model, consider enclosing the changes in a ILinkedUndoTransaction. This groups your changes into one transaction. If any of the changes fails, the whole transaction will be rolled back. If the user undoes a change, all the changes will be undone together.

For more information, see How to: Link Model Updates using Transactions.

using (ILinkedUndoTransaction t =
        LinkedUndoContext.BeginTransaction("a name"))
{ 
    // Make changes here ....
    t.Commit(); // Don't forget this!
}

Containment

Layers (ILayer) and the layer model (ILayerModel) can contain Comments and Layers.

A layer (ILayer) can be contained in a layer model (ILayerModel) or it can be nested within another ILayer.

To create a comment or a layer, use the creation methods on the appropriate container.

Dependency Links

A dependency link is represented by an object. It can be navigated in either direction:

To create a dependency link, call source.CreateDependencyLink(target).

Comments

Comments can be contained inside layers or the layer model, and can also be linked to any layer element:

A comment can be linked to any number of elements, including none.

To get the comments that are attached to a layer element, use:

ILayerModel model = diagram.GetLayerModel(); 
IEnumerable<ILayerComment> comments = 
   model.Comments.Where(comment => 
      comment.Links.Any(link => link.Target == layerElement));

Warning

The Comments property of an ILayer gets comments that are contained within the ILayer. It does not get the comments that are linked to it.

Create a comment by invoking CreateComment() on the appropriate container.

Create a link by using CreateLink() on the comment.

Layer Elements

All the types of element that can be contained in a model are layer elements:

Properties

Each ILayerElement has a string dictionary named Properties. You can use this dictionary to attach arbitrary information to any layer element.

Artifact References

An artifact reference (ILayerArtifactReference) represents the link between a layer and a project item such as a file, class, or folder. When the user creates or adds to a layer by dragging items onto the layer diagram from Solution Explorer or Architecture Explorer, they are creating artifacts. Any number of artifact references can be linked to a layer.

Each row in Layer Explorer displays an artifact reference. For more information, see Create layer diagrams from code.

The principal types and methods concerned with artifact references are as follows:

ILayerArtifactReference. The Categories property indicates what kind of artifact is referenced, such as a class, executable file, or assembly. Categories determines how the Identifier identifies the target artifact.

CreateArtifactReferenceAsync creates an artifact reference from an Project or ProjectItem. This is an asynchronous operation. Therefore, you usually provide a callback that is called when the creation is complete.

Layer Artifact References should not be confused with Artifacts in use case diagrams.

Shapes and Diagrams

Two objects are used to represent each element in a layer model: an ILayerElement, and an IShape. The IShape represents the position and size of the shape on the diagram. In layer models, every ILayerElement has one IShape, and every IShape on a layer diagram has one ILayerElement. IShape is also used for UML models. Therefore, not every IShape has a layer element.

In the same manner, the ILayerModel is displayed on one IDiagram.

In the code of a custom command or gesture handler, you can get the current diagram and the current selection of shapes from the DiagramContext import:

public class ... {
[Import]
    public IDiagramContext DiagramContext { get; set; }
...
public void ... (...) 
{ IDiagram diagram = this.DiagramContext.CurrentDiagram;
  ILayerModel model = diagram.GetLayerModel();
  if (model != null)
  { foreach (ILayer layer in model.Layers) { ... }}
  foreach (IShape selected in diagram.SelectedShapes)
  { ILayerElement element = selected.GetLayerElement();
    if (element != null) ... }}

IShape and IDiagram are also used to display UML models. For more information, see How to: Display a Model on Diagrams.

See Also

Concepts

Adding Commands and Gestures to Layer Diagrams

Adding Custom Architecture Validation to Layer Diagrams

Adding Custom Properties to a Layer Diagram

Layer Diagrams: Reference

Layer Diagrams: Guidelines

Extending UML Models and Diagrams