We just posted a one-day Lab on the DSL Tools on the Code Gallery : http://code.msdn.microsoft.com/DslToolsLab
The idea is that, if you complete this Lab until the end, you'll be able to create your own modeling graphical designers using the DSL Tools technology, and the code generator that will generate code, documentation, configuration files or whatever textual artifact you want, from the information that is entered by the designer user. This will probably take you one day to complete it, but it's really worth it !
I am at TechEd Europe in Barcelona.
As Stuart explained in DSL Tools in Visual Studio 2010, we have many improvements to the DSL Tools in Visual Studio 2010. If you are interested in the subject, and want to talk about that, come an see me : I'll be very often on the VSX/VSIP booth in the "Ask the experts" area.
I'm looking forward to meeting you there !
As one of our customers remembered, we had announced a better support of nested shapes in Visual Studio 2008 SP1 / VSSDK 1.1.
But it turns out that on the list of improvement we shipped with VSSDK 1.1, we only talked about the print preview, and not the nested shape feature.
This post aims at answering what has changed, and why we did not advertise this feature too much. Since at least one person is wondering, it's worth reviewing the improvement:
- the improvement is, in fact, in the runtime of the DSL Tools. And this runtime, you might know it, is shipped with the Visual Studio 2008 SP1, not the VSSK. The part of the DSL Tools which is in the VSSDK covering what we call the "authoring experience", that is developing a DSL. This means we did not add anything to the Dsl designer itself to improve the support of nested shapes: you will still need to add custom code to use of this improved feature.
- you could already create nested shapes before SP1, using custom code as proposed in the book, for instance. The book actually proposes two ways of achieving this. The first one is the right but until the VS 2008 SP1, there were problems with:
- the routing of the connectors
- the collapsing of shapes
- The last news is, you'll still need to write code to use nested shapes, but this code will be simpler since the fact of moving the nested shapes is done for you, and the nested connector routing is much better now.
In this post, I'll show:
- what the problem was with the nested shapes before the fix
- what is better
- how you can profit from this feature
- what custom code you can add depending on the additional behaviours you want to get,
What was the problem with nested shapes before SP1 ; what is improved.
In pre SP1 DSL Tools:
- you needed to create a lot of custom code
- you had, anyway, the connector routing problem:
The following picture shows what this problem was: the connectors could cross the nested shapes, as if they had not been there.
Now, with the post SP1 fix, you'll get the following behaviour as far as the connectors routing is concerned.
How to create a DSL using nested shapes
Remains now to learn how to create a DSL using nested shapes.
- For this, starting with a Minimal Language template. create a DSL named NestedShapesSample: You get this domain model
- Transform the domain model in the following way:
- Add a domain class named Compound, and change its property Inheritance Modifier property to abstract.
- Make the ExampleModel inherit from Compound
- Make the ExampleElement inherit from Compound.
- Remove the ExampleModelHasElements relationship between ExampleModel and ExampleElement and replace it by an embedding between Compound and ExampleElement
- Rename the ExampleElements role of ExampleElement in this relation to SubElements, and the Compound role to Parent
- At that point if you try to save your designer definition, you should get an error : "The Parent Element Path for Shape Map from ExampleElement to ExampleShape must not be null.". this is because we did not re-map the ExampleShape to the ExmapleElement after removing the ExempleModelHasElements relationship and replacing it by CompoundHasSubElements.
In order to get it right, instead of giving the Parent element path, you'll have to check the Has Custom Parent Shape checkbox, and write one line of custom code.
Note that, If you had followed your intuition, you would probably had writen "CompoundHasSubElements.Parent/!Compound" in the Parent Element Path text box, but, in fact, the authoring still does not let you write that (you would end-up with "A GeometryShape may not be parented on a GeometryShape. In the ShapeMap mapping ExampleElement to ExampleShape, the parent element path leads to Compound, which has a subclass ExampleElement whose mapped shape is ExampleShape" ). This is because we did not finish the authoring part of the behaviour.
- Save your DesignerDefinition.dsl file (there should not be any error now)
- Transform all templates and try to compile the Dsl assembly,
You'll get a compile error this time, because you need to produce the GetParentForExampleElement method for as custom code.
- Add the following custom code:
- In the Dsl project create a new folder and name it CustomCode
- In this folder, Add a class named FixUpDiagram. Turn it partial, and do not forget to remove the last segment of the namespace(CustomCode)
- the code of CustomCode\FixUpDiagram.cs should be the following:
using Microsoft.VisualStudio.Modeling;
namespace Microsoft.NestedShapesSample
{
partial class FixUpDiagram
{
private ModelElement GetParentForExampleElement(ExampleElement exampleElement)
{
return exampleElement.Parent;
}
}
}
- Build your DSL, and start it (with or without Debugging): you can now create an ExampleElement either on the diagram, or in an existing ExampleElement
Be sure to give a big size to one of your ExampleElement so that you can drop new ExampleElement in it, because, for the moment, the size of the parent ExampleElement will not increase. To have such a behaviour, we'll need a little bit more custom code. This will be the object of the third part.
Adding more Custom code to the shape, to improve the behaviour
With the simple modification we made the behaviour of our DSL is not yet perfect. The layout of the connectors is right, but we would like:
- either to expand the size of the parent shape when we add a new child shape or move it inside its parent shape: in this way the children shape would be prisoner of its parent.
- or to let the children shapes move out their parent shapes but then re-parent them.
As a function of the wanted behaviour, the custom code is different.
First case: Constraining children shapes into their parent's shape
In order to constraint the children shapes to remain in their parent shape we need to override a few methods and properties in the ExampleShape class.
- allow the children to resize their parent. When they move next to the border of their parent shape, the size of the parent shape will increase. This is enabled by overriding the AllowsChildrenToResizeParent property.
- prevent the parent shape from reducing to a size that would move its children shapes out of its boundaries. this is enabled by overriding the MinimumResizableSize property to a value that contains all the children. There already is a method that computes this size; CalculateMinimumSizeBasedOnChildren()
The custom code is the following:
using Microsoft.VisualStudio.Modeling.Diagrams;
namespace Microsoft.NestedShapesSample
{
partial class ExampleShape
{
/// <summary>
/// Cannot move the children outside their children shape
/// </summary>
public override bool AllowsChildrenToResizeParent
{
get
{
return true;
}
}
/// <summary>
/// Cannot size down the parent shape if the children shapes were to move out of their
/// parent's boundary
/// </summary>
public override SizeD MinimumResizableSize
{
get
{
return this.CalculateMinimumSizeBasedOnChildren();
}
}
}
}
Second case: Reparenting an ExampleElement depending on its position
The alternative is to let the shapes move in and out the parent shapes, but change their parent depending on the geometry. The custom code is, in that case, different. This will be the subject of a next post if some of you are interested by this behaviour.
Having collapsing shape reduce their size
The last customisation I want to talk about is the fact of having collapsing shapes. To let you ExampleShapes be collapsible, you need:
- To add an Expand / Collapse decorator on the ExampleShape, and Transform all templates.
If you do only that, when clicking on the collapse decorator the nested shapes and connectors are hidden, but the size of the parent shape does not change.
- If you are interested in having this size reduced when collapsing the shape, simply add the following custom code, still in the same CustomCode\ExampleShape.cs file
partial class ExampleShape
{
/// <summary>
/// Keeps the size of the expanded bounds of the shape
/// </summary>
protected RectangleD ExpandedBounds;
/// <summary>
/// When we collapse the shape, we keep its current bound and reduce its size
/// </summary>
protected override void Collapse()
{
base.Collapse();
this.ExpandedBounds = this.Bounds;
this.Bounds = this.AbsoluteBounds;
this.AbsoluteBounds = new RectangleD(this.Location, new SizeD(1.5, 0.3));
}
/// <summary>
/// When we expand the shape, we restore the expanded bounds
/// </summary>
protected override void Expand()
{
base.Expand();
this.Bounds = this.ExpandedBounds;
}
...
After collapsing the "Started" shape, you get this
Note that we do not see any longer the connectors form started to terminated. They were hidden as well. This behaviour might suit you or not, but this is beyond the scope of this post.
Conclusion
In this post we went through the nested shapes support in VS 2008 SP1 / VSSDK 1.1.
If some of you are interested we could go further in a future post presenting custom code that brings other behaviours such as:
- moving a shape outside its parent reparents the child
- collapsing a shape containing connectors from its children to the outside of the collapsed shape would show "synthesis" connector.
Presentation of the problem:
Deleting behaviour with compartments representing embeddings
Most of the time, in the DSL Tools, you map compartments in compartment shapes to embedding relationships.
And then, deleting a compartment item in the compartment shape indeed removes the model element which was displayed as this compartment item, which makes sense.
Deleting behaviour with compartments representing reference relationships
Now let's suppose you have are mapping a compartment not to an embedding, but to a reference relationship. You might think that deleting a compartment item will only delete the link between the instance represented by the compartment shape and the instance represented by the compartment item. But it turns out that it also deletes the instance represented by the compartment item.
There are scenarios, where you would like first behaviour. This posts explains why it is so, and how to proceed to have only the link deleted, not the target model element.
A case study: what it does, and what we would want
The domain model
- we have 2 domain classes ClassA and ClassB, linked thru a Reference relationship (many-many) named ClassAReferencesClassB
- ClassB is represented as a geometric shape ClassBShape
- ClassB is represented by a compartment shape ClassAShape, which displays the ClassBs referenced by the instance of ClassA through ClassAReferencesClassB
- the same ClassAReferencesClassB is also represented by a connector, so that we really see what is happening there.
Figure 1: the domain model (please, click the image to enlarge)
Opening the DSL Details tool window, and clicking on the mapping line between ClassA and ClassAShape, in the Compartment Maps tab, we use the path editor as we usually do and end-up with the following, which really means that in the Bs compartment, we are:
- requesting to represent ClassB instances, which we get though the ClassAReferencesClassB relationship navigating though the ClassB role (Displayed elements collection path)
- Then we want to display the Name of each ClassB (Display property).
Figure 2: The mapping between ClassA and the compartment shape representing it.
Running our designer - what it does
After transforming all templates, and running the editor, you create a ClassA , a ClassB , and connect them through the connector, in order to get this (the ClassB1 instance also appears in the compartment, since the relationship is mapped both to the compartment and the connector)
Figure 3: Running our designer - starting point
Now, let's try to delete ClassB1 from the compartment (Using the Del key or the contextual Delete command). You end-up with this:
- the ClassB1 represented instance was deleted (after all the Delete command was targeting it), removing the link, of course
- consequently the ClassB1 shape was deleted
Figure 3: Running our designer - what Delete does on the compartment item
Running our designer - What we would like
That said. You were maybe expecting that, considering you were using a Reference relationship and not an embedding, you would end-up with only deleting the link between ClassA1 and ClassB1 and not the ClassB1 instance. It turns out that this scenario is of interest, but this is not what you requested. You really sent the Delete command to the ClassB1 instance, hence the result.
How to get what we want
In fact, to tell you the truth, I thought myself this behaviour was a bug :-), until Stuart explained me about the command being directed to the ClassBs instances and not to the link. Then, you can very easily achieve our desired behaviour specifying the right things in the DSL Details window on the shape map (and not writing any custom code)
Here is how we should proceed.
- Still in the Compartment Maps tab of our mapping between ClassA and ClassAShape, we need to express that we want to deal not with ClassB instances but with a collection of ClassAReferencesClassBlinks form the instance of ClassA represented by the compartment shape to the related ClassB instances.
The Displayed elements collection path should, therefore be ClassAReferencesClassB.ClassB
This can be understood as the same code construct as ClassAReferencesClassB.GetLinksToClassB(ClassA1) which returns collection of ClassAReferencesClassB. This is really an instance of the link that will be presented as a compartment item, and thus, deleting it will delete the link, not the targeted ClassB.
- Now, we need to specify what to display (namely the Name property of the ClassB instance accessed through the link). For that, given an instance of ClassAReferencesClassB, we need to get an instance of ClassB (just in order to access its property). We express this in the Path to display property field as ClassAReferencesClassB!ClassB which means getting the ClassB property of the ClassAReferencesClassB instance, that is getting a ClassB instance.
- The last step is to provide the Display property, here Name
Figure 4: how to express we want to deal with links
Running our designer - We get what we want
After transforming all templates, and running the designer the first thing is you get exactly the same appearance as before (even if now the compartment items represent links and not model element instances). This is no surprise because we did all we could for that, but it's work noting it
Figure 5: Running our new designer - apparently this is like before
But this, time, deleting the ClassB1 compartment item, we end up with the following expected result:
Figure 6: Running our new designer - the delete command now delete the link, not the targeted shape
Conclusion
In this post, we learnt why, when mapping a compartment to a reference relationship, deleting compartment items deletes the targeted model element with the usual mapping, and how to change the mapping so that it only deletes the link.
To get more information about the path syntax, you can review Overview of Domain Path Syntax . When I started with the DSL tools, I also found this post by Alan very useful.
As you might know, James and I are currently doing a VSX Tour in Europe. James already provided information in his blog about the different steps, in Brussels, Amsterdam, and Munich.
For the ones who would be interested in the event in Belgium:
- Katrien, who welcomed us and took care of us in Brussels, provides the links on the WebCasts recorded during the user group in Belgium.
- There is also a nice feedback on our session in David Sleeckx's blog. Thanks, David !
I'm currently visiting the VSX team in Redmond, introducing myself and meeting everybody. I'll be there for two weeks.
I arrived yesterday afternoon after a 23 hours trip from France, and Ken Levy invited me to a party at Ted Neward's house, along with Pablo Galiano It was a great occasion to speak with MVPs and VSX developers, even if I was very tired.
Today I began my first meetings with the members of the team. In the next couple of days, I'll have meetings with various team members, and will participate to the MVP Summit - Communities Side Session on Thursday.
It's really great to meet everybody, and to get more understanding of the VS SDK's overall development life cycle, as well as meeting the VSX community members. All this will enable me to participate in helping add new features to DSL tools and to enhance the VS SDK, working to enhance VSX development. :-)
As I told you in my previous post, the DslFactory community created a lot of content about DslTools and more generally Visual Studio Extensibility. This content is freely available, although written in French. Most of it is very interesting: For instance, DslFactory organized, on October 16th 2007, in Paris, along with Microsoft France, a complete day about Visual Studio customizations and extensibility named 9french) VSX Day 07.
The VSX Day 07 explained
The VSX Day, that is not less than 19 sessions whose content was filmed and is available as WebCasts (in French, of course) on Microsoft France Vision site.
These sessions are organized as a pathways, illustrated as a metro map, enabling us to discover the visual studio extensibility in a kind of progressive way. Starting from the Visual Studio customizations we ended the day by the the VS 2008 Shell, going through VSI, Snippets, VS Templates, GAX, Automation by macros and DTE, Add-ins, a VS SDK's Tour, Packages, DSLs, advanced DSLs such as bidirectional ones, with many demos, including Alain Metge brilliant Candle, and the WCF Designer. During the full day we also incrementally demoed a sample which was the pretext to navigate through these technologies : The creation of clickable images from class diagrams, and other DSL diagrams, and their inclusion in a Reference documentation thru add-in to SandCastle, and SandCastleHelpFileBuilder. Quite a lot of information for the attendees (the legend tells they would have been 200 :-) )
The VSX Day web casts
The Webcasts sessions of the day VSX Day can be found at the "Vision" Microsoft France:
Note that these links will take you to lists of more detailed WebCasts (it takes a little digging to find some WebCasts for the moment)
The VSX Slides
After a short introduction, DslFactory presented the issue of industrializing reference materials - which we serve as a leitmotif of this day - and the extension of Visual Studio responding.
The different extensibility scalability were then presented, from the most accessible to most powerful:
- The simple Visual Studio customization templates, wizards, and the use of GAX Guidances we already provide significant opportunities
- Then came the time to start coding with automation by Macros and Add-In
- Then, the Tour of the "Visual Studio SDK" allowed us to quickly learn about all these technologies most of which are ignored, and what they can do for us.
- A special focus was then carried out on some of these technologies:
- The afternoon was entirely devoted to the Domain Specific Languages (DSL) and their implementation in Visual Studio Opens via DSL Tools. Beginners, as confirmed users have, hopefully, been able to find answers to their questions
- We ended the day by lifting the veil on scalability VS 2008, and providing useful links
If you are interested in a particular subject, you can download a summary as a . pps file, and click subway stations. You will be taken directly to the corresponding powerpoint presentations.
The code samples
Associated with each session, DslFactory also provides the code of the demoed samples:
- 1. 1. Leitmotif: Demoed by Sebastian, with 3 examples. Chm before and after using SandCastle Add-ins and SandCastleHelpFileBuilder 1-FilRouge.zip (998 kb)
- 2. 2. Customizing VS:
- The demonstration by Alain on Visual Studio Policy: 2-VSPolicy.zip (2.14 MB).
- Moreover, the DSL "DSL4VSI" that Alain created to generate Visual Studio Installer (VSI) capable of installing 'Code Snippet', 'VSTemplate', 'Macro Project', 'Addin', 'Control Toolbox' is available on CodePlex in http://www.codeplex.com/dsl4vsi
- 3. 3. Automation API and Add-ins.
- The Visual Studio solution that I used inmy demos on the implementation of ProjectModel (list of projects and files), CoreModel (enumeration of windows) CodeModel (dynamic creation of a solution containing a draft containing serializable class): 3.1-AutomationAPI.zip (559 kb)
- The source code and binaries for the Add-in for Sebastien to generate clickable iamges from ClassDiagrams: 3.2-Add-ins.zip (25.3 kb)
- 4. VS SDK Tour has been a Live demo, which you can find in the WebCast.
For next demos, except the 6.1, you must install the VS SDK 4.0 for Visual Studio 2005
- 4.5. Regarding the demonstration associated with the presentation of the discovery of the packages, the 4.5-Packages.zip archive (7.81 MB) includes the 8 step of building the ReferenceDocumentationGenerator package to export clickable images
corresponding to ClassDiagram and DSL, and choose Export options, as well as to export diagrams.
- 5.2. Sebastien's Demo on creating a DSL for geometric shapes includes 7 steps, the establishment of the Domain Model with the DSL Tools for deployment. These steps have been grouped in 5.2-VSX-Day-solutions . zip (8 MB)
- 6.1. 6.1. Session advanced customization aspects of the properties window with the concepts of the System.ComponentModel namespace by Alain are available in 6.1-ComponentModel.zip ( 53 KO)
- 6.2. The demonstration of the session Using the Domain Model is in this archive: 6.2-UtilisationModele-ReferenceDocumentationGenerator.zip (755 KB). It is also part of the archive of the sesssion 4.5 Packages on which it is the 8th step.
- 6.3. The amendment to DSL Sebastian him for advanced functions such as the Model <-> Code bidirectionality is, also in 6.3-Bidirectionnalite.zip (2.90 MB)
That's it for an overview of the VSX Day
In my next post, I'll talk a little more about some Labs and Workshop that DslFactory produced to learn DSL Tools.
I started a few days ago in the Visual Studio Ecosystem team.
During my last 19 years I worked in the French Ministry of Defence building operational analysis software, and simulation applications to make decisions. A few years ago, I started creating a simulation development environment. This is were I got the passion for modelling, and discovered the DSL Tools. This lead me to get more interested in Visual Studio Extensibility, and, with a few friends, we created a French community about VSX and DSL Tools, which you'll find at http://www.dslfactory.org.
This is actually a great community, but there is one inconvenient for most people in the world : this is all written in French!
I hope to use this blog to share with you it's content, and also my discoveries on the long running path of understanding the Visual Studio SDK.
