DSLs

Posted: Industry Vertical Episode 001

Jim Lavin — Tue, 04 Nov 2008 13:06:04 GMT

I am proud to present the first episode of Industry Vertical the twice monthly net cast about industrializing software development with Software Factories, Guidance Automation and Domain Specific Languages at http://tinyurl.com/6gjlgl. This episode starts out with the basics of Software Factories and trys to answer the question "What is a Software Factory".

How to Create a Custom Editor for a Domain Model Element Property

Jim Lavin — Sat, 05 Jul 2008 17:09:11 GMT

Sometimes when defining a property for a domain model element you may need to use a complex type that has more than one property or can't easily be displayed using a single text field or drop down in the property editor. A good example might be a class that holds a list of strings for a GUI interface or a Rich Text editor for a custom text field required by your framework.

To resolve this you can create a custom editor and hook it into your domain model that will provide a proper user interface to specify information for your property.

There are three steps you need to take in order to wire your domain property to display a custom editor:

1. Create a class derived from System.Drawing.Design.UITypeEditor that will launch the custom dialog box as below:

using System;

using System.Collections.Generic;

using System.Text;

// Need to add a reference to System.Drawing DLL.

using System.Drawing.Design;

using System.Security.Permissions;

using Microsoft.VisualStudio.Modeling;

using Microsoft.VisualStudio.Modeling.Design;

namespace XXX.UIProcessDesigner.UIEditors

    // FxCop rule: must have same security demands as parent class

    [PermissionSet(SecurityAction.LinkDemand, Name = "FullTrust"), PermissionSet(SecurityAction.InheritanceDemand, Name = "FullTrust")]

    public class FormPromptUITypeEditor : System.Drawing.Design.UITypeEditor

        /// <summary>

        /// Overridden to specify that our editor is a modal form

        /// </summary>

        /// <param name="context"></param>

        /// <returns></returns>

        public override UITypeEditorEditStyle GetEditStyle(System.ComponentModel.ITypeDescriptorContext context)

            return UITypeEditorEditStyle.Modal;

        /// <summary>

        /// Called by VS whenever the user clicks on the ellipsis in the

        /// properties window for a property to which this editor is linked.

        /// </summary>

        /// <param name="context"></param>

        /// <param name="provider"></param>

        /// <param name="value"></param>

        /// <returns></returns>

        public override object EditValue(

            System.ComponentModel.ITypeDescriptorContext context,

            IServiceProvider provider,

            object value)

            // Get a reference to the underlying property element

            ElementPropertyDescriptor descriptor = context.PropertyDescriptor as ElementPropertyDescriptor;

            ModelElement underlyingModelElent = descriptor.ModelElement;

            // context.Instance also returns a model element, but this will either

            // be the shape representing the underlying element (if you selected

            // the element via the design surface), or the underlying element

            // itself (if you selected the element via the model explorer)

            ModelElement element = context.Instance as ModelElement;

            FormPromptUITypeEditorForm theForm = new FormPromptUITypeEditorForm();

            theForm.Value = (string)value;

            if (theForm.ShowDialog() == System.Windows.Forms.DialogResult.OK)

                value = theForm.Value;

            return value;

2. Create a Windows Form dialog that will be displayed when the editor is invoked, such as the one below:

3. Set the Custom Attributes for the Domain Property to reference the UITypeEditor class you have created.

The text is as follows: [System.ComponentModel.Editor(typeof(XXX.UIProcessDesigner.UIEditors.FormActionTypeUITypeEditor),typeof(System.Drawing.Design.UITypeEditor))]

The bold faced text is the full namespace of your class that derives from UITypeEditor.

I normally store all code that I add to a DSL Designer in various folders such as; CustomCode, UIEditors, Validators, etc. That way it is easy to find when I am trying to reference it.

Also, you can debug the UITypeEditor and Dialog by setting breakpoints in the code before you start debugging.

Technorati Tags: DSL,Domain Specific Languages,Software Factories

Extending the Service Factory v3

Jim Lavin — Sat, 15 Sep 2007 09:59:56 GMT

I've been needing a tailored version of the Web Service Software Factory to simplify the design and creation of web services for my development team. Not that the Service Factory isn't easy to use, but my team has to design and build services that use industry standard schemas as well as invoke workflows. So, I figured extending the the service factory would allow me to tailor it to my team's needs and by using some of the new features in the v3b117 Alpha I could keep the modifications simple. Granted, things will change between now and the final release, but half of the fun with being on the bleeding edge is taking things apart to get a good understanding of how they work.

Technology Extensions

What I needed was a way for the person designing the service to indicate if an operation should invoke a workflow or not. To do this I needed a new property on the operation contract model element in the service designer. Normally, you would have to modify the DSL model to add the new property, recompile and distribute the new version of the DSL. This is not always the best way to do things because you end up having various versions of the DSL laying about taking up space. Not anymore! By using the extensions provided in the service factory you can extend the model specifically for the purposes of the factory without having to modify the DSL. This is really nice! The new extensions are a really big step towards the reuse of DSLs for factory building.

In order to target the models for a specific implementation technology the team has added a Technology Extensions library which allows you to dynamically extend the model at runtime. If you look at the service designer model properties you'll see a property for implementation technology and you have a choice of either ASMX or WCF.

This property dynamically loads up a set of model extensions that provides additional properties and actions that are specific for the selected technology. Once the extension is loaded then the properties for the model elements show the additional properties for the specific technology extension.

Tailoring the Factory to Invoke a Workflow

It just so happens that just like there are two ways to create web services within .Net there are two ways to host workflows within a web service. You can use the native ASMX hosting method provided with Windows Workflow or you can instantiate the workflow runtime in a WCF web service and invoke the workflow using the ManualWorkflowScheduler. This allows us to use the existing Technology Extensions to tailor the hosting method based on the selected implementation technology in the service model.

Extending the Object Model

First we need to extend the OperationContract ObjectExtender with a new property called InvokesWorkflow that will be presented to the DSL user once they have selected an implementation technology.

Below is a sample of the code I added to the WCFOperationContract:

        private bool invokesWorkflow = false;

        [Category(ServiceContractWCFExtensionProvider.ExtensionProviderPropertyCategory),
         Description("Specifies the if the operation should invoke a workflow to handle the request."),
         ReadOnly(false),
         BrowsableAttribute(true)]
        [XmlElement("InvokesWorkflow")]
        public bool InvokesWorkflow
        {
            get { return invokesWorkflow; }
            set { invokesWorkflow = value; }
        }

That's all we have to do to add our new property to the DSL. Now as our designers are working on a service's design they can indicate if the operation should invoke a workflow or not. This is so much simpler than having to modify the DSL and republish it.

Modifying the Implementation Specific Text Templates

Next we need to modify the code generation templates to add the technology specific implementations to the code. You'll find the templates under the ServiceContractDSL project in a folder called TextTemplates. They have created one for each technology extension, I am assuming the Service Factory Team did this to keep things simple. If I find out differently, I'll let you know in a later post.

I modified the WCF specific service implementation template to do the following:

Add using statements for the various workflow assemblies.
Add a new method called GetWCFImplementation which inserts the hosting code to the generated classes methods.
Parse out the parts of the request and add them to a Dictionary that is passed to the workflow when it is invoked.
Instantiate the response message class.
Parse out the parts of the response and assigned their return values from the Dictionary after the workflow has completed.
Return the response message class.

Below is the modified template:

<#@ Template Language="C#" Inherits="Microsoft.Practices.Modeling.CodeGeneration.Strategies.TextTemplating.ModelingTextTransformation" #>
<#@ Import Namespace="System.Text" #>
<#@ Import Namespace="System.Globalization" #>
<#@ Import Namespace="System.Collections.Generic" #>
<#@ Import Namespace="System.ServiceModel" #>
<#@ Import Namespace="Microsoft.Practices.ServiceFactory.ServiceContracts" #>
<#@ Import Namespace="Microsoft.Practices.ServiceFactory.DataContracts" #>
<#@ Import Namespace="Microsoft.Practices.ServiceFactory.Extenders.DataContract.Wcf" #>
<#@ Import Namespace="Microsoft.VisualStudio.Modeling" #>
<#@ Assembly Name="Microsoft.Practices.ServiceFactory.DataContracts.Dsl, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5d6a471ce3d28564" #>
<#@ Assembly Name="Microsoft.Practices.ServiceFactory.Extenders.DataContract.Wcf, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5d6a471ce3d28564" #>
<#@ Assembly Name="Microsoft.Practices.ServiceFactory.ServiceContracts.Dsl, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5d6a471ce3d28564" #>
<#@ Assembly Name="System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" #>
<#@ ModelInjector processor="ModelInjectorDirectiveProcessor" #>
<#@ include file="TextTemplates\WCF\CS\CommonTextTransformation.tt" #>
//------------------------------------------------------------------------------
// 
//     This code was generated by a tool.
//
//     Changes to this file may cause incorrect behavior and will be lost if
//     the code is regenerated.
// 
//------------------------------------------------------------------------------

using System;
using System.Workflow;
using System.Workflow.ComponentModel;
using System.Workflow.Runtime;
using System.Workflow.Runtime.Hosting;
using System.Workflow.Activities;
using WCF = global::System.ServiceModel;

namespace <#=CurrentExtender.ArtifactLink.Namespace#>
{	
	/// 
	/// Service Class - <#= CurrentElement.Name #>
	/// 
	[WCF::ServiceBehavior(Name = "<#= CurrentElement.Name #>", 
		Namespace = "<#= CurrentExtender.Namespace #>", 
		InstanceContextMode = WCF::InstanceContextMode.<#= CurrentExtender.InstanceContextMode.ToString() #>, 
		ConcurrencyMode = WCF::ConcurrencyMode.<#= CurrentExtender.ConcurrencyMode.ToString() #> )]
	public abstract class <#= CurrentElement.Name #>Base <#= BuildInheritedServiceContract(CurrentElement.ServiceContract) #>
	{
<#
		if (CurrentElement.ServiceContract != null) {
#>
		#region <#= CurrentElement.ServiceContract.Name #> Members
<#
		foreach(Operation operation in CurrentElement.ServiceContract.Operations)
		{
			WCFOperationContract wcfOperation = GetObjectExtender(operation);
            if(wcfOperation.GenerateCode)
            {
			    if (!wcfOperation.AsyncPattern)
			    {

#>

		public virtual <#= GetResponseElement(operation.Response) #> <#= operation.Name #>(<#= GetRequestElement(operation.Request) #>)
		{
			<#= GetImplementation(operation.Request) #>
		}

<#
			    }
			    else
			    {

#>

		public virtual IAsyncResult Begin<#=operation.Name#>(<#= GetRequestElement(operation.Request,UseComma.Yes) #>AsyncCallback callback, object state)
		{
			return null;
		}

		public virtual <#= GetResponseElement(operation.Response) #> End<#=operation.Name#>(IAsyncResult result)
		{
			<#= GetImplementation(operation.Request) #>
		}

<#			    } // close if AsyncPattern
            } // close if Generatecode

		} // close Operations foreach
#>
		#endregion		
<#
	} // end if
#>		
	}
	
	public partial class <#= CurrentElement.Name #> : <#= CurrentElement.Name #>Base
	{
<#
		if (CurrentElement.ServiceContract != null) {
#>
		#region <#= CurrentElement.ServiceContract.Name #> Members
<#
		foreach(Operation operation in CurrentElement.ServiceContract.Operations)
		{
			WCFOperationContract wcfOperation = GetObjectExtender(operation);
            if(wcfOperation.GenerateCode)
            {
			    if (!wcfOperation.AsyncPattern)
			    {

#>

		public override <#= GetResponseElement(operation.Response) #> <#= operation.Name #>(<#= GetRequestElement(operation.Request) #>)
		{
			<#= GetWCFImplementation(operation) #>
		}

<#
			    }
			    else
			    {

#>

		public override <#= GetResponseElement(operation.Response) #> End<#=operation.Name#>(IAsyncResult result)
		{
			<#= GetWCFImplementation(operation) #>
		}

<#			    } // close if AsyncPattern
            } // close if Generatecode

		} // close Operations foreach
#>
		#endregion		
<#
	} // end if
#>		
	}
	
}

<#+
	private string BuildInheritedServiceContract(ServiceContract serviceContract)
	{
		if (serviceContract == null)
		{
			return string.Empty;
		}
		else
		{
			return ": " + ResolveServiceContractNameAndAddProjectRef(serviceContract);
		}
	}
	
	private string ResolveServiceContractNameAndAddProjectRef(ServiceContract contract)
	{
		WCFServiceContract wfcSc = GetObjectExtender(contract);
		if(wfcSc == null)
		{
			return "I" + contract.Name;
		}
		AddProjectReference(wfcSc.ArtifactLink);
		return wfcSc.ArtifactLink.Namespace + ".I" + contract.Name;
	}

	private string GetWCFImplementation(Operation operation)
	{
		if(operation.Response != null)
		{
			string result = "";
    		WCFOperationContract wcfOc = GetObjectExtender(operation);

            if(wcfOc.InvokesWorkflow)
            {
				string nl = "\r\n\t\t\t"; 
                result = "// Build the parameters for the Workflow" + nl;
                result += "Dictionary parameters = new Dictionary();" + nl;

                foreach(MessagePart mPart in operation.Request.MessageParts)
                { 
                    result += "parameters.Add(\"" + mPart.Name +"\", " + operation.Request.Name + "." + mPart.Name+ ");" + nl; 
                }

                result += "// Execute the Workflow" + nl;
                result += "// TODO: change myWorkflow to the name of the workflow to execute" + nl;
                result += "WFHost.ExecuteWorkflow(typeof(myWorkflow), parameters);" + nl;
                result += "// Build the response based on the parameters" + nl;
                result += GetResponseElement(operation.Response) + " response = new " + GetResponseElement(operation.Response) + "();" + nl;

                foreach(MessagePart mPart in operation.Response.MessageParts)
                { 
                    if(mPart is DataContractMessagePart)
                    {
                        DataContractMessagePart dcmPart = (DataContractMessagePart)mPart;
                        result += "response." + mPart.Name + " = (" + dcmPart.Type + ")parameters[\"" + mPart.Name + "\"];" + nl; 
                    }
                    else if(mPart is XsdElementMessagePart)
                    {
                        XsdElementMessagePart xsdmPart = (XsdElementMessagePart)mPart;
                        int nPos = xsdmPart.Element.IndexOf('?');
                        string strTemp = xsdmPart.Element.Substring(nPos + 1, (xsdmPart.Element.Length - (nPos + 1)));
                        result += "response." + mPart.Name + " = (" + strTemp + ")parameters[\"" + mPart.Name + "\"];" + nl; 
                    }
                }

                result += "return response;" + nl;
            }
            else
            {
                result = "return null;";
            }

			return result;
		}

		return string.Empty;
	}
#>

Below is the generated code based on the template changes:

//------------------------------------------------------------------------------
// 
//     This code was generated by a tool.
//
//     Changes to this file may cause incorrect behavior and will be lost if
//     the code is regenerated.
// 
//------------------------------------------------------------------------------

using System;
using System.Workflow;
using System.Workflow.ComponentModel;
using System.Workflow.Runtime;
using System.Workflow.Runtime.Hosting;
using System.Workflow.Activities;
using WCF = global::System.ServiceModel;

namespace WCF.ServiceImplementation
{	
	/// 
	/// Service Class - MyService
	/// 
	[WCF::ServiceBehavior(Name = "MyService", 
		Namespace = "WCF.ServiceImplementation", 
		InstanceContextMode = WCF::InstanceContextMode.PerSession, 
		ConcurrencyMode = WCF::ConcurrencyMode.Single )]
	public abstract class MyServiceBase : WCF.ServiceContracts.IMyServiceContract
	{
		#region MyServiceContract Members

		public virtual WCF.MessageContracts.Response MyOperation(WCF.MessageContracts.Request request)
		{
			return null;
		}

		#endregion		
		
	}
	
	public partial class MyService : MyServiceBase
	{
		#region MyServiceContract Members

		public override WCF.MessageContracts.Response MyOperation(WCF.MessageContracts.Request request)
		{
			// Build the parameters for the Workflow
			Dictionary parameters = new Dictionary();
			parameters.Add("RequestPayload", Request.RequestPayload);
			// Execute the Workflow
			// TODO: change myWorkflow to the name of the workflow to execute
			WFHost.ExecuteWorkflow(typeof(myWorkflow), parameters);
			// Build the response based on the parameters
			WCF.MessageContracts.Response response = new WCF.MessageContracts.Response();
			response.ResponsePayload = (ServiceResponse)parameters["ResponsePayload"];
			return response;
			
		}

		#endregion		
		
	}
	
}

I made similar changes for the ASMX implementation but tailored them towards using the native workflow hosting methods. As you can see, you can make some minor modifications to the new version of the Service Factory, and provide a lot of additional functionality without much work.

If you decide you want to keep the original Technology Extensions intact, you can always create another Technology Extension based on one of the original extensions with just your changes. This way you can offer users of the service factory multiple custom implementations.

I think the direction the Service Factory Team has taken this new version of the service factory is really promising and I hope to see them apply these new extensions to the rest of the factories. Keep up the good work!

Its All About Reuse - Part 2

Jim Lavin — Tue, 14 Aug 2007 10:09:10 GMT

In my last post I discussed some of the other life cycle artifacts that I thought should be included in a Software Factory. In this post I'll show how to use T4 templates to generate a Use Case document from an XML data file.

To do this we can invoke a Custom Directive from within a Text Template to parse the XML file and reformat in to an HTML Document. The MSDN's DSL Tools documentation provides a great example on how to create a Custom Text Template Directive Processor

I've modified the class, provided in the sample, a little to just include the code required to use the XML DOM:

using System;
using System.CodeDom;
using System.CodeDom.Compiler;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Text;
using System.Xml;
using System.Xml.Serialization;
using Microsoft.VisualStudio.TextTemplating;

namespace XMLDirectiveProcessor
{
    class XMLDirectiveProcessor : DirectiveProcessor
    {
        //this buffer stores the code that is added to the
        //generated transformation class after all the processing is done
        //---------------------------------------------------------------------
        private StringBuilder codeBuffer;

        //Using a Code Dom Provider creates code for the
        //generated transformation class in either Visual Basic or C#.
        //If you want your directive processor to support only one language, you
        //can hard code the code you add to the generated transformation class.
        //In that case, you do not need this field.
        //--------------------------------------------------------------------------
        private CodeDomProvider codeDomProvider;

        //this stores the full contents of the text template that is being processed
        //--------------------------------------------------------------------------
        private String templateContents;

        //These are the errors that occur during processing. The engine passes
        //the errors to the host, and the host can decide how to display them,
        //for example the the host can display the errors in the UI
        //or write them to a file.
        //---------------------------------------------------------------------
        private CompilerErrorCollection errorsValue;

        public new CompilerErrorCollection Errors
        {
            get { return errorsValue; }
        }

        //Each time this directive processor is called, it creates a new property.
        //We count how many times we are called, and append "n" to each new
        //property name. The property names are therefore unique.
        //-----------------------------------------------------------------------------
        private int directiveCount = 0;

        public override void Initialize(ITextTemplatingEngineHost host)
        {
            //we do not need to do any initialization work
        }

        public override void StartProcessingRun(CodeDomProvider languageProvider, String templateContents, CompilerErrorCollection errors)
        {
            //the engine has passed us the language of the text template
            //we will use that language to generate code later
            //----------------------------------------------------------
            this.codeDomProvider = languageProvider;
            this.templateContents = templateContents;
            this.errorsValue = errors;

this.codeBuffer = new StringBuilder();
}

        //Before calling the ProcessDirective method for a directive, the
        //engine calls this function to see whether the directive is supported.
        //Notice that one directive processor might support many directives.
        //---------------------------------------------------------------------
        public override bool IsDirectiveSupported(string directiveName)
        {
            if (string.Compare(directiveName, "XMLDirective", StringComparison.OrdinalIgnoreCase) == 0)
            {
                return true;
            }

return false;
}

public override void ProcessDirective(string directiveName, IDictionary<string, string> arguments)
 {
 if (string.Compare(directiveName, "XMLDirective", StringComparison.OrdinalIgnoreCase) == 0)
 {
 string fileName;

                if (!arguments.TryGetValue("FileName", out fileName))
                {
                    throw new DirectiveProcessorException("Required argument 'FileName' not specified.");
                }

                if (string.IsNullOrEmpty(fileName))
                {
                    throw new DirectiveProcessorException("Argument 'FileName' is null or empty.");
                }

                //Now we add code to the generated transformation class.
                //This directive supports either Visual Basic or C#, so we must use the
                //System.CodeDom to create the code.
                //If a directive supports only one language, you can hard code the code.
                //--------------------------------------------------------------------------

CodeMemberField documentField = new CodeMemberField();

                documentField.Name = "document" + directiveCount + "Value";
                documentField.Type = new CodeTypeReference(typeof(XmlDocument));
                documentField.Attributes = MemberAttributes.Private;

CodeMemberProperty documentProperty = new CodeMemberProperty();

                documentProperty.Name = "Document" + directiveCount;
                documentProperty.Type = new CodeTypeReference(typeof(XmlDocument));
                documentProperty.Attributes = MemberAttributes.Public;
                documentProperty.HasSet = false;
                documentProperty.HasGet = true;

                CodeExpression fieldName = new CodeFieldReferenceExpression(new CodeThisReferenceExpression(), documentField.Name);
                CodeExpression booleanTest = new CodeBinaryOperatorExpression(fieldName, CodeBinaryOperatorType.IdentityEquality, new CodePrimitiveExpression(null));
                CodeExpression rightSide = new CodeMethodInvokeExpression(new CodeTypeReferenceExpression("XmlReaderHelper"), "ReadXml", new CodePrimitiveExpression(fileName));
                CodeStatement[] thenSteps = new CodeStatement[] { new CodeAssignStatement(fieldName, rightSide) };

CodeConditionStatement ifThen = new CodeConditionStatement(booleanTest, thenSteps);
documentProperty.GetStatements.Add(ifThen);

CodeStatement s = new CodeMethodReturnStatement(fieldName);
documentProperty.GetStatements.Add(s);

                CodeGeneratorOptions options = new CodeGeneratorOptions();
                options.BlankLinesBetweenMembers = true;
                options.IndentString = "    ";
                options.VerbatimOrder = true;
                options.BracingStyle = "C";

                using (StringWriter writer = new StringWriter(codeBuffer, CultureInfo.InvariantCulture))
                {
                    codeDomProvider.GenerateCodeFromMember(documentField, writer, options);
                    codeDomProvider.GenerateCodeFromMember(documentProperty, writer, options);
                }

}
//end XMLDirective

            //Track how many times the processor has been called.
            //-----------------------------------------------------------------
            directiveCount++;

}
//end ProcessDirective

        public override void FinishProcessingRun()
        {
            this.codeDomProvider = null;

            //important: do not do this:
            //the get methods below are called after this method
            //and the get methods can access this field
            //-----------------------------------------------------------------
            //this.codeBuffer = null;
        }

        public override string GetPreInitializationCodeForProcessingRun()
        {
            //Use this method to add code to the start of the
            //Initialize() method of the generated transformation class.
            //We do not need any pre-initialization, so we will just return "".
            //-----------------------------------------------------------------
            //GetPreInitializationCodeForProcessingRun runs before the
            //Initialize() method of the base class.
            //-----------------------------------------------------------------
            return String.Empty;
        }

        public override string GetPostInitializationCodeForProcessingRun()
        {
            //Use this method to add code to the end of the
            //Initialize() method of the generated transformation class.
            //We do not need any post-initialization, so we will just return "".
            //------------------------------------------------------------------
            //GetPostInitializationCodeForProcessingRun runs after the
            //Initialize() method of the base class.
            //-----------------------------------------------------------------
            return String.Empty;
        }

        public override string GetClassCodeForProcessingRun()
        {
            //Return the code to add to the generated transformation class.
            //-----------------------------------------------------------------
            return codeBuffer.ToString();
        }

        public override string[] GetReferencesForProcessingRun()
        {
            //This returns the references that we want to use when
            //compiling the generated transformation class.
            //-----------------------------------------------------------------
            //We need a reference to this assembly to be able to call
            //XmlReaderHelper.ReadXml from the generated transformation class.
            //-----------------------------------------------------------------
            return new string[]
            {
                "System.Xml",
                this.GetType().Assembly.Location
            };
        }

        public override string[] GetImportsForProcessingRun()
        {
            //This returns the imports or using statements that we want to
            //add to the generated transformation class.
            //-----------------------------------------------------------------
            //We need XMLDirectiveProcessor to be able to call XmlReaderHelper.ReadXml
            //from the generated transformation class.
            //-----------------------------------------------------------------
            return new string[]
            {
                "System.Xml",
                "XMLDirectiveProcessor"
            };
        }
    }
    //end class XMLDirectiveProcessor

    //-------------------------------------------------------------------------
    // the code that we are adding to the generated transformation class
    // will call this method
    //-------------------------------------------------------------------------
    public static class XmlReaderHelper
    {
        public static XmlDocument ReadXml(string fileName)
        {
            XmlDocument d = new XmlDocument();

            using (XmlTextReader reader = new XmlTextReader(fileName))
            {
                try
                {
                    d.Load(reader);
                }
                catch (System.Xml.XmlException e)
                {
                    throw new DirectiveProcessorException("Unable to read the XML file.", e);
                }
            }
            return d;
        }
    }
}

This class is part of a C# Class Library that can be used by the Text Template Engine inside of Visual Studio. In order to get Visual Studio to recognize the custom directive you need to add a registry entry. I've included a sample below:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\TextTemplating\DirectiveProcessors\XMLDirectiveProcessor]
"Class"="XMLDirectiveProcessor.XMLDirectiveProcessor"
"CodeBase"="<YourPath>\\XMLDirectiveProcessor\\bin\\Debug\\XMLDirectiveProcessor.dll"

Next I created a new Class Library Project to use as a test harness for the Custom Directive Processor. I then created an XML file to hold the Use Case data. Below is the data I'll use:

<?xml version="1.0" encoding="utf-8" ?>

<Doc>

<UseCases>

  <UseCase>

    <Project>Delivery Service</Project>

    <UseCaseName>Login to Account</UseCaseName>

    <UseCaseNumber>UC001</UseCaseNumber>

    <UseCaseAuthor>Jim Lavin</UseCaseAuthor>

    <LastRevised>11/10/2003</LastRevised>

    <Summary>

      <![CDATA[Used to authenticate and identify the user with the web application.]]>

    </Summary>

    <Actors>

      <Actor>Sender</Actor>

      <Actor>Delivery Clerk</Actor>

      <Actor>Courier</Actor>

      <Actor>SuD</Actor>

      <Actor>DBMS</Actor>

    </Actors>

    <Preconditions>

      <Precondition>

        <![CDATA[The user's information must exist in the DBMS.]]>

      </Precondition>

    </Preconditions>

    <BasicCourse>

      <InitializationSteps>

        <InitializationStep>

          <![CDATA[The user navigates to the main web page.]]>

        </InitializationStep>

      </InitializationSteps>

      <ProcessSteps>

        <ProcessStep>

          <![CDATA[The user enters his/her email address in the Email field.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The user enters his/her password in the Password field.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The user clicks on the Submit icon.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD validates that the email address and password have been entered.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD queries the User Table for the user credentials.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD creates an instance of a User object stores it in the Session State.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD displays the message "Welcome, User Name" in place of the login fields.]]>

        </ProcessStep>

      </ProcessSteps>

      <TerminationSteps>

        <TerminationStep>

          <![CDATA[The SuD updates the user menu with appropriate menu options.]]>

        </TerminationStep>

      </TerminationSteps>

    </BasicCourse>

    <Exceptions>

      <Exception>

        <![CDATA[Either the email address or password has not been entered. The SuD redisplays the web page with an error indicating the missing field.]]>

      </Exception>

      <Exception>

        <![CDATA[The SuD cannot validate the user credentials. The SuD redirects the user to an error page indicating the information that is incorrect.]]>

      </Exception>

    </Exceptions>

    <Postconditions>

      <Postcondition>

        <![CDATA[A valid user object has been stored to the Session State.]]>

      </Postcondition>

      <Postcondition>

        <![CDATA[The welcome message is displayed.]]>

      </Postcondition>

      <Postcondition>

        <![CDATA[The proper menu is displayed for the user.]]>

      </Postcondition>

    </Postconditions>

    <ScreensReferenced>

      <Screen>Login Page</Screen>

    </ScreensReferenced>

    <SystemInterfaces>

      <SystemInterface>DBMS</SystemInterface>

    </SystemInterfaces>

    <DBMSInterfaces>

      <DBMSInterface>User Table</DBMSInterface>

    </DBMSInterfaces>

    <Issues>

      <Issue>

        <Status>Closed</Status>

        <OpenDate>11/01/2003</OpenDate>

        <CloseDate>11/02/2003</CloseDate>

        <Owner>Jim Lavin</Owner>

        <Title>Need to add fields to User Table</Title>

        <Description>

          <![CDATA[Need to add fields for the user's email address and password to the user table along with the appropriate indexes.]]>

        </Description>

        <Comments>

          <Comment>

            <Commenter>Jim Lavin</Commenter>

            <DateEntered>11/02/2003</DateEntered>

            <CommentText>

              <![CDATA[Added the requested fields to the user table definition.]]>

            </CommentText>

          </Comment>

        </Comments>

      </Issue>

    </Issues>

    <Assumptions>

      <Assumption>

        <![CDATA[All users who access the system will have access to a web browser.]]>

      </Assumption>

    </Assumptions>

  </UseCase>

  <UseCase>

    <Project>Delivery Service</Project>

    <UseCaseName>Retrieve Lost Password</UseCaseName>

    <UseCaseNumber>UC002</UseCaseNumber>

    <UseCaseAuthor>Jim Lavin</UseCaseAuthor>

    <LastRevised>11/10/2003</LastRevised>

    <Summary>

      <![CDATA[Process used to recover a lost user password. The password is reset and then sent via email.]]>

    </Summary>

    <Actors>

      <Actor>Sender</Actor>

      <Actor>Delivery Clerk</Actor>

      <Actor>Courier</Actor>

      <Actor>SuD</Actor>

      <Actor>DBMS</Actor>

    </Actors>

    <Preconditions>

      <Precondition>

        <![CDATA[The user must have an account on the System.]]>

      </Precondition>

    </Preconditions>

    <BasicCourse>

      <InitializationSteps>

        <InitializationStep>

          <![CDATA[The user has entered an invalid password and has clicked on the link to retrieve a lost password.]]>

        </InitializationStep>

      </InitializationSteps>

      <ProcessSteps>

        <ProcessStep>

          <![CDATA[The user enters his/her email address and clicks on the submit icon.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD looks up the email address.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The user clicks on the Submit icon.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD generates a new password.]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD updates the user's record in the User Table]]>

        </ProcessStep>

        <ProcessStep>

          <![CDATA[The SuD emails the new password to the user.]]>

        </ProcessStep>

      </ProcessSteps>

      <TerminationSteps>

        <TerminationStep>

          <![CDATA[The SuD has found the user and sent a new password to the user.]]>

        </TerminationStep>

      </TerminationSteps>

    </BasicCourse>

    <Exceptions>

      <Exception>

        <![CDATA[The user did not enter an email address. The SuD redisplays the web page with an error indicating the field is required.]]>

      </Exception>

      <Exception>

        <![CDATA[The SuD could not find the email address entered. The SuD redisplays the web page with an error page indicating the email address was not found.]]>

      </Exception>

    </Exceptions>

    <Postconditions>

      <Postcondition>

        <![CDATA[The user's password has been set to a temporary password and it has been emailed to the user.]]>

      </Postcondition>

    </Postconditions>

    <GUIsReferenced>

      <Screen>Retrieve Lost Password Page</Screen>

    </GUIsReferenced>

    <SystemInterfaces>

      <SystemInterface>SMTP Server</SystemInterface>

      <SystemInterface>DBMS</SystemInterface>

    </SystemInterfaces>

    <DBMSInterfaces>

      <DBMSInterface>User Table</DBMSInterface>

    </DBMSInterfaces>

    <Issues />

    <Assumptions>

      <Assumption>

        <![CDATA[All users who access the system will have access to a web browser.]]>

      </Assumption>

    </Assumptions>

  </UseCase>

</UseCases>

</Doc>

I then created the Text Template below to process the XML Data File and create an HTML document. The Text Template iterates through each UseCase and its sub-elements and then uses a switch statement based on the element name to emit the desired output. I handle embedded elements in the same way, first I iterate through the sub-elements and then use a switch statement to emit the desired output. You can use this same template to generate any type of document output by replacing the HTML with the formatting required by the document specification.

The XMLDirective line is used to load the XMLDirectiveProcessor class and use it to load and access the DOM. The Class gives you access to the document via the Document0 property. You can then use any XmlDocument processing code you want to process the document.

If you want to debug your template, remove the // from line 7 and it will cause the system to break and allow you to step through your template in the Visual Studio Debugger. This is a great resource if you are having problems with your template's output. Once you get the debugger started you can set breakpoints and watches, just like with your normal code.

<#@ assembly name="System.Xml" #>
<#@ template debug="true" #>
<#@ output extension=".html" #>
<# //This will call the custom directive processor. #>
<#@ XMLDirective Processor="XMLDirectiveProcessor" FileName="<InsertPath>\UseCases.xml" #>
<# //Uncomment this line if you want to see the generated transformation class. #>
<# //System.Diagnostics.Debugger.Break(); #>
<# //This will use the results of the directive processor. #>
<# //The directive processor has read the XML and stored it in Document0. #>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252" />
<title>Use Case</title>
</head>
<body lang="en-us">
<#
 //Get the root UseCases node
 XmlNode node = Document0.DocumentElement.SelectSingleNode("UseCases");
 // iterate through each child UseCase
 foreach (XmlNode member in node.ChildNodes)
 {
#>
<div>
<table border="1" cellspacing="0" cellpadding="5" width="800" >
<thead>
<tr>
 <td colspan="2" valign="top" align="center">
 USE CASE
 </td>
</tr>
</thead>
<#
 // iterate through each child element of the use case
 foreach (XmlNode child in member.ChildNodes)
 {
 // emit different output based on the child element
 switch(child.Name)
 {
 case "Project":
#>
<tr>
 <td valign="top">
 Project:
 </td>
 <td valign="top">
 
 <# Write(child.InnerText); #>
 
 </td>
</tr>
<#
 break;
 case "UseCaseName":
#>
<tr>
 <td valign="top">
 Use Case Name:
 </td>
 <td valign="top">
 
 <# Write(child.InnerText); #>
 
 </td>
</tr>
<#
 break;
 case "UseCaseNumber":
#>
<tr>
 <td valign="top">
 Use Case Number:
 </td>
 <td valign="top">
 
 <# Write(child.InnerText); #>
 
 </td>
</tr>
<#
 break;
 case "UseCaseAuthor":
#>
<tr>
 <td valign="top">
 Use Case Author:
 </td>
 <td valign="top">
 
 <# Write(child.InnerText); #>
 
 </td>
</tr>
<#
 break;
 case "LastRevised":
#>
<tr>
 <td valign="top">
 Last Revised:
 </td>
 <td valign="top">
 
 <# Write(child.InnerText); #>
 
 </td>
</tr>
<#
 break;
 case "Summary":
#>
<tr>
 <td valign="top">
 Summary:
 </td>
 <td valign="top">
 
 <# Write(child.InnerText); #>
 
 </td>
</tr>
<#
 break;
 case "Actors":
#>
<tr>
 <td valign="top">
 Actors:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through the child elements
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<# Write(childnode.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "Preconditions":
#>
<tr>
 <td valign="top">
 Preconditions:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through the child elements
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<# Write(childnode.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "BasicCourse":
#>
<tr>
 <td valign="top">
 Basic Course:
 </td>
 <td valign="top">
  
 </td>
</tr>
<#
 // iterate through the child elements
 foreach(XmlNode childnode in child.ChildNodes)
 {
 // emit different output based on the child element name
 switch(childnode.Name)
 {
 case "InitializationSteps":
#>
<tr>
 <td valign="top">
 Initialization Steps:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode step in child.ChildNodes)
 {
#>
<li>
<# Write(step.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "ProcessSteps":
#>
<tr>
 <td valign="top">
 Process Steps:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode step in child.ChildNodes)
 {
#>
<li>
<# Write(step.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "TerminationSteps":
#>
<tr>
 <td valign="top">
 Termination Steps:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode step in child.ChildNodes)
 {
#>
<li>
<# Write(step.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 }
 }
 break;
 case "Exceptions":
#>
<tr>
 <td valign="top">
 Exceptions:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<# Write(childnode.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "Postconditions":
#>
<tr>
 <td valign="top">
 Postconditions:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<# Write(childnode.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "ScreensReferenced":
#>
<tr>
 <td valign="top">
 Screens Referenced:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<# Write(childnode.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "SystemInterfaces":
#>
<tr>
 <td valign="top">
 System Interfaces:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<# Write(childnode.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "DBMSInterfaces":
#>
<tr>
 <td valign="top">
 DBMS Interfaces:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<# Write(childnode.InnerText); #>
</li>
<#
 }
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "Issues":
#>
<tr>
 <td valign="top">
 Issues:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child issue
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
<li>
<#
 // iterate through each child element within the issue
 foreach(XmlNode issue in childnode.ChildNodes)
 {
 // emit different output based on the element name
 switch(issue.Name)
 {
 case "Status":
 Write("{0,11}: {1} ", "Status", issue.InnerText);
 break;
 case "OpenDate":
 Write("{0,11}: {1} ", "Open Date", issue.InnerText);
 break;
 case "CloseDate":
 Write("{0,11}: {1} ", "Close Date", issue.InnerText);
 break;
 case "Owner":
 Write("{0,11}: {1} ", "Owner", issue.InnerText);
 break;
 case "Title":
 Write("{0,11}: {1} ", "Title", issue.InnerText);
 break;
 case "Description":
 Write("{0,11}: {1} ", "Description", issue.InnerText);
 break;
 case "Comments":
 Write("{0,11}: ", "Comments");
 // iterate through each comment
 foreach(XmlNode comment in issue.ChildNodes)
 {
 // iterate through each element of the child
 foreach(XmlNode innercomment in comment.ChildNodes)
 {
 // emit different output based on the element name
 switch(innercomment.Name)
 {
 case "Commenter":
 Write("{0,11}: {1} ", "Commenter", innercomment.InnerText);
 break;
 case "DateEntered":
 Write("{0,11}: {1} ", "DateEntered", innercomment.InnerText);
 break;
 case "CommentText":
 Write("{0,11}: {1} ", "Comment", innercomment.InnerText);
 break;
 } // end comment element switch
 } // end comment element foreach
 } // end comment foreach
 break;
 } // end issue element switch
 } // end issue element foreach
#>
</li>
<#
 } // end issues child foreach
#>
 </ol>
 </td>
</tr>
<#
 break;
 case "Assumptions":
#>
<tr>
 <td valign="top">
 Assumptions:
 </td>
 <td valign="top">
 <ol>
<#
 // iterate through each child element
 foreach(XmlNode childnode in child.ChildNodes)
 {
#>
 <li>
 <# Write(childnode.InnerText); #>
 </li>
<#
 } // end assumptions child foreach
#>
 </ol>
 </td>
</tr>
<#
 break;
 } // end UseCaseElement switch
 } // end UseCaseElement foreach
#>
</table>
 
</div>
<#
 } // end UseCase foreach
#>
</body>
</html>

The Custom Directive Processor and Text Template above is just one way you can reuse non-code artifacts within your Software Factory. To me this is a very important part of a Software Factory. And I believe a Software Factory should include all of the artifacts that relate to your Software Product Line or Framework, not just the code.

For those of you who want a working sample of the code discussed above you can pull it from here.

Learning to Build Software Factories

Jim Lavin — Sun, 24 Jun 2007 15:02:35 GMT

I've been involved in DSLs and Software Factories for about six months now, before that I dabbled in building DSLs trying to see how I could use them in enhancing the development experience for both developers and non-developers.

One of the big problems I came across is the lack of a single reference that provided the necessary background information required to assemble a Software Factory.

Granted the MSDN provides all of the documentation on-line and you have the various community sites, but there is nothing out there that ties it all together so you can gain the skills needed to easily assemble a Software Factory using DSLs, GAT and GAX.

So I'm in the process of putting together a series of articles that I think provides a pretty good overview of the information you need to understand before you start assembling a Software Factory using the current toolset.

As the tooling changes in the near future so will the required knowledge base, but for people wanting to take one of the existing Microsoft Patterns & Practices Software Factories and tailor it for their own uses or for those who need to assemble a Software Factory on their own, I think the topics I've selected can help get you off on the right foot.

So far the topics I'm working on are as follows:

Guidance - What is it?
Building DSLs
EnvDTE - Microsoft Visual Studio Automation Primer
Visual Studio Templates
T4 Templates
Actions
Type Convertors
Value Providers
Menus
Custom Wizard Pages
Recipes

I look forward to any feedback or additional topics you might feel are needed.

Technorati Tags: Domain Specific Languages, Software Factories, GAT, GAX