Layer Diagrams: Guidelines

In Visual Studio Ultimate, you can describe the structure of an application at a high level and verify that the code conforms to this high-level design by using layer diagrams. To ensure that the code stays consistent with the design, you can include layer validation as part of the build process.

Like a traditional architecture diagram, a layer diagram identifies the major components or functional units of the design and their interdependencies. Each node on the diagram, called a layer, represents a logical group of namespaces, projects, or other artifacts. You can draw the dependencies that should exist in your design. Unlike a traditional architecture diagram, you can verify that the actual dependencies in the source code conform to the intended dependencies that you have specified. By making validation part of a regular build on Team Foundation Server, you can ensure that the program code continues to adhere to the system's architecture through future changes.

For information about layer diagrams, see Layer Diagrams: Reference and the following videos:

Architect an Application with Layer Diagrams

MSDN How Do I Series: How to Validate Code using Layer Diagrams

How to Design or Update Your Application Using Layer Diagrams

The following steps provide an overview of how to use layer diagrams within the development process. Later sections in this topic describe more detail about each step. If you are developing a new design, omit the steps that refer to existing code.

Note

These steps appear in approximate order. You will probably want to overlap the tasks, reorder them to suit your own situation, and revisit them at the start of each iteration in your project.

1. Create a layer diagram for the whole application, or for a layer within it.

2. Define layers to represent primary functional areas or components of your application. Name these layers according to their function, for example, "Presentation" or "Services". If you have a Visual Studio solution, you can associate each layer with a collection of artifacts, such as projects, namespaces, files, and so on.

3. Discover the existing dependencies between layers.

4. Edit the layers and dependencies to show the updated design that you want the code to reflect.

5. Design new areas of your application by creating layers to represent the principal architectural blocks or components and defining dependencies to show how each layer uses the others.

6. Edit the layout and appearance of the diagram to help you discuss it with colleagues.

7. Validate the code against the layer diagram to highlight the conflicts between the code and the architecture you require.

8. Update the code to conform to your new architecture. Iteratively develop and refactor code until the validation shows no conflicts.

9. Include layer validation in the build process to ensure that the code continues to adhere to your design.

Create a Layer Diagram

A layer diagram must be created inside a modeling project. You can add a new layer diagram to an existing modeling project, or you can create a new modeling in your solution for the new layer diagram.

To add a new layer diagram to a modeling project

1. On the Architecture menu, click New Diagram.

2. Under Templates, click Layer Diagram.

3. Name the diagram

4. In Add to Modeling Project, browse to and select an existing modeling project in your solution.

   -or-

   Click Create a new modeling project to add a new modeling project to the solution.

   Note

   The layer diagram must exist inside a modeling project. However, you can link it to artifacts that exist anywhere in the solution.

You can also copy an existing layer diagram within the same modeling project.

Note

Do not add, drag, or copy an existing layer diagram from a modeling project to another modeling project or to another location in the solution. A layer diagram that is copied in this way will have the same references as the original diagram, even if you modify the diagram. This will prevent layer validation from working correctly and might cause other issues, such as missing elements or other errors when trying to open the diagram.

To copy a layer diagram, follow these steps:

To copy an existing layer diagram

1. Add a new layer diagram to the modeling project.

2. Copy the elements from the source layer diagram to the new layer diagram.

Define Layers to Represent Functional Areas or Components

Layers represent logical groups of artifacts, such as projects, code files, namespaces, classes, and methods. You can create layers from artifacts in your Visual Studio solution, or you can attach specifications or plans to a layer by linking documents, such as Word files or PowerPoint presentations. Each layer appears as a rectangle on the diagram and shows the number of artifacts that are linked to it. A layer can contain nested layers that describe more granular tasks.

As a general guideline, name layers according to their function, for example, "Presentation" or "Services". If the artifacts are closely interdependent, place them in the same layer. If the artifacts can be updated separately or used in separate applications, place them in different layers. To learn about layering patterns, visit the Patterns & Practices site at https://go.microsoft.com/fwlink/?LinkId=145794.

Note

There are certain types of artifacts that you can link to layers but that do not support validation against the layer diagram. To see whether the artifact supports validation, open Layer Explorer to examine the Supports Validation property of the artifact link. For more information, see Managing Links Between Layers and Artifacts.

When updating an unfamiliar application, you might use dependency graphs to help you explore and understand the code. These graphs can help you discover clusters and dependencies in the code. You might also use Architecture Explorer to explore namespaces and classes, which often correspond well to the existing layers. This can help make it easier for you to assign artifacts to layers. You can then use layer diagrams to help you update the code.

For more information, see the following topics:

• How to: Explore Code with Dependency Graphs

• How to: Find Code Using Architecture Explorer

Use the following tasks to create layers:

To	Perform these steps
Create a layer for a single artifact	Drag the artifact onto the layer diagram from any of the following sources: Solution Explorer For example, you can drag files or projects. Architecture Explorer For example, you can drag namespaces, classes, or methods. For more information, see How to: Find Code Using Architecture Explorer. Dependency graphs For more information, see How to: Generate Dependency Graphs for .NET Code. A layer appears on the diagram and is linked to the artifact. Rename the layer to reflect the responsibilities of the associated code or artifacts.
Create a single layer for all selected artifacts	Drag all of the selected artifacts to the diagram at the same time. A layer appears on the diagram and is linked to the entire group of artifacts.
Create a layer for each selected artifact	Press and hold the SHIFT key while you drag all of the artifacts to the layer diagram at the same time. Note If you use the SHIFT key to select a range of items, release the key after you select the artifacts. Press and hold it again when you drag the artifacts to the diagram. A layer for each artifact appears on the diagram and is linked to that artifact.
Add an artifact to a layer	Drag the artifact to the layer.
Create a new unlinked layer	In the Toolbox, expand the Layer Diagram section, and then drag a Layer to the layer diagram. To add multiple layers, double-click the tool. When you are finished, click the Pointer tool or press the ESC key. - or - Right-click the layer diagram, point to Add, and then click Layer. For example, you can do this to represent a part of the application that you have not yet started to develop. It is a useful practice to create placeholder code for such layers at an early stage.
Create nested layers	Drag an existing layer onto another layer. - or - Right-click a layer, point to Add, and then click Layer.
Create a new layer that contains two or more existing layers	Select the layers, right-click a selected layer, and then click Group.
Change the color of a layer	Set its Color property to the color that you want.
Specify that artifacts associated with a layer cannot depend on the specified namespaces	Type the namespaces in the layer's Forbidden Namespace Dependencies property. Use a semicolon (;) to separate the namespaces.
Specify that artifacts associated with a layer must not belong to the specified namespaces	Type the namespaces in the layer's Forbidden Namespaces property. Use a semicolon (;) to separate the namespaces.
Specify that artifacts associated with a layer must belong to one of the specified namespaces	Type the namespace in the layer's Required Namespaces property. Use a semicolon (;) to separate the namespaces.

Manage Links Between Layers and Artifacts

1. On the layer diagram, right-click a layer, and then click View Links.

   Layer Explorer shows the artifacts that are linked to the selected layer. To see all the artifacts that are linked to the layers on the diagram, click the diagram.

2. Use the following tasks to manage these links:

   To	In Layer Explorer
   Delete the link between the layer and an artifact	Right-click the artifact link, and then click Delete.
   Move the link from one layer to another	Drag the artifact link to an existing layer on the diagram. - or - Right-click the artifact link, and then click Cut. On the layer diagram, right-click the layer, and then click Paste.
   Copy the link from one layer to another	Right-click the artifact link, and then click Copy. On the layer diagram, right-click the layer, and then click Paste.
   Create a new layer from an existing artifact link	Drag the artifact link to a blank area on the diagram.
   Verify that a linked artifact supports validation against the layer diagram.	Look at the Supports Validation column for the artifact link. Artifacts that do not support validation against a layer diagram include C++ projects, Web sites, Office documents, and plain text files. You can link such artifacts to layers, but the validation process will ignore them. Validation errors will not appear for references to projects or assemblies that are linked to separate layers when no dependencies appear between those layers. Such references are not considered dependencies unless the code uses those references.

Discover Existing Dependencies Between Layers

A dependency exists wherever an artifact that is associated with one layer has a reference to an artifact that is associated with another layer. For example, a class in one layer declares a variable that has a class in another layer. You can discover existing dependencies by reverse-engineering them.

Note

Dependencies cannot be reverse-engineered for certain kinds of artifacts. For example, no dependencies will be reverse-engineered from or to a layer that is linked to a text file. To see which artifacts have dependencies that you can reverse-engineer, right-click one or multiple layers, and then click View Links. In Layer Explorer, examine the Supports Validation column. Dependencies will not be reverse-engineered for artifacts for which this column shows False.

To reverse-engineer existing dependencies between layers

• Select one layer or multiple layers, right-click a selected layer, and then click Generate Dependencies.

Typically, you will see some dependencies that should not exist. You can edit these dependencies to align them with the intended design.

Edit Layers and Dependencies to Show the Intended Design

To describe the changes that you plan to make to your system, you can edit the diagram to reflect the updated design. You might also consider making some refactoring changes to improve the structure of the code before extending it. For more information, see Improving the Structure of the Code.

To	Perform these steps
Delete a dependency that should not exist	Click the dependency, and then press DELETE.
Change or restrict the direction of a dependency	Set its Direction property.
Create new dependencies	Use the Dependency and Bidirectional Dependency tools. To draw multiple dependencies, double-click the tool. When you are finished, click the Pointer tool or press the ESC key.
Specify that artifacts associated with a layer cannot depend on the specified namespaces	Type the namespaces in the layer's Forbidden Namespace Dependencies property. Use a semicolon (;) to separate the namespaces.
Specify that artifacts associated with a layer must not belong to the specified namespaces	Type the namespaces in the layer's Forbidden Namespaces property. Use a semicolon (;) to separate the namespaces.
Specify that artifacts associated with a layer must belong to one of the specified namespaces	Type the namespace in the layer's Required Namespaces property. Use a semicolon (;) to separate the namespaces.

Improving the Structure of the Code

Refactoring changes are improvements that do not affect the behavior of the application, but help make the code easier to change and extend in the future. Well-structured code has a design that is easy to abstract to a layer diagram.

For example, if you create a layer for each namespace in the code and then reverse-engineer the dependencies, there should be a minimal set of one-way dependencies between the layers. If you create a more detailed diagram using classes or methods as your layers, then the result should also have the same characteristics.

If this is not the case, the code will be more difficult to change throughout its life and will be less suitable for validation using layer diagrams.

Design New Areas of Your Application

When you start development of a new project, or a new area in a new project, you can draw layers and dependencies to help identify the major components before you start to develop the code.

• Show identifiable architectural patterns in your layer diagrams, if possible. For example, a layer diagram that describes a desktop application might include layers such as Presentation, Domain Logic, and Data Store. A layer diagram that covers a single feature within an application might have layers such as Model, View, and Controller. For more information about such patterns, see Patterns & Practices: Application Architecture.

  If you frequently create similar patterns, create a custom tool. For more information, see How to: Define a Custom Modeling Toolbox Item.

• Create a code artifact for each layer such as a namespace, class, or component. This makes it easier to follow the code and to link the code artifacts to layers. As soon as you create each artifact, link it to the appropriate layer.

• You do not have to link most classes and other artifacts to layers because they fall within larger artifacts such as namespaces that you have already linked to layers.

• Create a new diagram for a new feature. Typically, there will be one or more layer diagrams describing the whole application. If you are designing a new feature within the application, do not add to or change the existing diagrams. Instead, create your own diagram that reflects the new parts of the code. The layers in the new diagram might include presentation, domain logic, and database layers for the new feature.

  When you build the application, your code will be validated both against the overall diagram and your more detailed feature diagram.

Edit the Layout for Presentation and Discussion

To help you identify layers and dependencies or discuss them with team members, edit the appearance and layout of the diagram in the following ways:

• Change the sizes, shapes, and positions of layers.

• Change the colors of layers and dependencies.

  • Select one or more layers or dependencies, right-click, and then click Properties. In the Properties window, edit the Color property.

Validate the Code Against the Diagram

When you have edited the diagram, you can validate it against the code manually at any time or automatically every time that you run a local build. You can also run validation automatically every time you build using Team Foundation Server. 

For more information, see:

• How to: Validate .NET Code Against Layer Diagrams

• Include Layer Validation in the Build Process

To add assemblies or projects manually for validation

1. In Solution Explorer, right-click the modeling project or the Layer References folder, and then click Add Reference.

2. In the Add Reference dialog box, select the assemblies or projects, and then click OK.

To validate code manually from an open layer diagram

1. Right-click the diagram surface, and then click Validate Architecture.

   Note

   By default, the Build Action property on the layer diagram (.layerdiagram) file is set to Validate so that the diagram is included in the validation process.

   The Error List window reports any errors that occur. For more information about validation errors, see Understanding Layer Validation Errors.

2. To view the source of each error, double-click the error in the Error List window.

   Note

   Visual Studio might show a dependency graph instead of the source of the error. This occurs when either the code has a dependency on an assembly that is not specified by the layer diagram, or the code is missing a dependency that is specified by the layer diagram. Review the dependency graph or the code to determine whether the dependency should exist. For more information about dependency graphs, see How to: Browse and Navigate Graph Documents.

3. To manage errors, see Updating the Code to Conform with the New Architecture.

To validate code manually from the command prompt

1. Open the Visual Studio command prompt.

   To open the command prompt, click Start, point to All Programs, point to Microsoft Visual Studio 2010, point to Visual Studio Tools, and then click Visual Studio 2010 Command Prompt.

2. Choose one of the following:

   • To validate code against a specific modeling project in the solution, run MSBuild with the following custom property.

     msbuild <FilePath+ModelProjectFileName>.modelproj
     /p:ValidateArchitecture=true
     

     - or -

     Browse to the folder that contains the modeling project (.modelproj) file and the layer diagram and then run MSBuild with the following custom property:

     msbuild /p:ValidateArchitecture=true 
     

   • To validate code against all modeling projects in the solution, run MSBuild with the following custom property:

     msbuild <FilePath+SolutionName>.sln /p:ValidateArchitecture=true 
     

     - or -

     Browse to the solution folder, which must contain a modeling project that contains a layer diagram, and then run MSBuild with the following custom property:

     msbuild /p:ValidateArchitecture=true
     

   Any errors that occur will be listed. For more information about MSBuild, see MSBuild and MSBuild Task.

For more information about understanding validation errors, see Understanding Layer Validation Errors.

To validate code automatically from a local build

• Use a text editor to open the modeling project (.modelproj) file, and then include the following property:

<ValidateArchitecture>true</ValidateArchitecture>

- or -

1. In Solution Explorer, right-click the modeling project that contains the layer diagram or diagrams, and then click Properties.

2. In the Properties window, set the modeling project's Validate Architecture property to True.

   This includes the modeling project in the validation process.

3. In Solution Explorer, click the layer diagram (.layerdiagram) file that you want to use for validation.

4. In the Properties window, make sure that the diagram's Build Action property is set to Validate.

   This includes the layer diagram in the validation process.

For more information about understanding validation errors, see Understanding Layer Validation Errors. To manage errors, see Updating the Code to Conform with the New Architecture.

Update the Code to Conform to the New Architecture

Typically, errors will appear the first time that you validate code against an updated layer diagram. These errors can have several causes:

• An artifact is assigned to the wrong layer. In this case, move the artifact.

• An artifact, such as a class, uses another class in a way that conflicts with your architecture. In this case, refactor the code to remove the dependency.

To resolve these errors, update the code until no more errors appear during validation. This is usually an iterative process.

Note

As you develop or refactor the code, you might have new artifacts to link to the layer diagram. However, this might not be necessary, for example, when you have layers that represent existing namespaces, and the new code only adds more material to those namespaces.

During the development process, you might want to suppress some of the reported conflicts during validation. For example, you might want to suppress errors that you are already addressing or that are not relevant to your particular scenario. When you suppress an error, it is a good practice to log a work item in Team Foundation.

To create a work item for a validation error

• In the Error List window, right-click the error, point to Create Work Item, and then click the type of work item that you want to create.

Use these tasks to manage validation errors in the Error List window:

To	Follow these steps
Suppress selected errors during validation	Right-click the one or multiple selected errors, point to Manage Validation Errors, and then click Suppress Errors. The suppressed errors appear with strikethrough formatting. When you run validation the next time, these errors will not appear. Suppressed errors are tracked in a .suppressions file for the corresponding layer diagram file.
Stop suppressing selected errors	Right-click the selected suppressed error or errors, point to Manage Validation Errors, and then click Stop Suppressing Errors. The selected suppressed errors will appear when you run validation the next time.
Restore all suppressed errors in the Error List window	Right-click anywhere in the Error List window, point to Manage Validation Errors, and then click Show All Suppressed Errors.
Hide all suppressed errors from the Error List window	Right-click anywhere in the Error List window, point to Manage Validation Errors, and then click Hide All Suppressed Errors.

Include Layer Validation in the Build Process

To ensure that future changes in the code conform to the layer diagrams, include layer validation to your solution's standard build process. Whenever other team members build the solution, any differences between the dependencies in the code and the layer diagram will be reported as build errors.

To validate code when running Team Foundation Build

1. In Team Explorer, double-click the build definition, and then click Process.

2. Under Build process parameters, expand Compilation, and type the following in the MSBuild Arguments parameter:

   /p:ValidateArchitecture=true

For more information, see Define a Build Using the Default Template.

See Also

Concepts

Layer Diagrams: Reference

How to: Create Layer Diagrams from Artifacts

How to: Validate .NET Code Against Layer Diagrams