Skinner's Blog : tsbt-arch

PDC 2009

camerons — Thu, 05 Nov 2009 20:33:44 GMT

Realized I haven’t mentioned that I am planning on giving a talk at this year’s PDC. Here’s that abstract:

Visualization, UML, and DSLs

Cameron Skinner

Microsoft Visual Studio Team System 2010 Architecture Edition introduces a whole host of new designers and modeling tools to help enterprises and teams build software. UML Diagrams and the Layer Diagram can be used to plan and design the assets your team will produce, and communicate effectively about those designs during the entire development lifecycle. The Architecture Explorer and Graphs help you investigate and better understand the assets you have to enable more effective planning and decision making. Come learn how you can use all of these tools when investigating your current assets, and planning and designing your future work.

I hope to see you all there!

One other thing that I also want to mention is that Jens Jacobsen, a Program Manager on my team, has just started blogging. His first-time post is right here.

I’m looking forward to watching what Jens comes up with, as he is planning on focusing in on how to improve overall User Experience of the tooling we are producing, now and into the future. He is uniquely qualified to lead the charge on this as he has deep experience in user experience research.

So check out his blog and give Jens some feedback / participate in future discussions he begins.

Thanks!

Cameron

Providing Feedback

camerons — Mon, 26 Oct 2009 20:22:11 GMT

By now, you’ve pulled down the Beta2 bits and have started exploring. ( No you say? Please check this post for details on how to get the bits…. )

You may have questions, want to express concerns, find bugs and want to report them, or in general just look for more venues where topics specific to the Architecture and Modeling tools in Visual Studio 2010 can be found.

The MSDN forums are the place to start, and in particular, the following two forums have been created for the Beta2 bits:

Visual Studio Architectural Discovery & Modeling Tools
”Discuss the code visualization and modeling tools in Visual Studio 2010, such as Architecture Explorer, dependency graphs, UML diagrams, and layer diagrams”

Visual Studio 2010 Domain-Specific Languages (DSL) & Modeling Tools Extensibility
”Discuss the Microsoft Domain-Specific Language (DSL) Tools and extending the architecture and modeling tools for Visual Studio 2010”

As the product roles into RTM, these forums will be the place to directly interact with MVP, fellow users, and of course the folks from Microsoft that actually built the product!

See you there! :)

Cameron

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.]

DSL SDK for Visual Studio 2010 Beta2 Released

camerons — Thu, 22 Oct 2009 17:20:10 GMT

Jean-Marc has just posted some great details on the Beta2 version of the DSL SDK.

The amount of capabilities that have gone into the DSL Toolkit this version has been great to see. That team has done a fantastic job of increasing the power of what a DSL created via the toolkit can get done.

Man, this has been a crazy week, in all the best of ways! :)

Lovett is Blogging!

camerons — Mon, 19 Oct 2009 22:44:59 GMT

Chris Lovett, an architect on my team who has a glorious and long history with Microsoft, has finally joined the blogosphere! His expertise is all things .NET, but in particular he knows the code behind the new DGML graphs and dependency diagrams that are new in Visual Studio 2010 Ultimate.

His first two posts are fabulous, both of which include videos of Chris walking through some of the power of the DGML graphing technology. Be sure to check out his “teaser” post here, and a more in-depth post on our Standard Dependency Graphs.

Be sure to subscribe to his blog, as I know he’ll be putting up quite a bit more content in the weeks ahead.

You’ll be glad you did! :)

“First-time Experience” with Arch Tools

camerons — Mon, 19 Oct 2009 21:13:15 GMT

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

Ok, you’ve downloaded the Beta 2 bits of Visual Studio 2010 and .NET Framework 4.

Now you want to explorer the new Modeling and Visualization tools. This post will help you make those first couple of steps.

1) Launch Visual Studio

Notice the new top-level menu item called “Architecture”:

With no solution open, selecting the menu item simply results in the following:

2) Select “New Diagram…”

After a couple of seconds, a dialog box appears, which looks like this:

This dialog makes it very easy to see all the diagrammatic capabilities that are new in 2010. You see the ability to create a total of five different UML diagrams, a Layer Diagram option, and last but not least, the Directed Graph Document.

I’ll go into detail on all these later, but for now, just accept all the defaults and hit the OK button.

Now, because you do not have any solution open, you will see the following dialog:

( You’ll see the same dialog even if you have a solution open, but no Modeling projects exist in the solution ).

BUG ALERT:

Unfortunately, a little bug slipped through the cracks that I want to point out so you don’t waste your time logging a bug that has already been fixed.

If you hit the cancel button at this point, you’ll see this dialog:

You can hit the OK button and no harm will be done, but not quite the experience we’re looking for. ;)

Take the defaults and hit the OK button. You should see something similar to what you see in the image below ( minus my red annotations of course ):

At this point, your ready to start adding items to the class diagram to your hearts content. This is a pretty common first couple of steps that you will take as you start using VS 2010 Ultimate to model your problem domain using the various UML diagrams.

The steps above are very similar if you have an existing solution already open, but I do want to point out a couple of differences. The steps below are quite common when you are looking to the tool to help you understand an existing code base.

3) Open an existing solution

Just open any solution you’ve got within reach. I’m going to open up the old standby, Petshop 4.0. ( This will result in the current solution being closed, but don’t worry about that. )

Once your solution is opened, you’ll see some new additions to the “Architecture” menu item:

Go ahead and try one of the menu items out. I selected the “Generate Dependency Graph->By Assembly” menu item, which resulted in a graph that looks like this:

Don’t worry about the details on this yet. We’ll be diving into those details in future posts. For now, we’re just kicking tires.

One last thing to point out before calling this post done.

4) Open up a source file

In my case, I’m going to open up the Order.cs file in the OracleDAL project.

Find a decent size method in your class, right click in the text editor, anywhere within the method and select …

5) Generate Sequence Diagram

You’ll see this dialog:

Just take the defaults and hit OK. In my case, a diagram is generated that looks like this:

Again, I’m not going to go into any more detail on this than I have just done. I just wanted to point out a few very common ways into some of the new features in the product.

As I pointed out in this previous post, I’ve got a lot of topics I’m going to nail down for you. I don’t have any specific order that I’m committed to following, so if you have some preferences of which topics I do first, please let me know!

Cameron

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

Visual Studio 2010 and .NET Framework 4 Beta 2!!!

camerons — Mon, 19 Oct 2009 16:37:00 GMT

Ok, it has been a little while since I blogged last, but it is for good reason, and now’s the time to show you why.

The entire Visual Studio team, including my own, have been working extremely hard to get the Visual Studio 2010 Beta 2 release squared away, and I’m very pleased to announce that those bits have been made available as of 9:00 AM PDT today! ( See Soma’s announcement here. )

WooHoo!!!

There have been simply a *ton* of changes to the product since last we chatted, both from a functionality perspective ( we’ve made lots of progress that I can’t wait to tell you about! ) to changes in the Visual Studio SKU structure, to logo and name branding, and pricing changes. MSDN itself has been redesigned!

But first and foremost, if you are an MSDN subscriber, stop what you are doing and go down load Beta2 and the .NET Framework 4 bits from this link. I really think you’re going to like what you see! And Beta2 is a “Go Live” release, which means we are encouraging you to use the product in production, with an implied understanding that if serialization formats or what have you change between now and RTM, we’ll provide a way to move your data and artifacts forward so that you don’t lose any work.

If you aren’t an MSDN subscriber, general availability for the release will happen on October 21st.

To get more information on the new packaging and licensing details, please visit this link. But here’s a taste of the new Visual Studio 2010 logo:

And to top everything else off, the official launch date for Visual Studio 2010 and .NET Framework 4 is March 22nd, 2010!

SKU Structure Change

A couple words about the changes that you can read more about here. The Architecture Edition, along with many of the features of the Team System 2008 Development box, are now part of the Visual Studio 2010 Ultimate product.

The Visual Studio product line has moved to more of a “Russian Doll” model in regards to how the features are represented in each version of the product. At the top of the stack, including all the features and functionality of Visual Studio 2010 Premium and Visual Studio 2010 Professional, is the capabilities found in Visual Studio 2010 Ultimate. Going forward, I’m going to be spending my time with posts describing the Modeling and Visualization technologies in Ultimate, as that is what I know best, as that is what my team does. :)

But quickly, here’s a general view of the capabilities found in the new SKU structure. Please understand that from a feature perspective, Ultimate contains everything you see in this list ( all the Premium + Professional features ), plus the Ultimate specific features.

The features in red are the ones my team is responsible for delivering. Those features are the ones I will continue to blog about in depth in the days and weeks ahead.

Microsoft Visual Studio 2010 Ultimate ( includes all features from Premium and Professional SKUs ):

IntelliTrace
UML Modeling
Layer Diagram & Architectural Validation
Architecture Explorer
Web Testing
Load Testing

Microsoft Visual Studio 2010 Premium ( includes all features from the Professional SKU ):

UI Test Automation
Test Impact Analysis
Performance Profiling
Static Code Analysis
Code Coverage
Code Metrics
Database Change Management
Database Deployment
Database Unit Testing
Test Data Generation
Read-Only UML, Layer, and DGML Graphs

Microsoft Visual Studio 2010 Professional:

Silverlight Tools
Multi-Core Development
Sharepoint Development
Cloud Development
Web Development
Windows Development
Generate from Usage
Office Development
New WPF Editor
Customizable IDE

So stay tuned, as I’m planning on a number of posts that are designed to drill into the new features available in this beta 2 release of Visual Studio!

Cameron

DGML, Containers, and VSTS 2010 Architecture Rendering

camerons — Mon, 23 Feb 2009 05:58:00 GMT

I previously pointed out how easy it was to manipulate and then render a .dgml file in the upcoming VSTS 2010 Architecture product. I want to continue that discussion by showing how easy it is to indicate to the product that you need to see nodes contained inside another, and a few other niceties along the way.

NOTE:

I do need to make one thing clear before we move forward. The difference between the core DGML and the additional capabilities you will find in the Architecture product is significant. The core DGML markup is limited to very few elements: DirectedGraph, Nodes, Node, Links, Link, Categories, and Category. Any additional markup beyond those basic elements is specific to the VSTS Architecture product.

So we had previously started with a graph that looked like this:

In order to tell the VSTS 2010 Architecture product's DGML rendering engine to draw a container around the "From" node, you first start by adding another Link element that has the Source attribute named "My Container" ( value doesn't matter ), and the Target attribute's value set to "From" ( this value does matter ). When you add that to your graph, you'll see this:

Not exactly containing the "From" node at this point, but we're not done. We need to add two more things to the markup.

The first step is to add a Category element to the Link element we just added, with a value of "Contains". Markup should now look like this:

The second step is to add a Nodes element with a single Node element contained inside, like so:

The resulting graph looks like this:

Let me point out a number of things, and bring them to your attention. In the image below, I've selected the contained "From" node:

This is a number that indicates how many nodes are actually contained in the container.
The Id of the container. The Id must match the Source attribute value of the Link element that has the "Contains" Category attribute applied to it. You can further include a Label attribute to the Node element in order to use a different value for the container's title than the Id value. VSTS 2010 Architecture defaults to the Id value when the Label attribute is not present.
A chevron that can be clicked resulting in a collapsed or expanded container. The container in this example is clearly expanded, allowing you to see the contents of the container in the graph. The expanded state is captured in the dgml file via the value of the Group attribute on the Node element set to "Expanded". Setting that value to "Collapsed" collapses the container, hiding its contents. Here's a shot that shows the results of setting that value to "Collapsed" as well as using the Label attribute on the Node element:
This is showing that I have selected the "From" node.
Because I have selected the "From" node, the link between the "From" node and "To" node shows up. If you aren't selecting "From" or the "To" nodes, that link disappears.

That's it! I should also add that you can have as many levels of containment as you'd like. Hope that helps!

Cameron

DSL Multiple Views example and other links

camerons — Tue, 27 Jan 2009 21:29:54 GMT

Mr. Provost was recently interviewed by the ElegantCode folks. Find that podcast here.

Wanted to make people aware of the excellent work two of our MVPs ( Pascal Recchia and Anthony Guerot ) have done recently with the DSL Toolkit. Checkout this great article on how they have manipulated the DSL API in order to get multiple views over a single store. They have also provided access to a video showing the functionality, as well as the code they created.

This is great stuff, and does show the power of the DSL framework that we have built the UML designers coming in VSTS 2010 on.

With the 2010 product, we hope to make this type of functionality even easier, with even more extensibility options possible with new APIs we will be providing.

Enjoy!

Directed Graph Markup Language ( DGML )

camerons — Tue, 27 Jan 2009 00:03:57 GMT

In this previous post I introduced you to the new format, and then this follow on post showed some of the examples of how the format is used to back some common graphs you can expect in the product.

In this post, I'm going to talk about a couple ways of controlling how links are rendered in the VSTS 2010 Architecture product.

The Graph Element

At the root of every DGML document is the DirectedGraph element. The default namespace for this document, attributed to this element, is http://schemas.microsoft.com/vs/2009/dgml. There are a number of xml attributes that is supported for this element that you will be able to quickly discover through the intellisense functionality off the file, but I want to call out the Background attribute in particular.

The Background attribute allows you to set the color of the background of the graph surface itself, either by name of ARGB hex values as documented here.

For example, this snippet of DGML:

Results in this graph:

Amazing, but good to know nonetheless. :)

The Link Element

A DGML graph is fundamentally all about nodes and the links between those nodes. You'll notice in the markup above the Links element containing one Link element. You'll also notice that the rendering engine that reads this particular DGML is smart enough to understand that a link cannot exist without nodes to connect, so automatically creates a "From" node and a "To" node based on the values found in the Source and Target attributes on the Link element.

The Link element has a number of interesting attributes that are directly supported. I'll call out a few here.

In order to change the background color of a link arrowhead, set the Backround attribute to "Red". You'll get something like this:

In order to change the color of the entire link, set the Stroke attribute to your desired color. If you only specify Stroke and not Background, the arrowhead fill color will also be changed to the Stroke color value.

You can also change the thickness of the link itself by assigning a value to the StrokeThickness attribute, like so:

You can also make the link a dashed line by playing with values in the StrokeDashArray attribute. The comma delimited values are converted to doubles, and are taken in relation to the StrokeThickness value, which is 1 by default. For example, setting StrokeDashArray to 5 with a default thickness of 1 results in something like this:

You can make the dashed line much more involved by adding more values to the dash array, as specified here. Here's an example:

Summary

Just a quick taste on how to control link rendering. We'll start to build up more knowledge as we go. In a future post, I want to show the Node element, and specifically get into how grouping / nesting is supported. Stay tuned!

Visualize Java Code

camerons — Tue, 20 Jan 2009 08:09:10 GMT

In this last post I introduced you to some *very* basic understanding of how DGML works. Now I want to take that knowledge out for a test drive. :)

What I've decided to do is a couple of things. I've decided I'm going to show how to visualize Java code using Antlr and Visual Studio 2008 and output a DGML file that the VSTS 2010 Architecture product found in the latest CTP can render.

Why am I doing this? Because I think it will be an excellent example ( you'll be the judge of that ) of how easy it will be to visualize all kinds of data, not just .NET languages. Java code, Work Items, MSBuild dependencies, on and on. Literally, this list is potentially enormous, gated only by imagination and effort ( aren't all good things this way? ).

In some future posts, I'll show how you can continue to tweak the DGML to do some things that you can't do in the current CTP, but can with current bits ( such as node grouping, advanced selection, etc. ).

Prerequisites

If you want to follow along on this little journey, you need to get the following things:

Visual Studio 2008
Latest JDK from Sun. Lots of options here but I ultimately went here and followed the steps.
Antlr 3.1.1 ( see below for instructions )
VSTS 2010 CTP ( follow link for instructions )
The Visual Studio 2008 solution that I used to create this post

Establish "Base of Operations"

I'm going to be very descriptive of what I'm doing 'cause the complication is not going to be in the implementation, but more in the "configuration of the parts".

Create a directory where work will be done. This will be our "Base of Operations". From here on out, I'll refer to this directory as %BOO%.
Download Antlr 3.1.1
1. If this link becomes stale, go to http://www.antlr.org and download the latest source distribution which includes the runtime jars that you'll need.
Extract the contents of the download to the %BOO% directory. When done, you should have the following contents in the %BOO%\antlr-3.1.1 directory:
Ensure Java is installed correctly
1. Open up a command prompt, CD to your %BOO% directory.
2. Type the following: java -?
3. If you don't see a typical "Usage" statement, then you probably have something installed wrong. For me, I had to make sure that the java bin directory was in my path, so I added that to my system environment variables.
Create a BOO.bat file that contains the following contents, and save to %BOO%:

set BOO=%CD%
set ANTLR_LIB=%BOO%\antlr-3.1.1\lib
set classpath=.;%ANTLR_LIB%\antlr-3.1.1.jar;%ANTLR_LIB%\antlr-3.1.1-runtime.jar;%ANTLR_LIB%\stringtemplate-3.2.jar;%ANTLR_LIB%\antlr-2.7.7.jar
Ensure Antlr is now ready to go.
1. At the command prompt, type BOO.bat and hit enter
2. Now type java org.antlr.Tool and hit enter
3. You should see this:
  
  If you don't, double check your BOO.bat file and make sure you don't have any typos.
Feel free to download the original Java.g file also available on the Antlr site. I've included the one I have modified in the solution I've made available in the "Prerequisites section":
1. Click here.
2. If it looks like a page just full of text, right click and say view source, then "Save As..." java.g into your %BOO% directory.
Unzip the solution I created into your %BOO% directory.
You'll need to replace the references to antlr.runtime, Antlr3.Runtime, Antlr3.Utility, and StringTemplate to those now in your %BOO% directory:
1. Add Antlr C# runtime references to the project.
  1. First we have to extract the runtime files found in the %BOO%\antlr-3.1.1\runtime\CSharp\dist\DOT-NET-runtime-3.1.1.zip.
    1. Extract the contents of that zip to %BOO%\antlr-3.1.1\runtime\CSharp\Libraries
    2. Once extracted, you should have a bin directory.
  2. Right click on the References node in the project
  3. Click on the Browse tab.
  4. Navigate to %BOO%\antlr-3.1.1\runtime\CSharp\Libraries\bin\net-2.0
  5. Add all the dlls found in that directory as references. There should be four dlls in there, as mentioned above ( If you do everything I've just mentioned just right, this step shouldn't be necessary, as the solution I provided should be relative )
OK, we're ready to build.
1. Rebuild the solution.
If all went well, you now have a parser that's ready to parse Java 1.5 code!

Results

The executable created after building the solution is Java2DGML.exe. If you drop to the command line, CD into the debug directory where the exe is found, run the following command:

Java2DGML.exe /f %BOO%\antlr-3.1.1\src\org\antlr\Tool.java > Tool.dgml

then open Tool.dgml in the VSTS 2010 CTP, here's what you'll see:

Here's the XPS file of that image as well.

The exe is by no means a robust piece of software. It currently understands how to gather information for simple Java classes ( i.e., not templated ), fields, and methods. No interfaces, enums, etc., but after this post, you should have all the info you need to take this example a bit farther.

Now let me explain the source a little bit...

Taxonomy of the Solution

Here is a shot of the Solution Explorer with the Java2DGML solution loaded:

Generated Files

Java.Tokens, JavaLexer.cs, and JavaParser.cs are all generated files. You can regenerate those files by executing the following command in you command window where you executed BOO.bat, in the %BOO%\Java2DGML\Java2DGML directory:

java org.antlr.Tool Java.g

Java.g

The Java.g file is where the grammar for parsing Java 1.5 is defined. This grammar file instructs the org.antlr.Tool object how to generate a parser in C# capable of parsing Java 1.5 code. More on this later.

DGMLContext.cs

A simple utility class used to gather information during the parse that is later used to generate the appropriate DGML. For every Java class, one DGMLContext object will be created to capture the relevant details.

DGMLFile.st

Antlr has a great mechanism built in called the StringTemplate framework. Check out this link for more details. This file is an example of a StringTemplate for DGML files. More on this later.

JavaParserImpl.cs

Antlr allows the C# developer to tell Antlr to create a partial class for its parser implementation so that additional behavior can be added and used in the grammar file more easily. I've taken advantage of that in this file.

Program.cs

This is the main program, where all the pieces come together.

Summary

This post is really meant to whet your appetite on some of the possibilities coming in the 2010 version of the Architecture product around visualization. Admittedly, I'm clearly just scratching the surface of this particular example ( Java source visualization ), but that's ok. From time to time, I may come back to this example and flesh out a little more in order to exemplify some deeper features.

In the meantime, I think in my next post I'll start to show some more of the features inherent in DGML, beyond just the simple nodes and links I've shown to date.

Stay Tuned!

"Standard Graphs"

camerons — Thu, 18 Dec 2008 03:04:47 GMT

It became clear from the emails and comments to my last post that I should probably spend a little more time describing the functionality found in the VSTS 2010 CTP a bit better, specifically that functionality involving the Architecture Explorer and the graphs generated via the AE. ( I just figured everyone had already run out, downloaded that 7.5gig image, and started playing! :) )

This post introduces the three "Standard Graphs" found off the Architecture Explorer using the DinnerNow - ServicePortfolio2 solution found in that aforementioned CTP. The idea behind these graphs are to give you the ability to get some "typical" views of your source base with as few mouse clicks as possible.

Standard Graphs

Here's a shot of the Archicture Explorer, as seen with the DinnerNow solution open in VS 2010:

You'll notice the Visualize Code Relationships menu item, which is where you'll find the three menu items that will create graphs by Assembly, Namespace, or Class dependencies based on the contents of the current solution.

Visualize Call Dependency - By Assembly

If you select the Visualize Call Dependency - By Assembly menu item, here's what you'll get:

This graph is all about showing you the dependencies between the various assemblies that make up all the projects in your solution. If you don't have the solution built, you'll notice that after selecting this menu item ( this will happen for any "standard" graph actually ) the solution is built. This is due to the fact that we are cracking the assemblies in the output directories and gathering the information found there.

The nodes you see above represent each of the assemblies discovered in this solution. You'll also notice links of various thickness between these nodes. The thicker the link, the more dependencies between the two assemblies. We sometimes refer to these types of links as "blood vessels".

Notice the chevrons in the upper right hand corner of the nodes in this graph:

This is an "expand / collapse" button for this "group" node. You'll also notice in the upper left corner of each node, a number indicating the number of internal nodes inside the group. Here's what the DinnerNow.Services assembly node looks like when expanded ( click for larger view ):

The green and blue nodes represent Classes and Interfaces. You'll notice in the shot above the tooltip displayed as I hover over the CustomerService node, the category reads "Class". If I double-click on that node, it takes me to the source code where that class is defined.

Visualize Call Dependency - By Namespace

Selecting the Visualize Call Dependency - By Namespace results in a similar type graph, except this time the initial nodes you see below represent the namespaces found in the solution:

Clicking on the chevron of the DinnerNow.Services node shows the exact same information as it did when viewing from the Assembly diagram ( show below in-situ ):

Visualize Call Dependency - By Class

Selecting the Visualize Call Dependency - By Class results in the most complicated of graphs, mostly because what you are seeing is dependencies at the class level, with no grouping by assembly or namespace. Expanding a chevron in this graph reveals methods, properties, fields, indexers, etc. that are contained by that class or interface. Below is a shot of just a section, as the graph is pretty large:

One thing to point out if you haven't already discovered this, is that if you hover your mouse over a particular link, you can quickly jump to either end of the link. Quite helpful on large graphs like the Class dependency graph!

One other thing worth mentioning. The dependencies discovered on these graphs are dependencies discovered through static analysis of method call data, not structural dependencies. For example, if you have two classes that don't call each other but one includes the other as a type for a member, no dependency link will be created.

What other "Standard Graphs" should we include out of the box? What are some typical views over your solution that you would like one to two clicks away?

Thanks!

Cameron

Introduction to Directed Graph Markup Language ( DGML )

camerons — Tue, 16 Dec 2008 23:59:53 GMT

DGML, or "Directed Graph Markup Language" is what we are using in VSTS 2010 Architecture to render graphs like the one below:

The power of DGML is in its simplicity. Let me show you what I mean.

If you launch the VSTS 2010 CTP, open a project, click View->Architecture Explorer, then click the button shown below...

...you'll get a new dgml editor in the document well. You can then right click inside that document and select "View Code". Right click on the tab of the resulting editor and select "New Horizontal Tab Group". You'll have something similar to this:

If you add a Link element as a child element to the Links node, with a Source and Target attribute, you'll get something similar to this:

To add a few more elements, try this:

You'll notice the Nodes element isn't even needed to render the graph above. That is really all you need to know to visualize all kinds of data. Rest assured there is a lot more goodness to discuss about this technology, but the simplicity of it is one of the most exciting aspects as far as I'm concerned!

In my next post, I'm actually going to show you how, armed with just this little nugget of DGML information, you can visualize some Java code. Stay tuned!

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

The UML Model Explorer

camerons — Mon, 01 Dec 2008 12:23:46 GMT

In the VSTS 2010 Architecture product, we've added another toolwindow to VS designed to help you understand and manipulate the UML models that you will be building. The UML Model Explorer ( that's what we're currently calling it, but that can certainly change :) ) is a WPF component that represents the UML Package hierarchy of your models. "Models" in this context refer to the contents of the Modeling projects you have created and added to the current solution. The root node or nodes of the UML Model Explorer are UML packages representing those Modeling Projects.

For example, in the image below, I have created two Modeling Projects, "My First Modeling Project" and "My Second Modeling Project". You'll notice that the UML Model Explorer has two corresponding nodes in the tree.

You might immediately be asking yourself "What's up here? Why show this same information in two tree controls?" The reason will become more clear as I continue on, but it is worth pointing out right now that the UML Model Explorer is a "logical" view over you models. The Solution Explorer is showing you the "physical" view of how those models are contained and persisted. Keep that in mind as you read on.

As I mentioned earlier, every time you create a Modeling Project, a new node will be displayed in the UML Model Explorer. That node is actually a UML package named after the Modeling Project, and serves as the root package for all modeling elements that will be serialized into the Modeling Project. Creating a Modeling Project is the only way to create a root node in the UML Model Explorer.

In the VSTS 2010 CTP, any and every element created under one of these roots is stored in the ModelDefinition.uml file found the Modeling project. In the current bits, we actually create a .uml file for every UML package created. When you intially create a Modeling Project, the UML Package that represents that project is persisted on disk in the ModelDefinition.uml file you see in the project. Every model element created in that package, except new Packages, will be stored in that same file. if you create a new Package, an additional .uml file will be created to store the data behind that package, and all its contents.

Let me drive this all home with some examples, and at the same time show some of the additional capabilities of the UML Model Explorer.

Adding Elements

I want to add a class to the "My Second Modeling Project" model. I can do that by right-clicking on that node in the UML Model Explorer, and select Add->Class.

Each time I do that, a new class will appear underneath the "My Second Modeling Project" node.

To name the class, I hover over the current name, double-click, which allows me to rename the element. ( By the time we RTM, upon adding the new class, the tool will automatically put you in rename mode, as 99% of the time, that's what you will most likely be doing after adding an element in this manner. )

Below is an image of the explorer after adding a few elements. Notice, in small light-grey text is a label that indicates what type of element the node represents.

The types of elements that can be added depend on the node you right click on. So far, I've been right-clicking on the Package node that represents the root of my model. If I right click on the class or interface element, I can add UML Attributes or Operations as well.

Here's what the explorer looks like after adding a couple Operations and Attributes:

Adding elements directly to the UML Model Explorer is great, but that is not the only way to add elements of course. As you drop new elements on diagrams, you will see those elements represented as you would expect.

For example, I'm going to create a new Logical Class Diagram in the "My First Modeling Project" project by right clicking on that project node in the Solution Explorer, selecting Add->New Item..., which brings up the "Add New item dialog", where I select "Logical Class Diagram", give it a name, and hit "OK".

I now have a blank class diagram in the document well, and my project has a new file inserted into it:

Now I drop two classes on that diagram and create a UML Association between them. Like so:

Now over in the UML Model Explorer, you'll see the two new classes underneath the "My First Modeling Project" node. You'll also notice the Association relationship also being represented:

But how did the tool know to create those new elements underneath the "My First Modeling Project" when dropping them on the diagram we just created?

By default, whenever creating any type of UML diagram in a Modeling Project, that diagram's "Linked Package" property is set to the UML package associated with the project itself. That property is used when dropping new elements to figure out what UML package the new elements should be directly contained by. So in this example, that property is set to "My First Modeling Project", as seen below:

Let's drive this home with a more complicated example, and point out a couple more features of the system while we're at it.

First, I'm going to create three new UML Packages underneath the "My First Modeling Project" node, the results shown below:

Now remember when I mentioned that creating a new package would result in a new .uml file being added to the Modeling Project? Take a look at the Solution Explorer, and the "My First Modeling Project" node. You'll notice three new .uml files added to that project, one for each new package I added ( again, the first uml file was already there ):

Now I'm going to create three new class diagrams and associate them with the newly created packages. I do that by right clicking on the "My First Modeling Project" project node in the Solution Explorer, select "Add->New item...", select "Logical Class Diagram", and hit "OK" three times. Here's what my Solution Explorer looks like when done ( red square pointing out the new diagram files added to the project ):

I associate "LogicalClassdiagram1" to the "One" package my setting that diagram's "Linked Package" property appropriately:

I do the same thing for the rest of the diagrams, pointing "LogicalClassdiagram2" to the "Two" package, and "LogicalClassdiagram3" to the "Three" package.

Now I drop a new class onto each of the new diagrams. The UML Model Explorer looks like this:

Paste By Reference and Element Delete

One of the great things that the UML Model Explorer makes very easy is the ability to represent the same model element on numerous diagrams, simply by dragging the element from the explorer onto the diagram. Let me show you what I mean.

I am going to drag "Class1" onto the three class diagrams I just finished creating. Here's the result:

Class1 is now represented on all three diagrams.

NOTE

You'll notice in the image above that Class1 is represented on the diagrams with an elided name. Hovering over the element will show the fully qualified name. You can also widen the element to see the full name:

The reason for this is due to the fact that the diagram this shape is being displayed does not represent the same package that the model element is in. In this case, the LogicalClassDiagram3 represents the "Three" package, not the "My First Modeling Project" package which Class1 is directly owned by.

There is still only one "Class1" element in the UML Model Explorer. If I add an operation to Class1 via the UML Model Explorer, that operation will immediately be displayed in the Class1 on each diagram. This is because the shapes on each of those diagrams is essentially a view into the model data that is Class1. Changing the Class1 model data, which is exactly what changing that data in the Model Explorer does, results in the views of that data also changing.

And of course, adding a new Attribute to any of the Class1 shapes ( also called "Presentation Elements" ) results in the Class1 model data being updated, which updates all the other shapes, and so on.

Dragging from the UML Model Explorer is the most straight forward way of creating "references" back to the model data, but so is copying a shape and selecting "Paste By Reference" in the context menu.

Now deleting one of the shapes results in the shape being deleted, *not* the model element itself. So if I delete Class1 from LogicalClassDiagram1, nothing happens except that shape is removed from that diagram. Class1 is still present in the UML Model Explorer.

If I right click on Class1 and select "Delete", the model data is destroyed, along with all the shapes representing that element:

Summary

I hope that gives you a good taste of what the UML Model Explorer is all about. They key takeaway that I'm hoping you'll walk away with is that the UML Model Explorer is the logical view of the model repository contained by the Modeling Project. It represents data that can be displayed across numerous diagrams. That data can be manipulated directly via the explorer or through manipulation of presentation elements.

By the time we RTM, we hope to have a number of other facilities plugged into the UML Model Explorer, such as:

Ability to represent Diagrams directly in the explorer
Double click elements in the explorer will navigate to the diagram that element is represented on. If represented on many diagrams, you will be presented with a dialog allowing you to select which diagram to navigate to.
Support for moving elements between packages inside the explorer
Filtering of the explorer

As usual, would love to hear your feedback!