I’m not sure what append, maybe it happed on a project I imported from an older Visual Studio version. But for this project the property I needed so much was just missing.

If the same happens to you, you can edit the DslPackage.csproj and add the following line:

<ProjectTypeGuids>{82b43b9b-a64c-4715-b499-d71e9ca2bd60};     {FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>

It worked on my machine and I got this property back.

First of all I have to explain to everybody what I’m talking about:

With Visual Studio 2010 Microsoft introduced a new way to deploy extensions to Visual Studio. Instead of creating a setup.exe that copies files, writes to the registry and calls devenv.exe with the /setup option one only needs such a VSIX file that does all that is necessary to install an extension.

When working with the T4 (Template Transformation Toolkit) system one creates tt files with some kind of script that is used to generate source code within a user’s Visual Studio project. The Microsoft DSL Tools do the same: every DSL project contains a number of tt files that will generate all the code. If you take a look at such a file, you will only see two lines:

<#@ Dsl processor="DslDirectiveProcessor" requires="fileName='..\DslDefinition.dsl'" #>
<#@ include file="Dsl\Diagram.tt" #>

The magic happens with the include command. The real template code sits in the included file and not within every single project. When installing the DSL Tools extension to Visual Studio all these include files get installed somewhere where they can be found by the tt engine.

For my own DSL Languages I would like do the same: the user projects should only contain such two line tt files and include the rest of the template from other files.

How to deploy tt template files?

The following steps will show you how to deploy additional files with you DSL extension.

I will start from a newly created Domain-Specific Language Designer project. Such a project contains a Dsl and a DslPackage project where the DslPackage project creates besides of the DslPackage.dll a vsix file to install the designer onto another machine.

Our goal will be to add some tt files to the vsix and make them includable on the installed machine.

1. Add a folder to the DslPackage project and name it TextTemplates (or any other name)
2. Add the tt files to this folder.
   • In the properties windows clear the “Custom Tool” property; otherwise Visual Studio will try to execute these templates within the DslPackage project.
   • set “Build Action” to “Content”
   • set “Include in VSIX” to “True”
3. Add a file called Additional.pkgdef to the DslPackage project with the following content and
   • set “Build Action” to “Content”
   • set “Include in VSIX” to “True”
     

     [$RootKey$\TextTemplating\IncludeFolders] [$RootKey$\TextTemplating\IncludeFolders\.tt] "IncludeMyDsl"="$PackageFolder$\TextTemplates"

     Replace “IncludeMyDsl” by a unique name for your DSL but make sure it starts with the word “Include”.

4. Edit the source.extension.tt in the DslPackage project and add the following line within the Content tag:

   <VsPackage>Additional.pkgdef</VsPackage>

With these changes the tt files from the TextTemplates folder get packaged into the vsix file and will be accessible using the <include> tag on the machine where this extension is installed.

Let’s start with a short introduction to DirectiveProcessors. DirectiveProcessors are used in .tt-files to provide data to the template. The DirectiveProcessor can take parameters from the declaration in the .tt-file and adds some code to the compiled template. This code (often properties) can be used from within the template. For example the DSL Tools are generating one DirectiveProcessor for each DSL model. In a template form the DSL Tools you will see a line like the following:

<#@ Language1 processor=“Language1DirectiveProcessor”
requires=“fileName=’Sample.mydsl1′” #>

This line uses the Language1DirectiveProcessor and provides it with one parameter (fileName). The DirectiveProcessor adds code to the template to open the given file and creates (in this case) a ExampleModel-property to use in the template code.

I created two DirectiveProcessors to use the data of simple Xml-files and Visual Studio Project files in the templates. The code of the two DirectiveProcessors is very straight forward and maybe one could advance it (e.g. make it compatible with templates written in Visual Basic).

Using the XmlFileDirectiveProcessor

Add a line like the following to your .tt-file:

<#@ XmlFile processor=“XmlFileDirectiveProcessor” FileName=“example.xml” #>

Inside this template you can access the (full qualified) filename via the this.XmlFileName-Property and the Content of this file (as a XDocument) via the this.XmlFile-Property.

Using the VsProjectFileDirectiveProcessor

Add this line to your template:

<#@ ProjectFile processor=“VsProjectFileDirectiveProcessor” FileName=“x.csproj” #>

A property named this.ProjectFile will be added to the template. This property provides you with an instance of the VsProjectFile-class containing the project file contents. This class contains only very little functionality (feel free to add some more and submit it back to me!). Just take a look at the source code of this class. The method GetAllFiles() returns a string array of all files found in the project (supporting C++ and C# project files – .vcproj and .csproj).

Setup

An entry in the registry is needed to allow the T4 system to find custom DirectiveProcessors. Just add the following entries to your registry and don’t forget to point to the right location of the JaDAL.dll.

[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\9.0Exp\
Configuration\TextTemplating\DirectiveProcessors\VsProjectFileDirectiveProcessor]
“Class”=”BenjaminSchroeter.Dsl.DirectiveProcessors.VsProjectFileDirectiveProcessor”
“CodeBase”=”D:\\JaDAL\\bin\\Debug\\JaDAL.dll”

[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\9.0Exp\
Configuration\TextTemplating\DirectiveProcessors\XmlFileDirectiveProcessor]
“Class”=”BenjaminSchroeter.Dsl.DirectiveProcessors.XmlFileDirectiveProcessor”
“CodeBase”=”D:\\JaDAL\\bin\\Debug\\JaDAL.dll”

These registry keys are for the Experimental Hive of Visual Studio. To register the DirectiveProcessors for the normal Visual Studio instance the registry key starts with HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0
\TextTemplating\DirectiveProcessors\

I could not find any option in the DSL design to remove the model explorer, but if you look at some of the .tt files you will find somewhere a query for this.Dsl.Explorer != null. For example in the package.tt file that generates the package.cs which is responsible for registering the tool window for the model explorer:

<#
    if(this.Dsl.Explorer != null)
    {
#>
    [VSShell::ProvideToolWindow(         typeof(<#= dslName #>ExplorerToolWindow),          MultiInstances = false,          Style = VSShell::VsDockStyle.Tabbed,          Orientation = VSShell::ToolWindowOrientation.Right,          Window = "{3AE79031-E1BC-11D0-8F78-00A0C9110057}")]
    [VSShell::ProvideToolWindowVisibility(         typeof(<#= dslName #>ExplorerToolWindow),          Constants.<#= dslName #>EditorFactoryId)]
<#
    }
#>

Even if I did not find any option to set the Dsl.Explorer property of the model to null (you did not see the Explorer property anywhere in the DSL diagram) it seems that the developers of the DSL Tools had this use case in mind.

To remove the Dsl.Explorer from your DSL model open the .dsl file with a text editor and go to the end. There you will find some XML tags like the following:

<Explorer ExplorerGuid="6c276297-6acd-4e9a-8740-b61ba834004b"  Title="HardwareDescription Explorer">
    <ExplorerBehaviorMoniker      Name="HardwareDescription/HardwareDescriptionExplorer" />
</Explorer>

Just delete these three lines and generate your code once again. Maybe you should reset your Experimental Hive, too.

I tested a DSL with a removed Model Explorer without any problems. It seems the developers of the DSL Tools did a very good job on the code generation templates . The generated ModelExplorer.cs file contains only a single line:

// This source file is empty because    this DSL does not define a model explorer.

That should be a good proof that a DSL can run without the model explorer even if it might be not supported by the DSL Tools.

1.10 TypeConverters and TypeDescriptors are not picked up during the build process or during toolbox initialization.
When adding a custom TypeConverter or TypeDescriptor and then building the DSL, the TypeConvertor or TypeDescriptor is not picked up. The workaround is to rebuild the solution with a clean build.

[see Known Issues for Microsoft Visual Studio 2008 SDK 1.0]

Some time ago I posted a workaround for this problem with the TypeConverter, but today a realized that this workaround does not work with the same issue for TypeDescriptors.

Imagine some class with the following attribute:

[TypeDescriptionProvider(typeof(MyClassTypeDescriptionProvider))]
public partial class MyClass : ModelElement
{}

The corresponding TypeDescriptor (provided by the MyClassTypeDescriptionProvider class) is loaded only the first time you build or rebuild your solution. Every time you start Visual Studio after that, this attribute seems to be ignored.

Fortunately there is another way to glue TypeDescriptors to your classes using a static method of the TypeDescriptor class at runtime:

TypeDescriptor.AddProvider(
   new MyClassTypeDescriptionProvider(), typeof(MyClass));

I think a good place for this code is the static constructor of the MyClass type:

partial class MyClass
{
    static MyClass()
    {
        TypeDescriptor.AddProvider(
            new MyClassTypeDescriptionProvider(),
            typeof(MyClass));
    }
}

Another interesting point is: Not only custom TypeDescriptors you write yourself are affected by this problem, also the TypeDescriptors that are generated by the DSL-Tools from your DslDefintion have to struggle with it:

In the DSL Explorer you can define custom TypeDescriptors for each Domain Class and each Shape. Even these TypeDescriptors will not be loaded after the first run. In other words: the definition of TypeDescriptors in the DSL Explorer is pretty useless as long as you do not add the three lines of code to each class. Of course this is something one can automate! I stole some code from PropertiesGrid.tt and added a few lines to create the RegisterTypeDescriptor.tt. Just add this file to your Dsl Project in the GeneratedCode folder and all TypeDescriptors defined in the DSL Explorer will be loaded every time you start your project.

For some reason I want to know the filename of the model used in the tt-file. The default implementation provides you only with a reference to the model but with no chance to get its filename.

In your tt-file you will find something similar to

<#@ Language15 processor="Language15DirectiveProcessor"
     requires="fileName='Sample.mydsl1'" #>

This will use the Language15DirectiveProcessor to load the given file and provide your template with a global ExampleModel variable (of cause the name depends on your DSL and you can change it with the provides attribute in the tt-file).

To change the Language15DirectiveProcessor you can create a partial class in your DSL and add some code to it:

partial class Language15DirectiveProcessor
{
    protected override void GenerateTransformCode
     (string directiveName,
      StringBuilder codeBuffer,
      System.CodeDom.Compiler.CodeDomProvider languageProvider,
      IDictionary<string, string> requiresArguments,
      IDictionary<string, string> providesArguments)
      {
        base.GenerateTransformCode(directiveName,
                    codeBuffer, languageProvider,
                    requiresArguments, providesArguments);           

        codeBuffer.AppendFormat(
           "public string {1} = @\"{0}\";",
             requiresArguments["FileName"],
             providesArguments["FileName"]);

       codeBuffer.AppendLine();
    }

    protected override void InitializeProvidesDictionary
    (string directiveName,
      IDictionary<string, string> providesDictionary)
    {
        base.InitializeProvidesDictionary(directiveName,
                            providesDictionary);

        providesDictionary.Add("FileName","FileName");
    }
}

This adds a new global variable FileName to the tt and initializes it with the model file name.

Attention: You see the variable in this example is generated by writing a line of C# code to the codeBuffer. This may be a bad idea if you want to use this DirectiveProcessor for templates where the template language is set to VB. The better way is to create the code using the Emit and CodeDom API, but I was to lazy to do it that way.

If anybody ports this code to work with VB templates by using the CodeDom or plain VB code, please post a comment here.

Further reading: The process of creating your own DirectiveProcessor and everything you need to understand the code above can be found in the msdn: Creating Custom Text Template Directive Processors.

First I take a look on the properties of the connector in the DSL designer and while searching I observed something: The DSL designer has this behavior on all connectors! I don’t have to write code for the MouseOver-event, but I have to figure out how to activate this behavior on my DSL editor.

For my surprise, the connectors on a newly created example language have a mouse over feedback, too. After playing around with some properties I was faced to a interesting fact: The mouse over feedback works pretty good for all connectors but black ones. I had no idea what’s going on.

Long story short: With Reflector I found one interesting method in the ShapeElement class: ModifyLuminosity(). The documentation is very clear:

"Calculates the luminosity of the highlight for the shape."

"The formula that creates luminosity. By default, the formula is: if luminosity is >= 160, then luminosity = luminosity * 0.9; otherwise, luminosity = luminosity + 40."

The luminosity of a black connector is 0 so the new luminosity will be 40. But for the color black you hardly see a difference between 0 and 40. But with this knowledge you can override the method in the connector class like this:

protected override int ModifyLuminosity
              (int currentLuminosity, DiagramClientView view)
{
  if(!view.HighlightedShapes.Contains(new DiagramItem(this)))
     return currentLuminosity;
        
 return 130;
}

The value 130 on a black connector works pretty good for me. Just try a few values und find a value you like.

This is a pretty static way to control the domain properties. You have to define a few modes and decide at design time the visible and active properties for each mode. Sometimes you need a more dynamic way: So I introduced another attribute CustomRestrictedPropertyAttribute and an interface ISupportsUserRestrictions. If this attribute is present, the library will call the GetRestriction() method of this interface and your user code can decide whenever the domain property will be visible, hidden or read only.

I built a small example: a domain class contains a few properties: CustomPropery, CustomPropertyVisible and CustomPropertyReadOnly. The two flags cause the first property to be visible, hidden or read only in the properties window.

[CustomRestrictedProperty("CustomProperty")]
partial class ExampleElement : ISupportsUserRestrictions
{
    public Restriction GetRestriction(string property)
    {
        if (property == "CustomProperty")
        {
            if (!this.CustomPropertyVisible)
                return Restriction.Hidden;

            if (this.CustumPropertyReadOnly)
                return Restriction.ReadOnly;

            return Restriction.Full;
        }

        return Restriction.Full;
    }
}

This example can be downloaded as part of the JaDAL source code. Currently you have to catch the code directly from the Source Code tab at CodePlex since it isn’t part of the latest Release yet.

However we all know: zip files are a bad version management system!

I decided to put all these code together and compose a single library with addons for the DSL Tools, name it “JaDAL – Just another DSL-Tools Addon Library” and publish it at CodePlex. I will continue to write articles here, but now you can always find the latest code at CodePlex.

If you are interested in my work with the DSL Tools, just take a look at JaDAL.

If you don’t have any idea what I’m talking about please take a look at (at least) the first part of the series, but be careful and DO NOT read the second part! The second part contains obsolete information that will be corrected here. Part 3 and part 4 describe the inside of the library and they are still valid for the new version.

Changes from version 1 to 2

In the original version you have to decide (using the xml file) for the target and source of the connection to be mapped to a compartment or a regular shape. I thought this wouldn’t be an issue since you must know the mapping of your classes. I believed it until I created my DSL with the use of inheritance and some base class that can be mapped to regular or compartment shapes. For this base class I couldn’t create a mapping that goes from a regular or a compartment shape to a regular or compartment shape.

I removed this constraint and in version 2 you needn’t care about it. The library can handle all these cases (even the trivial mapping from regular to regular shape). And even the best: it turned out that removing this constraint made the code much clearer and simpler (both the code of the library itself and the code you have to write). Before this change there were many different cases (first regular to compartment, then compartment to regular, then compartment to compartment and at the end regular to regular which throws an exception) and now everything works the same way.

Lesson learned: If you can do something in an abstract and general way, don’t create different cases and handle only some of them!

And again: the user guide

In the 2nd part of this series I presented a user guide with a step by step walkthrough of creating a DSL using the compartment mapping. I will now create the same DSL with version 2. Most steps are still the same but I repeat them for completeness. The main difference is the xml file format at step 7 and the class you have to write yourself in steps 9 to 11.

You will find this example (and a more advanced one) in the release download over at CodePlex.

1. You need TTxGen to generate some code from my templates. See my article for more information and a workaround for an installation problem.
2. I assume you have a DSL solution and at least two Domain Classes mapped to two compartment shapes and two more Domain Classes used as entries of the compartment shapes created. In my example these classes are called Parent1, Entry1, Parent2 and Entry2.
   The entries need a unique identifier. You could use a name property for this, but there will be some difficulties if the user creates two entries in one shape with the same name, so I will use a guid. (Don’t forget to create a new guid in the constructor or another proper place.)
3. Create a Reference Relationship from Parent1 to Parent2. This will be automatically named Parent1ReferencesParent2. We will use this reference to present the relationship from one entry to another. I would like to create Reference Relationships from this relationship to the entries, but relationships of relationships are not supported. We have to store the guids of the entries in the relationship and add two Domain Properties for this purpose to it. I named them fromEntry and toEntry.
    
4. Set the Allows Duplicates property of the Parent1ReferencesParent2 relationship to true.
5. Set the Is Custom property of the Connection Builder (Parent1ReferencesParent2Builder) in the DSL Explorer to true.
6. Add a reference to JaDAL.dll to both the Dsl and DslPackage project.
7. Add a new xml file (in my example CompartmentMappings.xml) to your solution and write the following code in it:

   <?xml version="1.0" encoding="utf-8" ?>
   <CompartmentMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="CompartmentMappings.xsd"
    namespace="BenjaminSchroeter.CompartmentMapping">
    
     <Connection name="Parent1ReferencesParent2" 
       allowSelfReference="true"
       suppressEntryDeletePropagation="false">
       
       <Source allowHead="false">
         <DomainClass name="Parent1" />
         <EntryDomainClass name="Entry1"/>
       </Source>
       
       <Target allowHead="true">
         <DomainClass name="Parent2"/>
         <EntryDomainClass name="Entry2"/>
       </Target>
       
       <Connector name="Connector"/>
     </Connection>
   
     <CompartmentShape name="CompartmentShape1"/>
     <CompartmentShape name="CompartmentShape2"/>
   </CompartmentMappings>
   

   (If you place the xsd file in the same directory you get IntelliSense and error checking for free.)

8. Place the CompartmentMappings.tt file in the same directory, right-click on the xml file and choose Generate xGen Template. A CompartmentMappings_xGen.tt file will be created below the xml file and there you have to add the following lines:

   <#@ ParentFileInjector processor="TTxGenDirectiveProcessor" 
       requires="fileName='CompartmentMappings.xml'" #>
   <#@ include file="CompartmentMappings.tt" #>

   (Be sure you use the right xml file name here.)

9. Now you have to write some code by yourself. In the generated cs file (CompartmentMappings_xGen.cs) there will be a class named Parent1ReferencesParent2BuilderInstance with three missing methods you have to override. Create a partial class in a new file and implement these methods (see 10 and 11).

10. Implement the CreateElementLink() method in this file. Here you have to add code to store the selected compartment entries for source and target in the properties of the relationship (see 3).

    protected override ElementLink CreateElementLink
        (Parent1 source, 
         SelectedCompartmentPartType sourcePartType,
         Entry1 sourceEntry, 
         Parent2 target,
         SelectedCompartmentPartType targetPartType, 
         Entry2 targetEntry)
    {
        Parent1ReferencesParent2 result;
        result = new Parent1ReferencesParent2(source, target);
        if(sourcePartType== SelectedCompartmentPartType.Head)
            // use a empty guid for the Head
            result.fromEntry = Guid.Empty; 
        else
            result.fromEntry = sourceEntry.Guid;
    
        if(targetPartType== SelectedCompartmentPartType.Head)
            // use a empty guid for the Head
            result.toEntry = Guid.Empty;
        else
            result.toEntry = targetEntry.Guid;
    
        return result;
    }

11. In the CreateElementLink() method you have stored the source and target entry information somewhere; my library does not know about this location. So we need two additional methods to compare an entry with a relationship and answer the question "Is this entry the source of a given relationship?" and the same for the target. These code resists in the same file:

    public override bool IsEntryConnectionSource
        (Entry1 entry, 
         Parent1ReferencesParent2 connection)
    {
        if (entry == null)
            return connection.fromEntry.Equals(Guid.Empty);
    
        return connection.fromEntry.Equals(entry.Guid);
    }
    
    public override bool IsEntryConnectionTarget
        (Entry2 entry, 
         Parent1ReferencesParent2 connection)
    {
        if (entry == null)
            return connection.toEntry.Equals(Guid.Empty);
    
        return connection.toEntry.Equals(entry.Guid);
    }

    Always care for entry == null, this will be used to check whether the head of the shape is meant. Even if you do not allow the head to be source or target this method will be called with a null parameter from time to time.

12. Create a partial class for your Domain Model (CompartmentMappingExampleDomainModel) and add the following methods.

    protected override Type[] GetCustomDomainModelTypes()
    {
      return CompartmentMappingUtil.AllCompartmentMappingRules(this);
    }

    (If you have already some custom rules, you can use an overloaded version of the AllCompartmentMappingRules() method.)

13. In the DslPackage project create a partial class for the generated Command Set and add the following code:

    protected override IList<MenuCommand> GetMenuCommands()
    {
        return CompartmentMappingUtil.RemoveRerouteCommand
                                    (base.GetMenuCommands());
    }

That’s all. The mapping from compartment entry to compartment entry should be working after compiling the solution.

Advanced Features

As I mention above you can mix compartment and regular shapes. You only need to create a DSL with these shapes and configure the xml file another way. As you see, inside the <Connection> element there is no longer a reference to the diagram elements, only the domain classes are used here. Obviously if you use inheritance all your classes need to have the same base class for <DomainClass> itself and for <EntryDomainClass>. If the concrete class is mapped to a compartment shape, the compartment mappings, otherwise a mapping of regular shapes, will be used.

If one of source or target is always a regular shape, please use ModelElement for <EntryDomainClass>.

At the bottom of the xml file you have to list all shapes that play a role in your mapping. Use the xml elements <CompartmentShape> and <RegularShape> therefore.

Inside your Parent1ReferencesParent2BuilderInstance class you can override some more methods to allow or forbid the creation of connectors. I think the names and signatures speak for themselves:

• bool CanAcceptAsCompartmentSource
   (SOURCE_ELEMENT candidate, 
    SelectedCompartmentPartType partType, 
    SOURCE_COMPARTMENT_ENTRY candidateEntry)

• bool CanAcceptAsCompartmentTarget
   (TARGET_ELEMENT candidate, 
    SelectedCompartmentPartType partType, 
    TARGET_COMPARTMENT_ENTRY candidateEntry)

• bool CanAcceptAsCompartmentSourceAndTarget
    (SOURCE_ELEMENT sourceElement, 
    SelectedCompartmentPartType sourcePartType, 
    SOURCE_COMPARTMENT_ENTRY sourceEntry, 
    TARGET_ELEMENT targetElement, 
    SelectedCompartmentPartType targetPartType, 
    TARGET_COMPARTMENT_ENTRY targetEntry)

Advanced Sample

In addition to the sample above I build a second one. There I want to create mappings form some Inputs to some Outputs, where one of these Inputs or Outputs can be an entry of a compartment shape or a whole regular shape. This regular shape contains a property Kind that makes the shape to an Input or an Output (to show you the use of the CanAcceptAs... methods).

The DSL model looks like this:

The project with all sources is part of the samples in the JaDAL download.

Download

The compartment mapping library and both samples are part of JaDAL – Just another DSL-Tools Addon Library which you can download from CodePlex.