S h o r t S t o r i e s

// Tales from software development

Archive for December 2008

StyleCop custom rules – IntProperty problem

with 3 comments

IntProperty problem

I’ve just spent a day trying to work out why a StyleCop custom rule that I’m writing was throwing exceptions in the Apply() method when I tried to save its settings using the StyleCop Settings Editor.

A System.ArgumentException was thrown whenever I tried to create a new instance of an IntProperty with the following error message:

The property container does not contain a property descriptor for the <property-name> property.

The property was correctly defined in the rules xml file, as documented in the ‘Adding Custom Rule Settings’ topic of the SDK help file, using an IntProperty element under the Properties element. I began to suspect that there was an error in the StyleCop framework and that it wasn’t extracting the property definition from the rules xml.

When I temporarily changed the property type to a StringProperty and reran my tests everything worked as expected. So, the StyleCop framework was correctly extracting StringProperty elements but not IntProperty elements.

IntegerProperty element

On a whim I tried coding the property using IntegerProperty as the element name. And everything worked as expected.

So, the problem is simply that the documentation is wrong. An integer property is defined in the rules xml file using an IntegerProperty element not as an IntProperty element as the SDK help file indicates.

Advertisements

Written by Sea Monkey

December 31, 2008 at 2:00 pm

Posted in Development

Tagged with

MSBuild 3.5: /toolsversion and ToolsVersion

with one comment

One of the changes between the 2.0 and 3.5 versions of the .NET Framework is the addition of the FindInList MSBuild task. A few days ago I thought I’d have a quick play with this task to see exactly what it offers.

Strangely, my build script kept failing with the following error message:

C:\temp\test.proj(14,3): error MSB4036: The "FindInList" task was not found.
Check the following:
1.) The name of the task in the project file is the same as the name of the task class.
2.) The task class is "public" and implements the Microsoft.Build.Framework.ITask interface.
3.) The task is correctly declared with <UsingTask> in the project file, or in the *.tasks
files located in the "C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727" directory.

There are two things to note. Obviously, the error indicates that the FindInList task cannot be found but the reference to version 2.0.50727 is odd. I confirmed that I was executing MSBuild from the c:\WINDOWS\Microsoft.NET\Framework\v3.5 folder instead of c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727. Having done this, I dismissed the version in the message as an error in the 3.5 version of MSBuild. 

Next, I checked that the MSBuild.Common.Targets file specified an entry for FindInFiles. It did, so then I used Reflector to check that the task was implemented and exposed as a public class in the Microsoft.Build.Tasks.v3.5.dll assembly. Finally, I changed the task reference in the build script so that it was fully qualified. The problem remained and I was running out of ideas.

On a hunch, I checked the MSBuild command line arguments. The 3.5 version of MSBuild has several new arguments including one called /toolsversion. This looked promising…

A bit of experimenting showed that even when executing MSBuild 3.5, the version 2.0 tasks library is used unless the /toolsversion argument is used to specify that the 3.5 version tasks should be used. This explains why the error message referred to the version 2.0.50727.

The /toolsversion argument is intended to override the new ToolsVersion attribute of the project’s Project element. If the ToolsVersion attribute is not specified then version 2.0 is assumed.

So, the correct way to write a version 3.5 MSBuild project file is to specify the ToolsVersion attribute:

<Project DefaultTargets = "Full" ToolsVersion="3.5" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" >

Written by Sea Monkey

December 22, 2008 at 9:00 pm

Posted in MSBuild

Tagged with

Microsoft Small Basic

leave a comment »

Last month Microsoft released Small Basic. It’s advertised as a free introductory programming tool for children but it’s difficult to understand the motives behind the release. Does the world need another dialect of BASIC ? Is BASIC the best langauge to learn programming with ? Why would Microsoft release a ‘product’ at version 0.2 with documentation that consists solely of a single PDF file with lots of ‘TODO’ placeholders ?

It’s seems a bit odd to say the least but after playing with it for a few minutes a couple of things impressed me. First, is the intellisense, is this something we’ll see in the next release Visual Studio ?

Probably not but I like it.

The second interesting feature is the interaction with the internet – there are functions for retrieving word definitions (presumably from a web service), interacting with flickr, or simply fetching web page content and files. Just when it starts sounding interesting and even useful, it quickly becomes apparent that it isn’t. For example, the flickr functionality is limited to retreiving a single image by tag or the image of the moment. It’s not possible to get a partcular image or images belonging to a particular user.

My first attempt at a Small Basic program was this single line:

TextWindow.WriteLine(Dictionary.GetDefinition(“computer”)

If you look closely, you’ll note that there is a closing bracket missing. Sure enough, this generates an error. Now, remembering that this is a learning tool for children, is this error message going to mean much to the program’s intended audience:

Sorry we found some errors
1,56 Encountered unexpected end of line parsing method call.

Hmmm, probably not. Anyway, I added the missing bracket and ran the program. This was the output:

 com·put·er (noun)
 com·put·er [ k?m py?t?r ] ( com·put·ers )

 1. electronic data processor
 an electronic device that accepts, processes, stores, and outputs data at high
speeds according to programmed instructions
 2. somebody who computes
 somebody who calculates numbers or amounts using a machine

 com·put·er·less (adjective)
 com·put·er·less See com·put·er

Not bad. My second program extended to three lines:

GraphicsWindow.Show()
pic = Flickr.GetRandomPicture(“moon”)
GraphicsWindow.DrawImage(pic, 0, 0)

And it worked first time!

It was certainly fun to play with for half an hour but I still don’t get it. What is Microsoft trying to do with this ?

Written by Sea Monkey

December 20, 2008 at 6:00 pm

Posted in Comment, General

Tagged with

Wrestling with SandCastle

leave a comment »

SandCastle

I’ve spent the past week putting together a general purpose build for .NET 2.0 and 3.5 projects. Because the NDoc project appears to have ground to a halt I decided to use Microsoft’s SandCastle instead to generate documentation in the build.

SandCastle is used internally at Microsoft and was used to generate the .NET Framework 3.5 documentation. So, I was expecting a mature and robust tool. After struggling with it and making very little progress other than to find one bug after another I conceded defeat. There had to be an easier way…

I searched the SandCastle related forums and blogs and quickly found myself agreeing with the guy who posted the comment “…this is insanely complicated…” on the CodePlex site. However, the fact that there are several tools available that act as a front end to SandCastle gave me hope. To paraphrase another poster’s comments, SandCastle is better thought of as being the infrastructure for generating documention and an NDoc-type tool is still needed to use it.

First I tried using some of the batch file and build script tools that claim to make using SandCastle easy. I found that most were out of date as they are based on early CTP versions of SandCastle and no longer work with the latest (May 2008) release. The ones that did appear to have been updated to work with the current release usually failed when they encountered the same bugs that I’d already encountered when using SandCastle directly.

SandCastle Help File Builder

Finally, I decided to try Eric Woodruff’s SandCastle Help File Builder tool. Thank goodness there’s someone who fully understands SandCastle because Eric clearly does and he’s produced a tool that exposes all of the power and functionality of SandCastle through an easy to use UI. He’s also understood the need to incorporate this functionality into build scripts and has included a command line utility to build SandCastle Help File Builder projects.

Eric has also found ways of working around the known bugs in the current SandCastle release and the issues that I found when using SandCastle directly have simply disappeared.

MTPS Content Service

One of the irritations mentioned by SandCastle users is the fact that SandCastle attempts to access a Microsoft web service and fails if it cannot. A little bit of investigation shows that this is because, by default, SandCastle uses the MTPS Content Service. This service exposes navigation links for MSDN content. Presumably, this feature is on by default because SandCastle was developed at Microsoft to generate MSDN documentation.

Thankfully, not only can this behaviour be changed but SandCastle Help File Builder makes it easy to do this. Under the Help File section of the Project Properties window there are two properties that control how content links are generated: SdkLinkTarget and SdkLinkType

The SdkLinkTarget property specifies how the linked content is displayed in the same way as the target attribute of an HTML anchor.

The SdkLinkType property defines the type of link to be used. The default value, Msdn, causes SandCastle to access the MTPS web service to get the navigation link for an MSDN topic. Changing the value to Index or None stops this.

Documenting Namespaces

One other issue to note is that SandCastle can generate NameSpace comments but there is no support for this in Visual Studio’s  XML Comments system and so NameSpace comments must be supplied to SandCastle. Again, SandCastle Help Builder has this covered.

At the top right of the UI you’ll see a group of buttons. The Prj Summary and Namespaces buttons allow you to provide comments for the project and the namespaces.

Resources

SandCastle 2.4.10520 (Microsoft Download Center)

SandCastle (CodePlex)

SandCastle Help File Builder (CodePlex)

 

Written by Sea Monkey

December 16, 2008 at 9:00 pm

Posted in Development

Tagged with

Using the XSD Inference and XSD Object Code Generator tools

with one comment

I’ve been using these two tools to generate C# class code for serializable data for the past few years. It surprises me that some of my colleagues spend time hand coding data schemas. Maybe I’m just lazy…

XSD Inference tool

The XSD Inference tool was released back in 2002 and its functionality has now been integrated into the Visual Studio IDE (2005 and later). However, it’s still useful to have the tool because it allows you to incorporate the functionality into your build process.

There’s a help file provided that documents how dataypes are inferred.

XSD Object Code Generator

The XSD Object Code Generator tool was released in 2004 and is similar to the XSD tool that ships with Visual Studio.

The documentation is a Microsoft Word file.

Using together

I use the XSD Inference tool and the XSD Object Code Generator tool to create serializable C# classes from XML files containing examples of the XML data that these classes will be used to store. I guess I am being a bit lazy but it means that I don’t have to put any effort into the XSD schemas for persistent data. I just create a representative example of the data and run the two tools to generate the C# code.

When I first started using these tools, I’d typically create a folder called XsdInference in my project folder containing the example XML data files and a batch file that ran the two tools to generate the C# classes.

The real productivity gain comes when you need to change the data schema. A quick change to the example data, run the two tools, and your C# data class now supports the new schema.

The batch file contains these commands:

SETLOCAL
REM Configure these values as required:
SET ClassName=ConfigurationData
SET Namespace=MyProject.ConfigurationData

REM Run the inference and code generator tools:
"C:\Program Files\XSDInference\bin\Infer.exe" %ClassName%.template -o "%ClassName%.generated.xsd"
"C:\Program Files\XSDObjectGenerator\XSDObjectGen.exe" "%ClassName%.generated_1.xsd" /l:cs /n:%Namespace% /f:"..\%ClassName%.cs"

REM Remove the temporary schema file:
DEL "%ClassName%.generated_1.xsd"
ENDLOCAL

Note that the schema file created by the XSD Inference tool always has a filename slightly different from that specified by the -o parameter. As can be seen in the batch file commands, when the -o parameter specifies filename.ext the tool actually generates the schema file as filename_1.ext.

Integrating with Visual Studio

I’ve made this slightly more sophisticated recently. It’s possible to run a batch file using the Pre-build event command line setting in the Build Events tab of the project properties dialog in Visual Studio. The simple solution is to execute the batch file that runs the XSD Inference tool and the XSD Object Code Generator tool.

However, this will mean that the inference and code generation tools run everytime you do a build in the IDE which is unnecessary.So, the first improvement is to run an MSBuild project file instead and use the Inputs and Outputs on a target to ensure that the tools are only executed when the example XML files have been changed.

There is another way to achieve this that provides tighter integration with the build process that Visual Studio uses. Open the .csproj file in a text editor and page down to the end of the file and you’ll see a commented out section with this text:

To modify your build process, add your task inside one of the targets below and uncomment it. 
Other similar extension points exist, see Microsoft.Common.targets.

This section can be used to call a target in your own MSBuild project. You’ll also need to code an Import statement for the project file. 

If you do this, not only will the target in your MSBuild project run each time the project is built in the Visual Studio IDE but it will have access to all the IDE’s build properties and items. As discussed in How to tell if your MSBuild project is running in Visual Studio, the BuildingInsideVisualStudio property may be used to determine if your build file is running as part of the IDE build process.

Resources

XSD Inference tool

XSD Object Code Generator tool

Written by Sea Monkey

December 5, 2008 at 9:00 pm

Posted in Development

Tagged with

How to 'touch' files with the COPY command

leave a comment »

MSBuild has a Touch task to update the date/time stamp on a file like the UNIX touch command.

A little while ago I needed a way to touch a file but I didn’t want to use MSBuild and I didn’t really want to download a third-party touch utility. I wondered if there was a way to do it using just the commands supplied with Windows. It turns out there is…

This isn’t very intuitive but the COPY command can be used like this:

copy /b filename.ext + ,,

to update a file’s date/time stamp.

It works because the arguments instruct the copy command to update the specified file by appending a file but the file is not specified. So the file is, in effect, copied to itself. In reality, all that the COPY command does is update the last modified date/time stamp.

There’s an old Microsoft KnowledgeBase article that explains this in more detail here:

http://support.microsoft.com/kb/69581

Written by Sea Monkey

December 2, 2008 at 9:53 pm

Posted in Development

Tagged with