Software Factories

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

Adventures in Extending the Service Factory - Part 2

Jim Lavin — Tue, 20 Nov 2007 05:36:19 GMT

Here's a handy tip when you are trying to learn how the components of the Service Factory works. I've found it very useful over the last couple of weeks.

Since the Service Factory now gets registered under the Visual Studio Experimental Hive you can configure the solution so you can debug it. If you are familiar with debugging DSLs, this should be nothing new. Just follow the steps below:

Set the Service Factory Guidance Package as the Start-Up Project by right-clicking on the project and selecting "Set as Start-Up Project".
Change the Service Factory Guidance Package Project's debug settings to launch Visual Studio under the Experimental Hive:

Right click on the Service Factory Guidance Package Project and select "Properties".
Select the Debug Tab
Configure the Start Action to Start External Program and C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\devenv.exe or where ever you have installed Visual Studio for the program.
Set the Start Options, Command Line Arguments to /rootsuffix Exp

Now you can set breakpoints in the Service Factory code and press F5 to walk through the code in the debugger.

Adventures in Extending the Service Factory

Jim Lavin — Wed, 14 Nov 2007 09:53:36 GMT

I've been trying to add a couple of additional projects and item templates to the Service Factory for workflows and workflow activities. I thought I’d try to use the same techniques that the Service Factory was using to dynamically bind the menu options using the ProjectIsInRoleReference helper in the Binding.xml recipe.

So I did the following:

Added new roles WorkflowRole and ActivitiesRole to the file WSSF\Modeling.CodeGeneration\Source\Enums\ServiceFactoryRoleType.cs. I did this so that the Project Mapping helpers would incorporate the new roles into the ProjectMappingTable and get picked up by the ProjectIsInRoleReference helper.
Added the project templates to Templates\Projects.
Added the projects to the WCF and ASMX.vstemplate files.
Added new item templates to Templates\Items to use when the user selects the menu option to create a workflow or activity.
Added unbound recipes to unfold the templates. I used the CreateTranslator recipe as an example.
Added actions to the Binding.xml using the RefCreator and the ProjectIsInRoleReference just like the action for the CreateTranslator recipe.

When I created a new ASMX or WCF Implementation project, the new projects templates got unfolded without issue. But when I right clicked on either the workflow or activities project I did not see the menu options to launch the recipes on the context menu.

At first I thought maybe the ProjectIsInRoleReference helper was not working, but I added debug output to indicate whether it found a match or not and everything was showing up correctly.

So I was at a loss as to why the menu options didn’t show up. I even tried to bind the recipes to the projects but still no luck. I dug out the older Extensibility Walkthroughs from the Service Factory CTP and there was an example for adding a new recipe through the binding.xml file. It seems that because we are testing in the Experimental Hive you need to run the following command to reset the context menus:

devenv /rootsuffix Exp /Setup

Once I ran the command and then restarted Visual Studio under the experimental hive the menu options showed up. This behavior is not really apparent and I couldn't find anything in the GAX/GAT documentation. I think that has a lot to do with the fact that running under the experimental hive is rather new for GAX/GAT and until the Service Factory you had to use the Clarius SFT to run under the experimental hive.

Guidance Development Tools

Jim Lavin — Wed, 19 Sep 2007 17:13:10 GMT

Guidance includes so many different types of documents; Help, How-Tos, FAQs, Checklists, Code Examples, Design Patterns, and Guidelines to name just a few that coming up with a standard way to develop the needed guidance is a hard task to do from scratch. Luckily Microsoft's patterns & practices group has a tool that can simplify a lot of this for you.

The Microsoft patterns & practice's Guidance Explorer provides a one stop shop for discovering, developing and publishing high quality development guidance. The project web site is located at http://www.codeplex.com/guidanceExplorer. There you can find the latest release of the tool as well as links to existing guidance examples developed by the team.

The tool includes an editor which provides standardized templates for many of the types of guidance you may want to include in your factory. The editor also includes the ability to add custom data to each guidance item for filtering by Technology, Category, Topic and Rule Type.

How I see this tool being used is pretty simple. As part of the factory development process the guidance developer creates the various guidance items using Guidance Explorer and then exports them to HTML for inclusion into the factory contents. The factory developer then includes links to the files as part of the recipes using the <DocumentationLinks> tag. Now when ever a consumer of the factory invokes a recipe the Guidance Navigator can navigate to the document relating to the action just taken. This could be anything; a checklist of what steps need to be taken in the process; a how-to article on the use of a model just created or even code examples of how to use the library just added to the project.

Another way to apply this tool to factory development is by incorporating the web edition of the tool. It provides a read-only version of the Guidance Explorer that can utilize an on-line store allowing all of your guidance to be in one place. The web edition could be launched in a separate pane within Visual Studio to provide the full guidance library to the factory consumer as they use the factory. They can perform searches for specific topics, filter on a particular category or use the Guidance Navigation pane to browse all of the sections at their leisure.

In my opinion this is a must have tool in any factory developers toolkit, check it out.

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.

Its All About Reuse

Jim Lavin — Wed, 27 Jun 2007 18:55:13 GMT

When I look at Software Factories I see a chance to reuse resources in a major way. If you think about it, many of the foundations that Software Factories are built on are rooted in reuse initiatives.

When viewing Software Factories from a reuse perspective, what artifacts should a factory contain besides executable code? Should we include resources from all of the phases that make up the software development life cycle or should we limit the resources to just those needed to produce executable code? I am of the opinion that a Software Factory should include resources from all of the phases of the development lifecycle. Why not reuse the analysis and design artifacts? Their use would help to make the process more repeatable and consistent. Also, by reusing artifacts from the entire lifecycle process, we are helping to accelerate the completion of the entire project from analysis to steady state support. Not only can we provide the code, but we could provide starting point documents for the requirements, design, installation, and run-time support as well.

A list of the type of artifacts I could see being included are:

Requirements
Traceability Matrices
Business Rules Definitions
Use Case Scenarios
Design Diagrams
Unit Tests
Integration Tests
Acceptance Tests
Hardware Deployment Configurations
Deployment Steps
Application Trouble-Shooting Guides
Help-Desk Procedures

Thinking of the contents of Software Factories in this way means we have to think about the big picture. We need to look at everything produced during the development life cycle and decide how it fits in the factory schema and how we provide those artifacts in such a way that they are of value to the end-user.

Do we have our factory generate the artifacts in a series of documents or do we provide the ability to generate the output in several formats to allow it to be consumed by the various life cycle tools that are in use today? How do we store this information to allow it to be reused in so many different ways? Do we use text documents, XML, databases or do we need a repository to store it all?

If we look at how the Guidance Automation Toolkit (GAT) treats artifacts today, a source file has no significance until it is acted upon at runtime. The GAT treats it as an object, it doesn't compile it, it doesn't treat it in any special way, its just a file on the file system. In all reality, the GAT takes no special notice of it until it executes a recipe that references it and then the recipes and actions are the ones who understand its significance. They may use it as a template to generate a source file, they may add it to a project or they may even read it and use the data contained within it to pass to other actions or recipes.

Using this same principle, we should be able to do the same with all of the other lifecycle artifacts. Where appropriate, we can store the raw data in XML files and use T4 Templates to transform the data into any format we need for our life cycle tools. Graphical data can be exported to various standardized formats that can then be read in by our tools as well. We should be thinking of the GAT as a transformation engine and our artifacts as raw data that the recipes and actions transform in to format we need.

As you start to include more and more artifacts from the development lifecycle into your Software Factory, its complexity and size will increase. To handle this, you need to think about how you will standardize their format and transformation. Taking the time up front to define how you will store the information and what formats you'll provide for consumption will help you develop a library of recipes and actions you can reuse through out your projects.

To me, the use of XML data files to hold the raw data and the use of T4 Templates to output the data are probably the best way to do this at this point in time. It is very easy to read in a XML data source and then format it for output using the tools provided in GAT. Over my next few posts, I'll provide some examples of how to take a simple XML data file and transform it using T4 Templates.

Technorati Tags: Software Factories, GAT, GAX

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