How to: Validate .NET Code Against Layer Diagrams

This topic applies to:

Visual Studio Ultimate	Visual Studio Premium	Visual Studio Professional	Visual Studio Express

Validating code against a layer diagram helps you enforce architectural constraints on the code as it evolves. When you perform this task, dependencies in the code are compared with dependencies on the diagram. Layer validation can also help you with the following tasks:

• See the differences between the existing code and its intended design.

• Find code that is not organized as intended or that has unwanted dependencies.

• Find dependencies that might be affected by proposed changes.

  For example, you can edit the layer diagram to show potential architecture changes and then validate the code to see the affected dependencies. For more information, see How to: Create Layer Diagrams from Artifacts and Layer Diagrams: Guidelines.

• Refactor or migrate code to a different design.

  Find code or dependencies that still require work when you move the code to a different architecture.

Before you can validate the code, your Visual Studio solution must include at least one modeling project that has a layer diagram. The layer diagram describes the architecture of the system and organizes namespaces, projects, and other artifacts into logical, abstract groups, or layers. These layers describe the major components of the system or the tasks that those artifacts perform. You must define these layers, link artifacts to them, and describe the intended dependencies between those artifacts.

For more information about layer diagrams, see:

Architect an Application with Layer Diagrams

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

To validate C or C++ code, download and install Microsoft Visual Studio 2010 Visualization and Modeling Feature Pack.

For more information, see How to: Validate C and C++ Code Against Layer Diagrams.

In This Topic

• Add assemblies and projects manually for validation.

• Validate code manually at any time.

• Validate code automatically during a local build.

• Validate code automatically during a Team Foundation Build.

• Troubleshooting issues with layer validation.

Add Assemblies and Projects Manually for Validation

The Layer References folder within a modeling project contains references to the assemblies and projects that are analyzed during validation. When you drag items to the layer diagram, references to the corresponding assemblies or projects are added automatically to this folder. You can also add assemblies and projects manually for validation without dragging them to the layer diagram.

To add assemblies and 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.

Validate Code Manually at Any Time

To validate code 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 Manage Validation Errors.

To validate code 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.

Manage Validation Errors

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:

Validate Code Automatically During a Local Build

Use this method when you want to validate code automatically every time that you run a local build.

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 Manage Validation Errors.

Validate Code Automatically During a Team Foundation Build

To help prevent changes in the code that cause conflicts with the intended design, include layer validation with their builds that run using Team Foundation Build and with gated check-ins, which you can specify by creating a custom MSBuild task. Use build reports to collect validation errors. 

For more information about Team Foundation Build, see the following topics:

• Understand and Use Fundamental Team Foundation Build Features

• Define a Build Using the Default Template

• Define a Build Using the Upgrade Template

• Create and Work with a Custom Build Process Template

• Monitor Progress of a Running Build

For more information about how to create gated check-in builds, see Define a Gated Check-In Build Process to Validate Changes.

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.

Artifacts that Do Not Support Validation

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.

To verify whether an artifact supports validation

1. On a layer diagram, select one or more layers, right-click your selection, and then click View Links.

2. In Layer Explorer, look at the Supports Validation column.

   If the value is false for an artifact link, then that artifact does not support validation.

Troubleshooting Issues with Layer Validation

The following table describes layer validation issues and their resolution. These issues differ from errors that result from conflicts between the code and the design. For more information about these errors, see Understanding Layer Validation Errors.

See Also

Tasks

Understanding Layer Validation Errors

Concepts

Validating Your System During Development