Getting App Arch Guid Knowledge in VSTS2010 – Part3 Create Diagrams from Code
The (experimental) journey of getting App Arch Guid Knowledge in VSTS2010 with Edward continuous…
previous steps…
- The VSTA Layer Diagram and the P^P App Arch Guide 2.0.
- Blueprints: Visual Studio 2010 CTP
In this step as promised in part 1 ‘Create Diagrams from Code’.
I used VSTemplate and the IWizard interface for the first solution, but now we have the Blueprints available in VSTS2010 we better can use that functionality to create the diagrams. For this post it actually doesn’t matter what you use as long as you can access the Visual Studio automation object model [DTE].
The steps you have to take.
- Get and Load the Model and Diagram.
- Get the Store and start a transaction.
- Create the shape.
- Create the ModelElement and associate it with the shape.
- Add the combination to the design surface [diagram].
- Add child's [nested shapes] if necessary.
- create the dependencies.
- commit the transaction.
- save the model and diagram.
In more detail.
Step 1. Get and Load the Model and Diagram.
1: LayerModel layerModel = LoadModel(dte.ActiveDocument.FullName);
2:
3:
4: private LayerModel LoadModel(string fileName)
5: {
6: LayerModel currentLayerModel = null;
7: Store store = new Store();
8: Type[] modelTypes = new Type[]
9: {
10: typeof(CoreDesignSurfaceDomainModel),
11: typeof(LayerDesignerDomainModel)
12: };
13: store.LoadDomainModels(modelTypes);
14: using (Transaction t = store.TransactionManager.BeginTransaction("Reading diagram"))
15: {
16: currentLayerModel = LayerDesignerSerializationHelper.Instance.LoadModelAndDiagram(store, fileName, fileName + ".DIAGRAM", null, null);
17: t.Commit();
18: }
19: return currentLayerModel;
20: }
line number 1 is the calling method to the loadmodel function and as you can see i open / load the current in visual studio activated document, you can grab any diagram file. the first thing to look for [using reflector] are the modeltypes when loading a different kind of model. because i not only want add modelelements but also want to control the place of the shape on the design surface i have to loadmodelanddiagram. the .diagram file has knowledge of the position and the .layer file of the modelelements.
Before I forget it the usings are a bit tricky in this ctp. you have to add a reference to “microsoft.visualstudio.modeling.sdk.10.0” and “microsoft.visualstudio.modeling.sdk.diagrams.10.0” [and some more]. the problem is that these aren’t visible in the add reference dialogbox. so, you have to add these manually by adding them in the csproj file.
1: <Reference Include="Microsoft.VisualStudio.Modeling.Sdk.10.0, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" />
2: <Reference Include="Microsoft.VisualStudio.Modeling.Sdk.Diagrams.10.0, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" />
the other references […teamarchitect.layerdesigner and …teamarchitect.layerdesigner.dslpackage] you need can be found in ..\..\program files\microsoft visual studio 10.0\common7\ide\privateassemblies\
Step 2. get the store and start a transaction.
1: Store store = layerModel.Store;
2: using (Transaction t = store.TransactionManager.BeginTransaction("Draw diagram"))
and now we can start to create shapes and place them on the designsurface.
Step 3 and 4. Create the shape, modelelement and combine them.
1: LayerShape layerShape = new LayerShape(store, null);
2: Layer layer = (Layer)store.ElementFactory.CreateElement(Layer.DomainClassId);
3: layer.Name = name;
4: layerShape.Associate(layer);
set some visual properties of the shape, you can completely tweak the looks of the shape.
1: layerShape.AbsoluteBounds = new RectangleD(0.5, 0.5, 7, 2.375);
2: layerShape.FillColor = Color.DarkOrange;
repeat this for all the layers you want to create… and after that
Step 5 and 6. Add them to the Model and Diagram and – or create nestedchilds.
1: diagram.NestedChildShapes.Add(layerShape);
2: layerShape.NestedChildShapes.Add(uiProcessComponentsShape);
3: LayerHasChildLayers child = new LayerHasChildLayers(PresentationPair.LayerPart, uiComponentsPair.LayerPart);
You have to tell the Model and the Diagram that they are nested… if you tell it only to the Diagram [visual layout] they look like if they are nested but in the Layer Diagram Explorer you can see they aren’t.
Step 7. Create the dependencies.
1: DependencyFromLayerToLayer dep = new DependencyFromLayerToLayer(PresentationLayer, CrossCuttingLayer);
Step 8 and 9. Commit transaction and Save the Model and Diagram.
1: t.Commit();
2: }
3: SerializationResult result = new SerializationResult();
4: LayerDesignerSerializationHelper.Instance.SaveModelAndDiagram(result, layerModel, dte.ActiveDocument.FullName, diagram, dte.ActiveDocument.FullName + ".DIAGRAM");
Conclusion.
There is one big drawback with this solution. Because I load the model and diagram from a file, change it and save it back to the two files, Visual Studio recognizes that they are changed outside the IDE and popup a message [two times] if you want to reload it. Not something you want. A solution for this could be the Backplane. Edward did some early investigations around the backplane last year and the layer diagram is connected to the Backplane [not all VSTA diagrams are]. So, that would solve the reload problem. But, that’s something for another post… first Merry Christmas and a Happy New Year everyone, till next year..!
The VSTA Layer Diagram and the P^P App Arch Guide 2.0.
Microsoft is releasing more and more tooling and guidance for the architect. With Visual Studio Team Architect 2010 Microsoft enables the architect and designer to great models which keep their value throughout the application lifecycle and with the current effort according to Architectural Guidance of the Patterns and Practices group, they are helping us making better designed applications. Combining these two efforts, knowledge and valuable models, will help the Application Lifecycle in delivering more added value to the business.
VSTS2010 Layers
Most of the models VSTS2010 has are common used UML models, but Microsoft is also going to deliver another frequent used non-UML model, the Layer Diagram. I do think this diagram is used in all the communication of application architectures. [Cameron Skinner explains the layer diagram in more detail on his blog].
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.
App Arch Layers
Within the Patterns and Practices Application Architecture Guidance 2.0 the layer diagram is often used to describe, explain and communicate the overall structure for applications. In the guidance there are several common used application architectures with their pros and cons and even more important what are the constrains and decisions you have to make for the specific layers. [See part 3, chapters 9 till 13]
…discusses the overall structure for applications, in terms of the logical grouping of components into separate layers or tiers that communicate with each other and with other clients and applications. Layers are concerned with the logical division of components and functionality, and take no account of the physical location of components on different servers or in different locations.
In Part 4 Archetypes, the most common application types are discussed with layer diagrams as basis. Each archetype has their own set of layers and dependencies between those layers.
Together
With the ‘Patterns and Practices Application Architecture Guidance’ how to use layers, how to define layers and how to structure your application together with ‘Visual Studio Team Architect 2010 Layer Diagram’ with the capability to validate, the capability to check the implementation at build-time [or any other time, See Skinners blog “Incorporate Layer Validation in your Builds” and this forum post ] there is a real benefit of using them together. Having the knowledge of the Application Architecture Guidance as a set of predefined layer diagrams available within the development environment will help development teams to make faster, consistent and validated applications.
App Arch Layers in VSTS2010
In the current VSTS2010 CTP there are already several pre-defined layers available. The Fowler Three Layer diagram, the Four Layer diagram and a MVC diagram. You can drag and drop these from the toolbar and it draws the necessary layers for you, it doesn’t add the dependencies [hopefully this will be added in the future]. Adding your own pre-defined layer diagrams to the toolbar isn’t possible [I hope they will add this functionality too] at this moment they are embedded as a binary to the resource file of the DSL, not really good for extensibility :-) . But there are more options to make your own set of pre-defined layer diagrams.
The easiest way is just draw them upfront and add one with ‘add existing item’ to your solution, not really a good way. Changing the diagram will all so change your initial version. You have to copy your initial version to the solution and add it from there to your project. Exchanging different diagrams would be hard and probably you get some problems with guid’s.
So another solution is making a template [vstemplate] of it and let it generate on the fly. With that you can use the default distribution functionality to get the template to your team members [this way, Finding and Sharing Project and Item Templates or this way How to: Publish Project Templates] and because they are created on the fly there will be no problems with guid’s
Walkthrough
Add a new item to your solution. I’ve added a new category to ‘AppArchLayers’ to the dialog box just by adding a directory to the ../Visual Studio 10/Common7/IDE/ItemTemplates folder [for details : How to: Locate and Organize Project and Item Templates] and pasted my custom template in that directory.
As you can see this one is a test version of the template, I will rename it later on. Adding this template fires some IWizard functionality which generates the necessary layers, nested layers and dependencies.
do you like the colors :-) . This one generates the default reference architecture described in the application architecture guidance with strict dependencies. When looking at the Layer Diagram Explorer [view – other windows – Layer Diagram explorer, there is also another layer diagram window which displays the links] you can see that it uses nested layers. So, dependencies at lower level layers must have dependencies conform the top layers.
When we got this layer diagram we can start creating the projects and link them to the layers by drag and drop the projects from the Architecture Explorer.
[I also tried dragging and dropping from the solution explorer but ran in to some strange behavior, still have to log that one in the connect site].
From here developers can start doing their work, adding functionality to the different components and adding project references and now comes the really nice part, the build validates if the dependencies won’t break my model. [You also can right click on the design surface and push validate]
In this image you can see that someone [it wasn’t me] added a reference from UIComponents in the Presentation Layer to the DataHelpers component in the Data Layer and the validation error.
Making a vstemplate and the IWizard functionality just for one Archetype is a bit waste of ‘research’ time, so I also created them for all the other archetypes. [There is still the test template, have to remove that one]
Conclusion
This solution, of using item templates, only gives us the benefit of not having to do re-work, it captures minimal re-use of knowledge or help with defining the structure. When you read the AppArchGuid [chapter 3] there are a lot of decisions to make when defining and drawing the structure of you application architecture. See page 158. Choosing Layers for Your Application…
Use a layered approach to improve the maintainability of your application and make it easier to scale out when necessary to improve performance. Keep in mind that a layered approach adds complexity and can impact your initial development time. Be smart about adding layers, and don’t add them if you don’t need them. Use the following guidelines to help you decide on the layering requirements for your application: … see page 158
For sure you can extend the functionality of the template, put some more logic in the IWizard. Firing a real wizard with a kind of workflow which helps the user to make the decisions is a possibility. But this isn’t the best solution to capture the knowledge, the workflow, of designing the structure of your application. Microsoft Blueprints are much more sophisticated to handle this kind of ‘problems’.
A Blueprint is an accelerator for a specific type of software deliverable like a web service, a rich client, or a mobile application. A Blueprint is a package of process guidance, human-readable resources (docs, decks, videos, etc.) and machine-readable resources (code snippets, templates, frameworks, DSL tools, etc.) which help you build or manage a specific task or domain. It’s an SDK for a problem, not a product or specific technology.
Beside the sophisticated problem approach of Microsoft Blueprints it also gives better capabilities to add menuitems, see Edwards post over here about Blueprints: Custom menu filters the new fileitem menuitem only can be added to projects and actually I want it at solution item level.
So part two of this project of delivering the knowledge of the AppArchGuid to the development environment will start by making the Blueprint available for VSTS2010 and I will make another post how to create the diagrams from code later on, this year or next year...