Skinner's Blog : Layer Diagram

Custom Toolbox Items

camerons — Thu, 22 Oct 2009 22:52:48 GMT

[NOTE: This post is part of a blog series, the start of which is here.]

When defining layer diagrams for your organization, or various other modeling concepts and diagrams that you want to make available to your team, you can of course simply check in those diagrams to your version control system, such as Team Foundation Server. But another mechanism we have enabled in the product that can easily be overlooked is the ability to create custom toolbox items from existing diagrams ( UML or Layer ), and then make those available through the VSIX mechanism also new in Visual Studio 2010.

In this post, I’m going to walk you through the steps needed to create a couple different custom toolbox items. ( I’ll talk about the new VSIX capabilities in another post. )

Let’s create a Layer Diagram ( I discuss the basics of what the Layer Diagram is about here ) that can be used as the pattern for a new toolbox item that will appear whenever a Layer Diagram is present in the VS document well.

1) Select the “Architecture->New Diagram…” menu item.

2) Select the “Layer Diagram” in the Add New Diagram dialog, and give the diagram the “PresentationLayer” name:

3) If you are following along exactly, this will prompt you for the name of a new modeling project. Let’s give the project the name of “CustomToolBoxItems”:

Cool. Now the new layer diagram and modeling project show up inside Visual Studio.

What we’re going to do now is replicate a layer diagram that is found in the second edition of the Patterns & Practices Architecture Guide. Specifically, the layer diagram described in Chapter 6: Presentation Layer Guidelines.

4) Create the following layer diagram:

Tips & Tricks, plus a Beta2 BUG ALERT:

I cut a quick video to include with this post to show a couple of suggestions / tips on how to quickly build the diagram above, as well as call out some funky behavior in the Beta2 build that has since been corrected. Here’s that video.

One thing I failed to mention in the video is that you can navigate in and out of nested layers by holding the Shift-> to get the tab to go to inner layers, and Shift-< to go to containers.

5) Save the PresentationLayer.layerdiagram

At this point, you need to create a directory in your %userprofile%\my Documents\Visual Studio 2010 directory.

6) Start a command prompt and cd to %userprofile%\my Documents\Visual Studio 2010

7) Create a directory called “Team Architecture”

8) cd into the “Team Architecture” directory and create another directory called “Custom Toolbox Items”

9) Copy your “PresentationLayer.*” files from your modeling project to the “Custom Toolbox Items” directory.

Here’s an image of my command line actions of steps 5-9:

Ok, we’re almost there. Before we exit Visual Studio, do take notice of the current toolbox window, which should look something like this:

10) Exit and then restart Visual Studio, and create a new modeling project.

11) Create a new layer diagram

Once the new layer diagram is visible, your toolbox should look something like this:

At this point, you can select the “PresentationLayer” toolbox item and drop into your new layer diagram. You should see the exact same diagram that we created in the step 4!

Now this is great, but we also give you the ability to control how these new toolbox items are displayed and organized. Enter the .tbxinfo file.

12) Create a file called “MyCustomItems.tbxinfo” in the “Custom Toolbox Items” directory we created in step 8.

13) Open that file in Visual Studio, and paste the following code:

<?xml version="1.0" encoding="utf-8" ?>
<customToolboxItems xmlns="http://schemas.microsoft.com/visualstudio/2010/TeamArchitect/CustomToolboxItems">
<customToolboxItem fileName="PresentationLayer.layerdiagram">
    <displayName>
      <value>Presentation Layer Pattern</value>
    </displayName>
    <tabName>
      <value>Patterns & Practices</value>
    </tabName>
    <image>
      <bmp fileName="cloudservice.ico"/>
    </image>
    <f1Keyword>
      <value>PLayerHelp</value>
    </f1Keyword>
    <tooltip>
      <value>Create the Presentation Layer As mentioned In Pattern And Practices' Architecture Guidance v2</value>
    </tooltip>
</customToolboxItem>
</customToolboxItems>

Once you save that file, exit Visual Studio, open a modeling project and open a layer diagram, you’ll see the following:

NOTE:

As you play around with these custom tool box items, it is possible that you’ll start to see toolbox items from past experiments. If you start to see things your aren’t expecting, right click in the toolbox and select “Reset Toolbox”:

That’s it! You can experiment with adding more custom toolbox items created by using layer diagrams, and you can do the exact same thing with any of the UML diagrams as well. This is a great way to get started with Design Patterns or any other template you’d like to make more accessible with your engineering team.

Enjoy!

Cameron

[NOTE: This post is part of a blog series, the start of which is here.]

Incorporate Layer Validation in your Builds

camerons — Thu, 11 Dec 2008 08:20:27 GMT

As I promised in my last post, I want to show you how you can make Layer Validation part of your build process. I'm going to assume you've followed along from last post to make things easy. Again, this is all possible in the VSTS 2010 CTP.

Unload the "Client" project ( Right click on the "Client" project and select "Unload Project" )
Once unloaded, right click on the unloaded "Client" project and select "Edit Client.csproj":
Find this line:

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

And add this line right after it:

<Import Project=" $(ProgramFiles)\Microsoft Visual Studio 10.0\Team Tools\Architecture Tools\Microsoft.VisualStudio.TeamArchitect.Validate.Targets"/>

This is a temporary step to make this work in the CTP. At RTM ( and even for Beta ), the new targets file will be part of the core MSBuild targets file.
Save the project, then reload.
You'll be presented with this dialog:
Click on the "Load project normally" and click OK.
Now drag the "FirstLayerDiagram.layer" file from the "Diagrams" solution folder into the "Client" project.
Delete the "FirstLayerDiagram.layer" file from the solution folder.
Select the "FirstLayerdiagram.layer" file that is now in the "Client" project, and set its "Build" action to "Validate":

Now if you did want to leave the "FirstLayerDiagram.layer" file in the "Diagrams" solution folder, you would have to manually edit the "Client.csproj" file, changing this line:

<Validate Include="FirstLayerDiagram.layer" />

to this:

<Validate Include="..\FirstLayerDiagram.layer" />

You're project would look something like this ( notice the little arrow overlay, indicating that this is a reference to a file elsewhere ):
Now at this point you could drop to the command line, assuming the Client.csproj file is in "c:\temp\Layer Validation\Client", and type "msbuild /t:ValidateArchitecture".

Ideally, it would be great to incorporate this step into the build process whenever you build the solution or Client project. You would do something like add a DependsOn="ValidateArchitecture" attribute to the "AfterBuild" target in the project file. Unfortunately, the same bug that requires you to refresh the Architectural Explorer after each build of the project will prevent this from working as it should. Clearly, this will be corrected by RTM.

Hope that helps!

Cameron

Layer Validation with the VSTS 2010 CTP

camerons — Tue, 09 Dec 2008 08:26:25 GMT

In my first post of this series, I broke down the VSTS 2010 Architecture product into "functional" areas, and I've been slowly describing the pieces. The areas highlighted ( Modeling Project here and here, Model Explorer, and Work Item Integration ) I've already discussed at some length. Today, I want to drill into the Layer Diagram a bit more. Specifically, I want to walk you through the steps of creating a simple Layer diagram, map your code onto it, and validate that code against the constraints authored in the diagram via a manual validation gesture. ( In a future post I'll show you how to automate validation in your build process. )

For this post, I'll be using the VSTS 2010 CTP.

In this example, I'm going to be using some very simplistic code, as it is not the details of the code that I'm trying to emphasize, but more the concept the code represents. Let's get started...

Start you VSTS 2010 CTP image
Launch VS 2010
Create a C# console app called "Client", and name the solution "Layer Validation". You're "New Project" dialog should look similar to this:
Now right click on the solution node, select "New Project...", select "Class Library" and name the Project "Implementation":
Do the exact same thing you just did in step 4, except name the project "Interfaces".
Again, do the exact same thing except name the project "Creators". You should have a solution explorer that looks similar to this:
Now expand the "Interfaces" project node. Right click on the "Class1.cs" file, select "Rename", rename the class to IDataRetriever.cs, and click the "Yes" button when prompted. You should now see something like this in your document well and Solution Explorer:
Change IDataRetriever into an interface by replacing the "class" keyword with "interface".
Now add a getter property that returns an object that implements the "IData" interface. You'll notice that VS is indicating to you that IData doesn't exist yet by putting the red squiggles underneath "IData":

Let's resolve this error by taking advantage of a new feature in VS 2010.
Right click on the offending "IData", select "Generate", and select "Other...":
You'll now be presented with the "New Type" dialog. Change the "Type Kind:" drop-down to "interface" and the "Access:" drop-down to "public". Leave the rest as defaults:

VS will automatically create a new interface called "IData" in a new file called "IData.cs" placed in the Interfaces project. Nice, that's exactly what we wanted! Now let's go implement the IDataRetriever interface over in the "Implementation" project.
Expand the "Implementation" project node.
Right click on the "References" node, select "Add Reference...", click the "Projects" tab, and select "Interfaces":
Collapse the "References" node.
Right click on the "Class1.cs" file, select "Rename", change the file name to "DataRetriever.cs", and select "Yes" in the dialog that pops up.
Double-click on the "DataRetriever.cs" file, and make the new class implement the "IDataRetriever" interface. You'll notice that as you attempt to type "IDataRetriever", you get no intellisense support. That's ok, finish typing in "IDataRetriever", and again notice the red squigglies below the term.
Hover over "IDataRetriever" and notice a small rectangle under the start of the word. Click on that and select "using interfaces;". This will automatically insert the using statement that is required.
Now that the "using Interfaces;" line has been automatically added, select the "smart tag" again, but this time select "Implement interface 'IDataRetriever'":

Your final "DataRetriever" file should look like this:
Now add a reference to the "Implementation" project as well as the "Interfaces" project, following the similar steps in step 13 above.
Expand the "Client" project node and double click on "Program.cs".
Type "DataRetriever", select the smart-tag and select "using Implementation;". That will automatically generate the using statement needed to use the DataRetriever type. Finish like so, adding the "using Interfaces;" statement as well:
Rebuild the solution. If all went according to plan, no errors.

So what does this program do at this point? Well, actually nothing except instantiate a type, call a property on that type, throw a "NotImplementedException", then exit. Not that interesting, but also not the point. This is just setting the stage for a very common problem found in systems of all types.

This code is pretty typical of code that is early in its evolutionary path. We've got a client program accessing the specific implementation of an interface directly. This is fine for now, as all the program needs is the data that "DataRetriever" was designed to retrieve ( imagine DataRetriever pulling from a SQL database for instance ). But what about tomorrow when a requirement hits your desk, demanding data to be pulled from a different data source without changing the behavior of the rest of the application?

What we need is to *not* make any assumptions on *how* an interface is implemented, and depend *only* on the contract of the interface(s) itself. Again, a fairly common design pattern, but one that is pretty easy to violate in today's world, as it takes but one line of code to break this pattern and create dependencies that were not intended. This is what various IoC containers are out to help mitigate.

So how do we enforce this design in our code, protecting the intent of that design, and ensure our code is resilient to this type of breakage? Enter the Layer Diagram and Layer Validation.

Let's create a Layer Diagram where we will visually describe the constraints on our architecture that we want to maintain.

Create the Layer Diagram

Right click on the solution node and select Add->New Solution Folder. Name the folder "Diagrams"
Right click on the "Diagrams" solution folder and select Add->New Item..., select the "Layer Diagram" template, and name the diagram "FirstLayerDiagram.layer":
Since these are CTP bits, there are still a few things not quite right. One of these things is the fact that you'll see two Layer Diagram Explorers appear next to your Solution Explorer. Close the one that looks like this:
Now let's draw the layer diagram, make your diagram look like this one:

Please make sure that the links are going in the direction you see above, or things aren't going to work right in later steps!

What we're saying through this diagram is that we have a "Client Logic" layer that is dependent on the "Interfaces" layer, and an "Implementation" layer also dependent on the "Interfaces" layer. What we are also saying is that the "Client Logic" layer is *not* dependent on the "Implementation" layer, nor should it be. The lack of a directed link in this last case is very important.

But now we need to map our source code onto this layer diagram, so that the system can verify that your code is complying or *not* complying with the constraints this seemingly simple diagram is describing.

Let's do that now.

Map Source Onto the Layers

In the Solution Explorer, click and drag the "Client" project out onto the layer diagram and release your mouse on the "Client Logic" layer shape:
Drag the "Interfaces" project from the Solution Explorer out onto the layer diagram and let go over the top of the "Interfaces" layer shape:
And finally, drag the "Implementation" project from the Solution Explorer out onto the "Implementation" layer shape:
Your layer diagram should now look something like this. Notice the little icons in the upper right hand corner of the shapes. This indicates that source ( or some type of artifact(s) ) has been associated to the layer:

If you select the "Client Logic" shape, then click on the "Layer Explorer", that shows you the types of items associated with the layer. In this case, the "Client" csharp project:

Now we're ready to "Validate" our code against the diagram.
Right click anywhere in the layer diagram and select "Validate":

Notice an error is displayed in the Error Window:

This is expected at this point, 'cause the code in Program.cs found in the "Client" project is directly manipulating types from the "Implementation" project. We just finished creating a layer diagram that declares this type of dependency invalid!

So let's fix the problem in code so that this layer validation error goes away.

Fix Code

Back in Program.cs, we need to make sure that we are only using types out of the "Interfaces" project, or more importantly, *not* use types out of the "Implementation" project. That's all well and good, but we need a way to get an instance of an object that implements IDataRetriever without taking a direct dependency on that type.

Enter the Factory pattern.

In the Solution Explorer, expand the "Creators" project, right click on "Class1.cs", select "Rename...", and rename the file to "TypeCreator.cs".
Add the "Implementation" project and "Interfaces" as a references to the "Creators" project ( i.e., "Creators" now depends on the "Implementation" and "Interfaces" projects ).
Double click on the "TypeCreator.cs" file in Solution Explorer, which will make that file fill the document well.
Add a static method that creates a "DataRetriever" object but returns an IDataRetriever interface. TypeCreator.cs should look similar to this:
In the "Client" project, remove the "Implementation" project reference, and add a reference to the "Creators" project.
Change Program.cs to take advantage of the new method we just created. Program.cs should look something like this:
Rebuild the solution. No errors.

Now we need to bring up the Architecture Explorer and click the refresh button to work around a current limitation in the CTP bits.
From the main menu bar, select "View->Architecture Explorer".
Select the "Refresh Content" button on that explorer:
Now bring the FirstLayerDiagram back into view, right click on "Validate", and take a look at the error tool window. No errors! WooHoo! :)

Summary

I've shown you, through an admittedly trivial example, how to validate your solution through a simple Layer diagram. I've shown you how to map source onto the layers and how to tell the system what dependencies are valid and which are not via a manual gesture and that diagram.

There is much more to show on this diagram and how you can interact with it. A very important next step is to show you how to make the Validation action an automatic step in your build process. I'll do that in a future post.

Stay tuned! :)

Cameron

Architectural Validation and Synchronization

camerons — Tue, 30 Sep 2008 23:20:22 GMT

In one of the articles that just hit recently around our upcoming "Architectural Validation" feature in VSTS 2010 Team Architect, there was concern around how to "maintain all those diagrams" in context of the Architectural Validation or Layer Diagram feature. I wanted to shed a bit more light on how the association between your code and the diagram is made and maintained. We have not really discussed this nearly as much as we should, other than a quick "Map your physical assets..." comment I made in step five of this post.

Basically, I want to point out that the risk of the Layer Diagram and your source getting out of synch really depends on how you choose to use the tool.

Association with artifacts can occur in the following ways

Link to a single artifact e.g. a class

Out of sync risk = medium high
Depending on the number of deletes and renames, layers linked to classes can have stale links. However, these are shown as warnings and can be cleaned up quite easily.

Link to a group of artifacts using a container e.g. namespace

Out of sync risk = low
Linking a layer to a namespace indirectly links the layer to all classes in the namespace. Validation will start at the namespace and process everything in it. This indirect link allows the validation to adjust to changes to individual classes rather well.
Namespaces themselves do not change as often.

Link to a group of artifacts using a query

Out of sync risk = very low
A query links to dynamic collection of artifacts. The query is evaluated every time you validate. Hence, like the namespace example above, changes to the results of the query are automatically factored in.

Build time validation

The integration with builds and check ins make this feature a lot more useful and bring it to the forefront of the development process. This also has the side benefit of forcing updates if they’re required.

Layer Diagram

camerons — Fri, 11 Jul 2008 18:51:22 GMT

At TechEd2008 this year, the Rosario April CTP version of the VSTS Architecture Edition bits were demo'd during BillG's keynote by Brian Harry. Brian demonstrated the Architecture Explorer and the Layer Diagram. The Architecture Explorer is part of the April CTP, but the Layer Diagram did not make that CTP. I've received so many questions about that designer that I wanted to elaborate on the features of the diagram that you saw in the keynote, and describe the problem that diagram is out to help solve.

The Layer Diagram is designed to allow you to specify the various layers that make up your system's architecture. It is a way to describe what you believe your architecture is, and then provides you a way of discovering what it really is. :)

The diagram itself is very simple in notation, with only two main tools in the Layer palette, the "Layer" shape and the "Dependency" link. You can name those layers, describe allowed dependencies between those layers ( more on this later ), map your existing assets ( code, docs, what have you ) onto those layers, and validate that your architecture is conforming to the diagram.

Here's a very simple layer diagram that shows a typical system with a UI or Presentation, Business or Domain Logic, Data, and Logging layer:

Here is that same diagram "annotated" a bit, to describe some of the capabilities in the diagram:

There are a number of ways you can approach this diagram, below is one:

1. Create a new Layer diagram from scratch

2. Draw the various Layer shapes and name them appropriately

3. Use the Dependency connector to indicate the direction of allowed dependencies. As I mentioned in the annotated image, the lack of dependency links is also meaningful, in that you are indicating to the system that dependencies between two layers is not allowed.

4. Specify additional constraints per layer that you would like to see enforced. As an example, you will be able to indicate on a per layer basis what namespaces are allowed in that layer, and which are not allowed.

5. Map your physical assets to your specified layers. You map your assets ( code, documentation, entire projects or solutions ) via drag & drop from the Architectural Explorer and Solution Explorer. ( Later in the cycle, there will be more capabilities added around this step. )

6. Validate your architecture

This last step is where things get interesting. Steps 1-5 were all about specifying what you believe your architecture is and should be. Step 6 is all about telling you what it is.

But when does validation occur, and what do violations look like?

Validation can be done via a simple context menu gesture ( right click on the diagram and select "Validate" ), or as part of a check in policy, and as part of your build. The product will examine your Layer diagram ( you can have many by the way ), discover what assets are mapped and what constraints are being specified, and then analyze those assets with those constraints in mind.

A violation ( currently ), shows up in the Error window.

This should give you a better idea of what this diagram is all about, and you'll be able to take it for a test drive in our next CTP this fall.

Cheers,

Cameron