Robert Horvick's Weblog : MSBuild

MSBuild Task Generator: Part 11. IntRange explained and the exciting conclusion ...

RobertHorvick — Tue, 23 Mar 2004 18:56:00 GMT

Tomorrow … next week … read: the next time I post.

Specifying an integer range is one of the problems we need solve to have a reasonably robust task generator. It’s one thing to say that a property is assignable from an int, but another to say that the value must be valid. We want to ensure that by the time the task is executing we know the properties are valid.

So first an example input and output:

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

<Tasks>

</Task>

</Tasks>

Generates:

// Auto-generated Task: 3/23/2004 11:18:49 AM

namespace GenTaskTests

{

using System;

using Microsoft.Build.Framework;

using Microsoft.Build.Utilities;

using MBFTaskUtils;

public abstract class BasicType

{

#region Int32Test

private int m_Int32Test;

public virtual int Int32Test

{

get

{

return this.m_Int32Test;

}

set

{

string stringRange = "1;5;10-20";

MBFTaskUtils.IntRangeCollection intRanges = MBFTaskUtils.IntRangeCollection.Parse(stringRange);

if (intRanges.Satisfies(value))

{

this.m_Int32Test = value;

return;

}

throw new System.ArgumentOutOfRangeException("Unexpected value type setting field \"Int32Test\". Expected value in range: 1;5;10" +

"-20");

}

#endregion

}

We won’t cover the CodeDOM today, since we’ve covered everything we need to know in previous posts. Instead we’ll focus on the utility class, IntRangeCollection.

An IntRangeCollection is, as expected, a collection of IntRange instances. An IntRange is a numeric range from N to M, inclusive, where N <= M and both N and M are System.Int32.

An IntRange is expressed as a literal “30” or a range “30-40” (the integers 30 to 40, inclusive).

An IntRangeCollection then has a simple job:

1) Split the range string into it’s semi-colon deliminated parts

2) For each part create an IntRange

3) Allow a value to be tested against all parts

Pretty simple conceptually and even easier to implement:

public class IntRangeCollection : List<IntRange>

{

static public IntRangeCollection Parse(string ranges)

{

IntRangeCollection coll = new IntRangeCollection();

string[] values = ranges.Split(new char[] { ';' }, true);

foreach (string v in values)

{

coll.Add(IntRange.Parse(v));

}

return coll;

}

public bool Satisfies(int val)

{

foreach (IntRange ir in this)

{

if (ir.InRange(val))

{

return true;

}

return false;

}

So then IntRange.Parse is really the only interesting function.

For this I decided to use a regex. Since I’m not a native speaker of the regex syntax I hacked it up a bit – this is a sample app, right? J

There are 2 regexs. One for the single number case and one for the number range case. They can probably be combined if I researched it more. First I check for the range case and then, if there is not match, I check for the single number case.

The method looks roughly like:

public static IntRange Parse(string val)

{

string singleValue = @"^[-]?[0-9]+$";

string multipleValue = @"^([-]?[0-9]+)-([-]?[0-9]+)$";

Regex singleReg = new Regex(singleValue, (RegexOptions)0);

Regex multiReg = new Regex(multipleValue, (RegexOptions)0);

Match mm = multiReg.Match(val);

if (mm.Success)

{

int lb = int.Parse(mm.Groups[1].ToString());

int ub = int.Parse(mm.Groups[2].ToString());

return new IntRange(lb, ub);

}

else

{

Match sm = singleReg.Match(val);

if (sm.Success)

{

int lb = int.Parse(sm.Groups[0].ToString());

return new IntRange(lb);

}

throw new FormatException(string.Format("Error parsing: \"{0}\". Expected string in format \"30\" or \"20-30\""));

}

So know we’ve built up our collection of IntRange instances and need to see if an int satisfies the range. You can easily imagine that code so I won’t bother with it.

So there you go – checking a number for a valid range at build time. Any number of ranges and singe numbers are valid.

Really that’s pretty much the whole program. There is a simple loader that loads the classes that implement ITask, ITaskProperty and IGenerator. This works off a config file (GenTask.config) – a sample is in the GDN workspace source control. Then it’s simply a matter of the loading the XML, creating the instances and running IGenerator.Generate.

So … that’s about all I’m going to say about MSBuild Task Generator. We can discuss anything else at the workspace on GDN. This is where I will provide updates, etc.

Let me know what you thought. What I should have covered. Why this series sucked. Etc.

I’m recently distracted by tablet and Ink input – so maybe that will be next. Who knows.

MSBuild Task Generator: Part 10. Generating properties and the OneOf constraint explained

RobertHorvick — Thu, 18 Mar 2004 17:34:00 GMT

Yesterday we generated the fields and initializers, so today let’s move on to the properties.

Let’s quickly look at an example input:

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

<Tasks>

</Task>

</Tasks>

This should render the following (class and namespace removed):

#region StringWithOneOf

private string m_StringWithOneOf;

public virtual string StringWithOneOf

{

get

{

return this.m_StringWithOneOf;

}

set

{

if (MBFTaskUtils.OneOf.IsOneOf("Value1;Value2;Value3", this.m_StringWithOneOf))

{

this.m_StringWithOneOf = value;

return;

}

throw new System.ArgumentOutOfRangeException("Unexpected value type setting field \"StringWithOneOf\". Expected one of: Value1;V" +

"alue2;Value3");

}

#endregion

Notice a few things about this:

1) We are using the OneOf attribute to specify a valid range of values.

2) We are using a utility classes (MBFTaskUtils) to perform the validation

The utility class looks exactly what you would expect. We split the input (on the semi-colon) into a collection of values and perform a case-insensitive comparison of each value against the field value, returning a Boolean to indicate whether or not a match was found.

Since you’re quite familiar with the CodeDOM by now it should be no surprise how this works – here’s the function I used:

CodeStatement Generate_Call_IsOneOf (MBFTaskProperty tp, CodeMemberField field)

{

CodeStatement[] assignAndReturn = new CodeStatement[] {

new CodeAssignStatement(new CodeFieldReferenceExpression(

new CodeThisReferenceExpression(), field.Name),

new CodePropertySetValueReferenceExpression()),

new CodeMethodReturnStatement()

};

CodeTypeReferenceExpression OneOf_Type = new CodeTypeReferenceExpression(typeof(MBFTaskUtils.OneOf));

CodeMethodReferenceExpression IsOneOf_Method = new CodeMethodReferenceExpression(

OneOf_Type,

"IsOneOf");

CodeMethodInvokeExpression CallIsOneOf = new CodeMethodInvokeExpression(IsOneOf_Method,

new CodeExpression[] {

new CodePrimitiveExpression(tp.OneOfString),

new CodeFieldReferenceExpression(

new CodeThisReferenceExpression(),

field.Name)

}

);

return new CodeConditionStatement(CallIsOneOf, assignAndReturn);

}

Piece of cake. Render the assignment statement and return statement (the success condition), create the type reference and static method call with a few parameters, and finally drop it all into a conditional statement.

But where does the rendered exception throw come from? That comes from the caller of this method. A stripped down version of that function is this:

CodeStatementCollection GenerateSetStatement_AssignToValue(MBFTaskProperty tp, CodeMemberField field)

{

CodeStatementCollection statements = new CodeStatementCollection();

if (tp.OneOfString != null && tp.OneOfString.Length > 0)

{

statements.Add(Generate_Call_IsOneOf(tp, field));

string expMsg = string.Format(

"Unexpected value type setting field \"{0}\". Expected one of: {1}",

tp.Name,

tp.OneOfString);

statements.Add(Generate_Throw_OutOfRange(expMsg));

}

else

{

// field = value

CodeExpression left = new CodeFieldReferenceExpression(

new CodeThisReferenceExpression(), field.Name);

CodeExpression right = new CodePropertySetValueReferenceExpression();

statements.Add(new CodeAssignStatement(left, right));

}

return statements;

}

If we’re rendering a constraint (e.g. OneOf) then do that, otherwise render a simple assignment.

And for the curious Generate_Throw_OutOfRange looks like:

CodeStatement Generate_Throw_OutOfRange(string msg)

{

return new CodeThrowExceptionStatement(

new CodeObjectCreateExpression(typeof(ArgumentOutOfRangeException),

new CodePrimitiveExpression(msg)));

}

No surprises there. Although this does introduce a few new classes. CodeThrowExceptionStatement does what it sounds like. It generates a “throw” statement. CodeObjectCreateExpression too, is what it sounds like. It generates a heap allocation (e.g. “new”) of an object.

So that is the framework for rendering properties as well as rendering a constraint. The other constraints (i.e. Range) are rendered the same way. There is a utility class whose static method is called, it returns a Boolean, and either the assignment is done or an ArgumentOutOfRange exception is thrown. The implementation of Range is more interesting then the CodeDOM support for rendering it’s usage, so tomorrow we’ll look at that.

No warranty expressed or implied. It works on my machine, if it works on yours let me know. Don’t forget the GDN workspace is available too.

MSBuild Task Generator: Part 9. GenerateField and generating array initializers in the CodeDOM.

RobertHorvick — Wed, 17 Mar 2004 18:21:00 GMT

GenerateField is pretty straight-forward .. here, just look:

CodeMemberField GenerateField(MBFTaskProperty tp)

{

string privateName = string.Format("m_{0}", tp.Name);

CodeMemberField cmf = new CodeMemberField(tp.Type, privateName);

cmf.Attributes = MemberAttributes.Private;

if (StringHasData(tp.Default))

{

if (tp.IsArray)

{

cmf.InitExpression = new CodeArrayCreateExpression(tp.Type, tp.DefaultExpressionArray);

}

else

{

cmf.InitExpression = tp.DefaultExpression;

}

return cmf;

}

So we simply create the field (prepending a “m_” – the property and field will otherwise have the same name), mark it private and give it the Type defined in the ITaskProperty member. You can read about ITaskProperty in Part 4 of this series.

The only really interesting part here is the initializer expressions in the case where a Default is specified in the ITaskProperty. There are two cases, the array and the non-array case.

The array case is far more interesting (and explains the non-array case). In the case of an array we need to generate a field with assocaited array initializer syntax.

So GenerateField calls MBFTaskProperty.DefaultExpressionArray (this is why in yesterday’s column we demanded that the ITaskProperty implementer be an MBFTaskProperty instance). DefaultExpressionArray basically splits the semi-colon deliminated default value into an array of the basic type. Basically the following pseudo code:

CodeExpressionCollection ceItems;

foreach(item in Default) {

TargetType instance = createInstanceOfTargetType(item);

ceItems.Add(new CodePrimitiveExpression(instance));

}

return ceItems;

But how does createInstanceOfTargetType work?

We know the type of the target object (both as an enumeration and also as a System.Type), and we know the value we are converting from. Most of the objects are IConvertible so we can simply use Convert.ChangeType(item, TargetType). But there are several that are not IConvertible. The general algorithm is to determine if the type is IConvertible (via a switch), and if so use that interface. However if not then a call to Parse is generated to actually create an instance of the object at runtime. That looks like this:

private CodeExpression CallParse(System.Type t, string val)

{

CodeTypeReferenceExpression ctre = new CodeTypeReferenceExpression(t);

CodeMethodReferenceExpression parse = new CodeMethodReferenceExpression(ctre, "Parse");

return new CodeMethodInvokeExpression(

parse,

new CodeExpression[] {

new CodePrimitiveExpression(val)

}

);

}

private CodeExpression DefaultExpression_Internal(PropertyType type, string val)

{

object o = null;

CodeExpression ce = null;

switch (type)

{

case PropertyType.ITaskItem:

throw new ArgumentException("Can not create a default expression for an ITaskItem");

case PropertyType.SystemDateTime:

ce = CallParse(typeof(DateTime), val);

break;

case PropertyType.SystemSByte:

ce = CallParse(typeof(System.SByte), val);

break;

case PropertyType.SystemString:

o = val;

break;

case PropertyType.SystemUInt16:

ce = CallParse(typeof(System.UInt16), val);

break;

case PropertyType.SystemUInt32:

ce = CallParse(typeof(System.UInt32), val);

break;

case PropertyType.SystemUInt64:

ce = CallParse(typeof(System.UInt64), val);

break;

default:

o = Convert.ChangeType(val, UnarrayType);

break;

}

if (ce == null)

{

ce = new CodePrimitiveExpression(o);

}

return ce;

}

Incidentally this method is also what is used internally in the non-array case (tp.DefaultExpression) (remember that we call this in a loop in the array case). So let’s look at an example: This input:

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

<Tasks>

<Property Name="StringArray" Type="System.String"

IsArray="true" Default="Value1;Value2;Value3"/>

<Property Name="IntArray" Type="System.Int32"

IsArray="true" Default="10;20;30;40"/>

<Property Name="DoubleArray" Type="System.Double"

IsArray="true" Default="10.50;20.75;30.10;40.0001"/>

<Property Name="DateTimeArray" Type="System.DateTime" IsArray="true"

Default="2/16/1992 12:15:12;2/16/1992 12:15:13;2/16/1992 12:15:14"/>

</Task>

</Tasks>

Generates the following fields (properties are removed to keep the post length down):

// Auto-generated Task: 3/17/2004 10:24:51 AM

namespace ArrayTest

{

using System;

using Microsoft.Build.Framework;

using Microsoft.Build.Utilities;

using MBFTaskUtils;

public abstract class Test1 : Microsoft.Build.Utilities.Task

{

#region StringArray

private string[] m_StringArray = new string[] {

"Value1",

"Value2",

"Value3"};

#endregion

#region IntArray

private int[] m_IntArray = new int[] {

10,

20,

30,

40};

#endregion

#region DoubleArray

private System.Double[] m_DoubleArray = new System.Double[] {

10.5,

20.75,

30.1,

40.0001};

#endregion

#region DateTimeArray

private System.DateTime[] m_DateTimeArray = new System.DateTime[] {

System.DateTime.Parse("2/16/1992 12:15:12"),

System.DateTime.Parse("2/16/1992 12:15:13"),

System.DateTime.Parse("2/16/1992 12:15:14")};

#endregion

}

So there you go. A quick overview of the field generation algorithm. Nothing fancy.

By the way a GDN workspace is open where I am posting the project as it evolves. Since it is only prototype code don’t expect much in the way of comments and great design – but over time it will improve. This is blog-quality code J

Lots of known bugs BTW – some bugs, some design issues. Some we’ll tackle on this blog, some not.

No warranty expressed or implied. YMMV.

MSBuild Task Generator: Part 8. Implementing ITaskGenerator (a series within a series)

RobertHorvick — Tue, 16 Mar 2004 18:30:00 GMT

Now that we’re all good friends with the CodeDOM it’s time to look at the far less interesting reason for this whole series … generating MSBuild tasks.

Since we’ve implemented ITask and ITaskProperty it’s time to implement ITaskGenerator.

We’ll be taking a top-down approach to this. We’ll start by looking at the implementation of ITaskGenerator.Generate and then drilling down into each method.

Well, not quite. Generate, for the most part, calls another function named GenerateFile. Let’s start there instead.

CodeNamespace GenerateFile(MBFTaskFile tf)

{

CodeNamespace outerNameSpace = new CodeNamespace(tf.Namespace);

CodeTypeDeclaration ctd = new CodeTypeDeclaration(tf.Class);

ctd.IsClass = true;

ctd.TypeAttributes |= System.Reflection.TypeAttributes.Abstract;

if (StringHasData(tf.BaseClass))

{

ctd.BaseTypes.Add(new CodeTypeReference(tf.BaseClass));

}

outerNameSpace.Types.Add(ctd);

foreach (ITaskProperty tp in tf.Properties)

{

MBFTaskProperty mpfTp = tp as MBFTaskProperty;

if (mpfTp == null)

{

throw new TaskGeneratorException(

"Unable to convert ITaskProperty to MBFTaskProperty - type is: {0}",

tp.GetType().ToString()

);

}

CodeMemberField field = GenerateField(mpfTp);

field.StartDirectives.Add(new CodeRegionDirective(CodeRegionMode.Start, tp.Name));

CodeMemberProperty prop = GenerateProperty(mpfTp, field);

prop.EndDirectives.Add(new CodeRegionDirective(CodeRegionMode.End, tp.Name));

ctd.Members.Add(field);

ctd.Members.Add(prop);

}

return outerNameSpace;

}

Easy enough. Create the namespace (we’ll be generating our code using ICodeGenerator.GenerateCodeFromNamespace so this is our primary container for code artifacts).

Next we generate the type and make it an abstract class.

Finally if a BaseClass is defined (StringHasData checks that the string is not null, and contains a non-zero-length string) add it to the base types of the new class.

Then for each property associated with the task we:

1) Validate that it is an MBFTaskProperty type (since this is a plug-able architecture we need to make sure that we’re using the right parts. This will be clearer when we look at the deployment of the application).

2) Generate the field that backs the property.

3) Generate a region “start” directive based on the property name

4) Generate the property setter/getter

5) Generate the region “end” directive

6) Add the field and property to the class type.

Tomorrow we’ll look at GenerateField and find out why something that seems like it should be very simple to implement has a few gotchas that make it a bit more complex (hint: think about the new attributes introduced in Part 4 of this series and think about how they might affect initialization … specifically IsArray).

Questions? Comments? Insults? Let me know.

And as always – this is sample code. No warranty expressed or implied.

MSBuild Task Generator: Part 7. Rendering a loop in the CodeDOM.

RobertHorvick — Mon, 15 Mar 2004 18:16:00 GMT

For those that asked – on a Friday “tomorrow” means Monday. J

And a few people have asked “what does this have to do with MSBuild” – yeah, I suppose I’m a bit off topic but I’m trying to lay a little foundation so that when I’m talking about the task generator I don’t feel compelled to explain the CodeDOM and can instead focus on the task generation.

Last time we talked about generating a conditional statement – today we’ll look at rendering a simple loop. We’ll create an array of strings and then iterate over them and print out their values. Simple, right? Well … yeah!

First we need an array of strings and the initializer string. It might not be obvious at first but when creating an expression such as “MyType foo = bar” we need to define “bar” first. I want to create the following statement:

string[] colors = new string[] { "Red", "Green", "Blue"};

So first we need to create the array initializer expression as such:

CodeArrayCreateExpression colorsInit =

new CodeArrayCreateExpression(

typeof(string),

new CodeExpression[] {

new CodePrimitiveExpression("Red"),

new CodePrimitiveExpression("Green"),

new CodePrimitiveExpression("Blue")

}

);

And then create a variable (colors) that uses that initializer expression:

CodeVariableDeclarationStatement colors = new CodeVariableDeclarationStatement(

typeof(string[]),

"colors",

colorsInit);

This renders the following:

string[] colors = new string[] {

"Red",

"Green",

"Blue"};

Now we want a simple loop that does the following:

foreach (string s in colors)

{

Console.WriteLine(s);

}

The problem is that we are using the CodeDOM and are trying to be language agnostic, right? And “foreach” does not exist on every platform and therefore the CodeDOM doesn’t really know how to render that. It does, however, know how to render a “for” loop. So let’s shoot for something more like:

for (int index = 0; index < colors.Length; index++)

{

Console.WriteLine(colors[index]);

}

First let’s declare that indexer (index) and assign it to an initial value of 0:

string indexName = "index";

CodeVariableDeclarationStatement index = new CodeVariableDeclarationStatement(

typeof(int),

indexName,

new CodePrimitiveExpression(0)

);

That will be the initializer of our for-loop. Now we need the test condition (index < colors.Length):

CodePropertyReferenceExpression colorsLength = new CodePropertyReferenceExpression(

new CodeVariableReferenceExpression(colorsName),

"Length");

CodeBinaryOperatorExpression indexLTLength = new CodeBinaryOperatorExpression(

new CodeVariableReferenceExpression(indexName),

CodeBinaryOperatorType.LessThan,

colorsLength);

Third we need the loop iteration statement (index++). It turns out that this is not going to use the “++” operation and instead render something more like: index = index + 1; Much like not rendering a “foreach” this is not unexpected.

CodeAssignStatement indexIncrement = new CodeAssignStatement(

new CodeVariableReferenceExpression(indexName),

new CodeBinaryOperatorExpression(

new CodeVariableReferenceExpression(indexName),

CodeBinaryOperatorType.Add,

new CodePrimitiveExpression(1)

)

);

And lastly we need the loop body. This involves an array indexer and a method call. We will need to wrap all of this in a CodeStatement array since the CodeIterationStatement requires that:

CodeArrayIndexerExpression colorsAtIndex = new CodeArrayIndexerExpression(

new CodeVariableReferenceExpression(colorsName),

new CodeExpression[] {

new CodeVariableReferenceExpression(indexName)

}

);

CodeTypeReferenceExpression console = new CodeTypeReferenceExpression(typeof(Console));

CodeMethodReferenceExpression consoleWriteLine = new CodeMethodReferenceExpression(console, "WriteLine");

CodeMethodInvokeExpression performWriteLine = new CodeMethodInvokeExpression(

consoleWriteLine,

new CodeExpression[] {

colorsAtIndex

}

);

CodeStatement[] loopBody = new CodeStatement[] {

new CodeExpressionStatement(performWriteLine)

};

Finally we can now create out iteration statement (whew!):

CodeIterationStatement forColors = new CodeIterationStatement(

index,

indexLTLength,

indexIncrement,

loopBody);

And when we render the array initializer “colors” and the loop “forColors” (along with the namespace and class stubs we learned about earlier – all in a method named “PrintLoop”):

namespace CodeDOMSample

{

using System;

public class LoopSample

{

public virtual void PrintLoop()

{

string[] colors = new string[] {

"Red",

"Green",

"Blue"};

for (int index = 0; (index < colors.Length); index = (index + 1))

{

System.Console.WriteLine(colors[index]);

}

Seems like an awful lot of work to get some basic C# code rendered, right? Yeah, but by doing it this way we are able to pull out our code generator and drop in a new one. The following is the result of generating in VB:

Imports System

Namespace CodeDOMSample

Public Class LoopSample

Public Overridable Sub PrintLoop()

Dim colors() As String = New String() {"Red", "Green", "Blue"}

Dim index As Integer = 0

Do While (index < colors.Length)

System.Console.WriteLine(colors(index))

index = (index + 1)

Loop

End Sub

End Class

End Namespace

And any other language with a ICodeGenerator implementation could also be supported.

So that’s a basic introduction to using the CodeDOM. Tomorrow we’ll start talking about the MSBuild task generator (and about time, too).

MSBuild Task Generator: Part 6. Conditional statements in the CodeDOM.

RobertHorvick — Fri, 12 Mar 2004 18:06:00 GMT

Yesterday we introduced the CodeDOM and covered some fundamentals. Creating a namespace, a class, a member method and a method body. Today we’re going to cover conditionals. I know I promised loops too but conditionals is taking enough space that if I tried to do loops too this would turn into a novel, not a blog post. Loops tomorrow – I promise!

A conditional statement ( if(Boolean) { … } else { … } ) is nothing more then an expression that has a Boolean result and two collections of statements (the code executed if the test is true or false).

We’ll skip the namespace and class declarations from yesterday – please reference those if necessary. For today create a method named “IfSample” that takes 2 parameters (string lhs, string rhs). The purpose of the method is to print a string stating whether or not the string parameters are equal (using String.Equals as our test).

Since we are going to be referencing these two parameters “lhs” and “rhs” a few times let’s define them:

CodeVariableReferenceExpression lhs = new CodeVariableReferenceExpression("lhs");

CodeVariableReferenceExpression rhs = new CodeVariableReferenceExpression("rhs");

Now we create our member method:

CodeMemberMethod ifSample = new CodeMemberMethod();

ifSample.Name = "IfSample";

ifSample.ReturnType = new CodeTypeReference(typeof(void));

ifSample.Attributes = MemberAttributes.Public;

ifSample.Parameters.Add(new CodeParameterDeclarationExpression(typeof(string), lhs.VariableName));

ifSample.Parameters.Add(new CodeParameterDeclarationExpression(typeof(string), rhs.VariableName));

Notice that we are adding a few parameters to the function. These are variables of type string with the names “lhs” and “rhs” (also notice that I use the VariableName property to name them instead of hardcoding the string literals all throughout the code).

Now we want to create this expression:

lhs.Equals(rhs)

So thinking back to yesterday this is pretty easy:

CodeMethodReferenceExpression lhsEquals = new CodeMethodReferenceExpression(lhs, "Equals");

CodeExpression ifTest = new CodeMethodInvokeExpression(lhsEquals, new CodeExpression[] { rhs });

ifTest will be used later when we define the conditional statement.

Next we need to define the true and false statements. Since we’re going to be calling Console.WriteLine more then once we’ll create a method reference as follows:

CodeExpression console = new CodeTypeReferenceExpression(typeof(System.Console));

CodeMethodReferenceExpression consoleWriteLine = new CodeMethodReferenceExpression(console, "WriteLine");

And create a pair of expressions that invoke Console.WriteLine with the correct string literal – one expression for each boolean result.

CodeExpression ifTrueExp = new CodeMethodInvokeExpression(

consoleWriteLine,

new CodeExpression[] {

new CodePrimitiveExpression("This strings are equal")

});

CodeExpression ifFalseExp = new CodeMethodInvokeExpression(

consoleWriteLine,

new CodeExpression[] {

new CodePrimitiveExpression("This strings are not equal")

});

One gotcha is that the CodeConditionStatement class does not take a collection of CodeExpression objects but rather a collection of CodeStatement objects. So we need to create CodeStatement derived objects from our CodeExpression objects. Thankfully the CodeExpressionStatement class is there to help us out. So not we create statement arrays that will be added to the CodeConditionStatement:

CodeStatement[] ifTrue = { new CodeExpressionStatement(ifTrueExp) };

CodeStatement[] ifFalse = { new CodeExpressionStatement(ifFalseExp) };

And finally we create our conditional statement and add it to our method:

CodeConditionStatement ifStatement = new CodeConditionStatement(ifTest, ifTrue, ifFalse);

ifSample.Statements.Add(ifStatement);

Now when we run this code and we render the following:

namespace CodeDOMSample2

{

using System;

public class ConditionalTest

{

public virtual void IfSample(string lhs, string rhs)

{

if (lhs.Equals(rhs))

{

System.Console.WriteLine("This strings are equal");

}

else

{

System.Console.WriteLine("This strings are not equal");

}

There you have it. A generating a conditional expression really isn’t that hard.

As usual – no warranty expressed or implied. Your mileage may vary. Please don’t taunt happy fun ball.

MSBuild Task Generator: Part 5. Introducing the CodeDOM. Hello World was never so much fun.

RobertHorvick — Thu, 11 Mar 2004 17:49:00 GMT

Yesterday we looked at a basic implementation of ITaskProperty – and I promised we start looking at the code generation today. We won’t be looking at the XML -> C# rendering but rather the CodeDOM and generating some basic expressions.

Before we go on I’m going to assume you are familiar with the CodeDOM is – though perhaps you have never used it. If you are not then you will want to do some reading:

Using the CodeDOM

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconusingcodedom.asp

Generating Source Code and Compiling a Program from a CodeDOM Graph

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconusingcodedom.asp

CodeDOM Quick Reference

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconCodeDOMQuickReference.asp

Generating code really isn’t that hard once you understand the patterns.

Let’s look at a few quick examples that will all build on each other into a simple Hello World class.

First we need to create our code generator and provider.

ICodeGenerator gen;

CSharpCodeProvider prov = new CSharpCodeProvider();

gen = prov.CreateGenerator();

That’s what we need to start generating code. Now we need to figure out what to generate. I usually start with a namespace:

CodeNamespace outerNameSpace = new CodeNamespace("CodeDOMSample");

A namespace does not mean much without a class, right? So let’s put one in it.

CodeTypeDeclaration ctd = new CodeTypeDeclaration("HelloWorld");

ctd.IsClass = true;

Now we’re cooking with gas. So let’s stop right here and see what would happen if we add the class to the namespace and then generate some code. First we need to figure out how we want to generate the code using an instance of the CodeGeneratorOptions class. These are the options I usually use when generating code:

CodeGeneratorOptions co = new CodeGeneratorOptions();

co.BracingStyle = "C";

co.BlankLinesBetweenMembers = true;

co.VerbatimOrder = true;

Then we add the type to the namespace:

outerNameSpace.Types.Add(ctd);

And generate to stdout (Console.Out):

gen.GenerateCodeFromNamespace(outerNameSpace, Console.Out, co);

This produces the following (I’ve left all formatting un-changed):

namespace CodeDOMSample

{

public class HelloWorld

{

}

That looks good but it’s missing something. I’d like it to have at last one namespace (System) imported. Thankfully that is really easy to do:

outerNameSpace.Imports.Add(new CodeNamespaceImport("System"));

Now when we render the C# we get this:

namespace CodeDOMSample

{

using System;

public class HelloWorld

{

}

That looks a little better. Now let’s add a public method “SayHello” that will print “Hello World” to the console.

First we need to create a public method. We want a public method named “SayHello” that returns void.

CodeMemberMethod sayHello = new CodeMemberMethod();

sayHello.Name = "SayHello";

sayHello.Attributes = MemberAttributes.Public;

sayHello.ReturnType = new CodeTypeReference(typeof(void));

We’d like this method to perform a Console.WriteLine(“Hello World”);

So first we need to create a reference to the Console type:

CodeTypeReferenceExpression console = new CodeTypeReferenceExpression(typeof(System.Console));

Next we create a reference to the function WriteLine bound to the console type (this is a static method so our caller target is the type, not an instance):

CodeMethodReferenceExpression consoleWriteLine = new CodeMethodReferenceExpression(console, "WriteLine");

Next we create the string literal “Hello World” as a primitive expression:

CodePrimitiveExpression helloWorld = new CodePrimitiveExpression("Hello World");

And finally we bind them all together to invoke the method call with the appropriate parameters:

CodeMethodInvokeExpression sayHelloWorld = new CodeMethodInvokeExpression(

consoleWriteLine,

new CodeExpression[] { helloWorld }

);

Finally add the method call to the member method:

sayHello.Statements.Add(sayHelloWorld);

And add the method to the type:

ctd.Members.Add(sayHello);

Now render one last time:

namespace CodeDOMSample

{

using System;

public class HelloWorld

{

public virtual void SayHello()

{

System.Console.WriteLine("Hello World");

}

Tomorrow we’ll tackle conditional expressions and loops.

As always – this is sample code. No warranty expressed or implied. Your mileage may vary. Etc, etc, etc.

MSBuild Task Generator: Part 4. Implementing ITaskProperty and introducing a few new attributes.

RobertHorvick — Wed, 10 Mar 2004 19:47:00 GMT

Yesterday’s post was … well … boring. But a lot of software is boring so this really isn’t a surprise. Today’s will have a little more to it but still – we’re laying the foundation before talking about the more interesting things (the code generation) … but that starts soon.

So bear with me a little longer.

Today we’re implementing ITaskProperty in a class named MBFTaskProperty.

This is the class declaration and private data member:

namespace MBFTaskGenerator

{

public class MBFTaskProperty : ITaskProperty

{

string m_Name;

PropertyType m_Type;

bool m_Required;

string m_Default;

string m_Range;

string m_OneOf;

bool m_IsArray;

...

}

I would wager that from this you can figure out what most of the accessors look like so I won’t bore you.

But notice one thing – there is no System.Type member but there is an ITaskProperty member (Type) that returns a System.Type instance.

This is pretty easy to implement. First you will recall the XSD was run through xsd.exe to create classes for serialization. One of those classes (actually an enum) is PropertyType. If you haven’t run the XSD through xsd.exe please do so now. Refer to yesterday’s post for the specific command to execute.

So to get the type there is a two-step process:

1) figure out the base type

2) determine if it is an array type

So the pattern looks like this:

public Type Type

{

get

{

Type t = null;

switch (m_Type)

{

case PropertyType.ITaskItem:

t = typeof(Microsoft.Build.Framework.ITaskItem);

break;

...

case PropertyType.SystemBoolean:

t = typeof(System.Boolean);

break;

case PropertyType.SystemUInt64:

t = typeof(System.UInt64);

break;

default:

throw new ArgumentException(string.Format("Unknown type: {0}", m_Type), "Type");

}

if (this.IsArray)

{

t = System.Array.CreateInstance(t, 1).GetType();

}

return t;

}

Simple enough, right? Switch on the enum, figure out the basic type, and if it is an array then create an array of that type and return the type. I’m not sure if there is a better way to get the type of an array of a type from the original type (say that 5 times fast), but for prototype code this is a nice one-line hack.

Before we go further I want to introduce a few more members of the ITaskProperty interface. Each of the following is an optional attribute you can apply to each Property element in the XML input to the code generator.

IsArray: Boolean. Whether or not to generate an array of the Type member. The alternative was to have more types (Boolean, BooleanArray, etc).

Default: String. The default value. The string will be converted to the target type. If it can’t be then an exception will be thrown. At build time if the task parameter is not defined then it will default to this value. Otherwise .NET defaults apply (Boolean is false, Int* is 0, etc).

Range: String. A numeric Range string. You can provide a range (“1-10”), a single numeric (“42”) and any semi-colon separated collection (“1-10;42;50-75;99”). When applied to a numeric type (System.Int32, for example) this will generate the code necessary to ensure that at build time the provided value is an acceptable value. For example if you provided the range “1;2;4;8” and at build-time an attempt to assign “12” was made then an exception would be thrown. Can only be applied to numeric types. If a Default is specified then it must be a valid member of the range.

OneOf: String. A string of values. A semi-colon separated list of values that the build-time value must be one of. This is only used for System.String types. For example if the one of value is “Top;Bottom;Left;Right” then at build time only the string values “Top”, “Bottom”, “Left” or “Right” will be allowed. Anything else will generate an exception. If Default is specified it must be one of these. If the Type is not System.String this will throw an exception at code-gen time. OneOf and IsArray are not compatible. This could be changed easily but at the current time you can’t do this.

Required: Boolean. If this is “true” then the “Required” attribute will be applied to the property. If it is false then it will not. Defaults to false.

Example input (using Default and OneOf) and the generated output. Notice that the code generator uses a utility class to validate the input instead of generating the validation routines everything. The original prototype I wrote did put the validation everywhere. This was more difficult to maintain and did not provide me any benefit. However this change was on the primary reasons I opt’d for using interfaces and allowing the end-user to create their own code generators.

Generates the following:

#region TestProperty

private string m_TestProperty = "None";

public virtual string TestProperty

{

get

{

return this.m_TestProperty;

}

set

{

if (MBFTaskUtils.OneOf.IsOneOf("None;OnlyInline;Any", this.m_TestProperty))

{

this.m_TestProperty = value;

return;

}

throw new System.ArgumentOutOfRangeException("Unexpected value type setting field \"TestProperty\". Expected one of" +

": None;OnlyInline;Any");

}

#endregion

Here is another example, this time using Range. Again notice how a utility class is used to perform the validation. This reduces the amount of code gen that has to occur while still allowing for a flexible solution.

Generates the following:

#region TestProperty

private int m_TestProperty;

public virtual int TestProperty

{

get

{

return this.m_TestProperty;

}

set

{

string stringRange = "1,2,4,8,16";

MBFTaskUtils.IntRangeCollection intRanges = MBFTaskUtils.IntRangeCollection.Parse(stringRange);

if (intRanges.Satisfies(value))

{

this.m_TestProperty = value;

return;

}

throw new System.ArgumentOutOfRangeException("Unexpected value type setting field \" TestProperty\". Expected value in " +

"range: 1,2,4,8,16");

}

#endregion

Make sense?

If not then post a comment and let me know. Tomorrow we’ll start talking about how we get from that XML input to the C# output.

MSBuild Task Generator: Part 3. Implementing ITask

RobertHorvick — Tue, 09 Mar 2004 17:47:00 GMT

Yesterday we introduced the ITask interface. Today we’ll look at a simple implementation of the ITask interface.

I’m not a big fan of reading to be people what they can read for themselves so let’s move on to the code…

[Caveat: this is sample code. This whole series on the blog is sample code. While I am making a reasonable effort with respect to error handling and design, I am not going to take up a lot of room on the blog with comments and error checking that distracts from the intent of the code.]

namespace MBFTaskGenerator

{

public class MBFTaskFile : ITask

{

string m_Namespace;

string m_Class;

string m_BaseClass;

List<ITaskProperty> m_Properties = new List<ITaskProperty>();

public MBFTaskFile(TasksTask task)

{

Namespace = task.Namespace;

Class = task.Class;

BaseClass = (task.BaseClass == null) ?

typeof(Microsoft.Build.Utilities.Task).FullName : task.BaseClass;

}

public IList<ITaskProperty> Properties

{

get

{

return m_Properties;

}

public string Namespace

{

get

{

return m_Namespace;

}

set

{

m_Namespace = value;

}

public string Class

{

get

{

return m_Class;

}

set

{

m_Class = value;

}

public string BaseClass

{

get

{

return m_BaseClass;

}

set

{

m_BaseClass = value;

}

I think the only thing that deserves any explanation is that the default BaseClass, if one is not provided, is Microsoft.Build.Utilities.Task. I choose to implement this in code, instead of in the XSD file because it allows me to validate at compile time instead of catching a problem at runtime.

So that is a basic implementation of the ITask interface.

Tomorrow we’ll look at the ITaskProperty interface. It has a bit more to it.

MSBuild Task Generator: Part 2. The basic interfaces.

RobertHorvick — Mon, 08 Mar 2004 18:29:00 GMT

Last time we looked at the XSD file and a sample rendering from XML to C#. This time I’ll introduce the primary interfaces used in the rendering process.

First we have an ITask.

namespace GenTaskLib

{

public interface ITask

{

IList<ITaskProperty> Properties

{

get;

}

string Namespace

{

get;

}

string Class

{

get;

}

string BaseClass

{

get;

}

An ITask contains a Namespace, Class and BaseClass as well as a collection of ITaskProperty items (which we’ll see next). These map directly to the Namespace, Class and BaseClass attributes of the Task element in the XSD.

Next we have ITaskProperty

namespace GenTaskLib

{

public interface ITaskProperty

{

string Default

{

get;

}

bool IsArray

{

get;

}

string Name

{

get;

}

string Range

{

get;

}

bool Required

{

get;

}

Type Type

{

get;

}

An ITaskProperty, like an ITask, is a mirroring of the XSD attributes. I’ll assume this is all quite clear – otherwise leave a comment.

Finally we have the rendering engine – an ITaskGenerator.

namespace GenTaskLib

{

public interface ITaskGenerator

{

void Generate(ITask tf, TextWriter outStream);

}

Pretty straight forward.

The last thing for today is the loading of the input XML. Since we have an XSD we can use xsd.exe to generate a class for XML serialization. This generated 3 classes and an enum.

The classes are Tasks, TasksTask, and TasksTaskProperty.

The enum is PropertyType.

I encourage you to copy the XSD file into a file named “GenTask.xsd” and run:

xsd.exe /c GenTask.xsd

Tomorrow: Implementing the ITask interface,

MSBuild Tasks, code generation and a tangent I've been stuck on for a while...

RobertHorvick — Thu, 04 Mar 2004 22:30:00 GMT

I'm still quite distracted by MSBuild. I'm also a big fan of code generation. Any time you can combine a few passions you should. If I could find a way to mix in some seafood, a Willamette Valley (Oregon) wine and a Dave Matthew's Band album believe me, I would.

As I noted in an earlier post I needed a simple task that would validate that a project contained a file link to a specific file (BldVer.cs). Soon after I needed several other tasks. One needed many (over 100) potential properties. Certainly writing this all by hand was going to be a tedious process. I started looking at ways I could take the common tasks, like the property accessors and generic validation, and generate that all from a simple XML file.

In the next several posts I'll be walking through a simple implementation of that idea.

This first post will introduce you to the intended input and output.

The input is an XML file. It contains a collection (Tasks) of one or more Task objects. Each Task has several attributes and one or more Property objects. Each Property has several possible attributes. Since we're using XML the easiest way to describe and validate that XML is an XSD. The following is the schema for the input file format.

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

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="Tasks">

<xs:complexType>

<xs:sequence>

<xs:element maxOccurs="unbounded" name="Task">

<xs:complexType>

<xs:sequence>

<xs:element maxOccurs="unbounded" name="Property">

<xs:complexType>

<xs:attribute name="Name" type="xs:string" use="required" />

<xs:attribute name="Required" type="xs:boolean" use="optional" default="false"/>

<xs:attribute name="Type" type="PropertyType" use="required" />

<xs:attribute name="IsArray" type="xs:boolean" use="optional" default="false" />

<xs:attribute name="OneOf" type="xs:string" use="optional" />

<xs:attribute name="Range" type="xs:string" use="optional" />

<xs:attribute name="Default" type="xs:string" use="optional" />

</xs:complexType>

</xs:element>

</xs:sequence>

<xs:attribute name="Namespace" type="xs:string" use="required"/>

<xs:attribute name="Class" type="xs:string" use="required" />

<xs:attribute name="BaseClass" type="xs:string" use="optional" />

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:simpleType name="PropertyType">

<xs:restriction base="xs:string">

<xs:enumeration value="ITaskItem" />

<xs:enumeration value="System.Boolean" />

<xs:enumeration value="System.Byte" />

<xs:enumeration value="System.Char" />

<xs:enumeration value="System.DateTime" />

<xs:enumeration value="System.Decimal" />

<xs:enumeration value="System.Double" />

<xs:enumeration value="System.Int16" />

<xs:enumeration value="System.Int32" />

<xs:enumeration value="System.Int64" />

<xs:enumeration value="System.SByte" />

<xs:enumeration value="System.Single" />

<xs:enumeration value="System.String" />

<xs:enumeration value="System.UInt16" />

<xs:enumeration value="System.UInt32" />

<xs:enumeration value="System.UInt64" />

</xs:restriction>

</xs:simpleType>

</xs:schema>

As you can see it's quite straight forward. Each Task can have a Namespace, Class and BaseClass and each Property can have a Name, Required, Type, IsArray, OneOf, Range and Default attribute.

To make this clearer let's look at a simple example:

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

<Tasks>

</Task>

</Tasks>

Should generate a the following:

// Auto-generated Task: 3/4/2004 2:13:13 PM

namespace SampleNamespace

{

using System;

using Microsoft.Build.Framework;

using Microsoft.Build.Utilities;

public abstract class SampleClass : Microsoft.Build.Utilities.Task

{

#region Property1

private string m_Property1;

public virtual string Property1

{

get

{

return this.m_Property1;

}

set

{

this.m_Property1 = value;

}

#endregion

}

Now we have a foundation on which to work. The steps it took to get from the concept to here will be the next topic of discussion ... tomorrow (or when I get a chance).