Layer Diagrams: Guidelines

Describe your app's architecture at a high level by creating layer diagrams in Visual Studio. Make sure that your code stays consistent with this design by validating your code with a layer diagram. You can also include layer validation in your build process. See Channel 9 Video: Design and validate your architecture using layer diagrams.

To see which versions of Visual Studio support this feature, see Version support for architecture and modeling tools.

What is a layer diagram?

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. See Layer Diagrams: Reference.

How to design or update your app with 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.

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, create a new modeling project for the layer diagram, or copy an existing layer diagram within the same modeling project.

See Create layer diagrams from your code.

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 from Visual C# .NET and Visual Basic .NET projects, 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 specific 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](https://apparch.codeplex.com/Wiki/View.aspx?title=Application Patterns&referringTitle=Home).

When updating an unfamiliar application, you might also create code maps. These diagrams can help you discover patterns and dependencies while you explore the code. Use Solution Explorer to explore namespaces and classes, which often correspond well to existing layers. Assign these code artifacts to layers by dragging them from Solution Explorer to layer diagrams. You can then use layer diagrams to help you update the code and keep it consistent with your design.

See:

• Create layer diagrams from your code

• Use code maps to debug your applications

• Map dependencies across your solutions

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.

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 or the intended architecture, use the following steps to edit the layer diagram. You might also consider making some refactoring changes to improve the structure of the code before extending it. See Improving the structure of the code.

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](https://apparch.codeplex.com/Wiki/View.aspx?title=Application Patterns&referringTitle=Home).

  If you frequently create similar patterns, create a custom tool. See 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 or Team Foundation Build.

See:

• Validate code with layer diagrams

• Include Layer Validation in the Build Process

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. For more information about these errors, see Validate code with layer diagrams.

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 perform this task, see Validate code with layer diagrams.

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. For more information about including layer validation in the build process, see Validate code with layer diagrams.

See Also

Layer Diagrams: Reference Create layer diagrams from your code