Layer Diagrams: Guidelines
You can describe your app's architecture at a high level by creating layer diagrams in Visual Studio Ultimate. To make sure that your code stays consistent with this design, validate your code with a layer diagram in Visual Studio Ultimate or Visual Studio Premium. You can also include layer validation in your build process. See Channel 9 Video: Design and validate your architecture using layer diagrams.
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.
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.
Create a layer diagram for the whole application, or for a layer within it.
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.
Discover the existing dependencies between layers.
Edit the layers and dependencies to show the updated design that you want the code to reflect.
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.
Edit the layout and appearance of the diagram to help you discuss it with colleagues.
Validate the code against the layer diagram to highlight the conflicts between the code and the architecture you require.
Update the code to conform to your new architecture. Iteratively develop and refactor code until the validation shows no conflicts.
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.
Important
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.
See Create layer diagrams from 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.
Tip
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. See Discover existing dependencies between layers.
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:
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 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.
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. 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 or Team Foundation Build.
See:
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.
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 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.