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

// Tales from software development

Archive for July 2009

Sandcastle Help File Builder error BE0035

leave a comment »

A build should be as self-contained as possible and ideally contains all the tools required without having any dependencies on whether the tools are actually installed on the computer the build is running on.

Sandcastle and Sandcastle Help File Builder have proved to be tricky in this respect but a few days ago I made a concerted effort to nail down all the little gotchas that usually result in me giving up and just installing them on whatever computer I’m trying run a build on.

Sandcastle uses an environment variable called DXROOT to identify where it’s located. Similarly, the latest version of Sandcastle Help File Builder uses a variable called SHFBROOT. Sandcastle Help File Builder used to ship with a command line tool that could be called from a build but this has changed in the latest version. Instead an MSBuild project file is used to perform the build of the documentation.

This leads to a chicken and egg situation as regards trying to configure the location of Sandcastle Help File Builder in the build properties and I gave up and just set it as a relative path in the batch file used to invoke the build. Not ideal but I couldn’t see a way around that.

I thought I’d finally got a portable configuration but when I copied the build over to a build machine that didn’t have anything related to the build already installed it failed with this:

SHFB : error BE0035: Could not find the path to the Microsoft Sandcastle documentation compiler tools.  See error topic in help file for details.

Sandcastle Help File Builder’s help file indicates that this is a problem with DXROOT not being set to the location where Sandcastle can be found but I knew that I did have it set – to the build’s local copy of Sandcastle. I remembered hitting this problem before and conceding defeat but this time I was going to sort it out once and for all.

It took 30 minutes of experimentation to realise what the problem really is. Sandcastle Help File Builder is simply not using the DXROOT variable at all. In the abscence of an explicit path in the Sandcastle Help File Builder project file it simply looks in C:\Program Files\Sandcastle.

The solution is to set the value in the project file specifying the DXROOT variable as an MSBuild property:

<SandcastlePath>$(DXROOT)</SandcastlePath>

Unfortunately, this must be done using a text editor rather than the Sandcastle Help File Builder GUI tool because it insists on adding a trailing ‘\’ which makes the path invalid as the DXROOT variable usually has a trailing slash already.

Once this is done both Sandcastle and Sandcastle Help File Builder will run successfully without having to be installed.

Written by Sea Monkey

July 14, 2009 at 8:00 pm

Posted in MSBuild

Tagged with

What does a blank screen on a KVM-over-IP connection mean ?

leave a comment »

The project I’m working on at the moment is to implement an application that will run on our client’s secure network. The agreement that allows us to access the network requires that we use a single stand-alone computer that must not be attached to any other network. 

This has turned out to be a nuisance because it means that you have to physically be at the computer to use it. Even within our offices this often isn’t very convenient but its a much bigger problem when most of the company’s developers, like me, are working at other locations.

Our solution was to use a KVM-over-IP extender attached directly to the computer. An extender is usually used to enable a KVM to be accessed over an IP network but there’s no reason why you can’t use one to remotely control a single computer rather that the keyboard, mouse, and monitor input ports of a KVM. The extender is attached to the office LAN and we can access it remotely by connecting to the company’s VPN. (Just to be clear – we are controlling the computer remotely but it is not attached to any network except the client’s secure network.)

After successfully accessing the computer remotely via the VPN and KVM extender last week, I was disappointed to find that it didn’t seem to be working when I logged in on Monday morning. The symptoms were a bit strange: the login to the VPN was successful and I successfully logged in to the KVM extender but all I saw was a black screen that didn’t respond to the keyboard or mouse.

Blank screen

I spent a few minutes repeatedly pressing the Windows key, trying CTRL-ALT-DEL key sequences, etc., but without any success. After 10 minutes I decided that I’d have to call the office and ask someone to reboot the computer because I couldn’t get any response from it. I called but got no response so I emailed my coleagues to ask if someone in the office could reboot the computer.

A few minutes later an email arrived from a developer working at home – there was no one in the office today and because of the sensitivity of the secure network connected computer, the last person to leave the office on Friday had turned it off. So, the reason that all I could get from the KVM extender was a blank screen was because the computer it was attached to was powered down!

Written by Sea Monkey

July 9, 2009 at 8:00 pm

Posted in Environments, Hardware

Tagged with ,

Are write-only properties ever useful ?

leave a comment »

I’ve previously thought of write-only properties as a useless curiosity but in implementing an MSBuild task last week I finally found a use for them.

The build task I wrote updated the AssemblyFileVersion attribute value in a C# AssemblyInfo.cs file. The task implements properties to specify the path of the file to be updated and which part of the major.minor.build.revision style version number should be incremented. The task returns the updated version value as an output parameter. The call to the task from an MSBuild project file looks like this:

<IncrementVersion
    File=”$(VersionFile)”
    Increment=”Revision”
>
    <Output TaskParameter=”UpdatedVersion” PropertyName=”VersionString” />
</IncrementVersion>

The implementation of the task requires the input and output parameters to be defined as properties that are then decorated with MSBuild related attributes such as Required and Output. For example the File property might be implemented as:

[Required]
public string File
{
    get { return this.versionFilePath; }
    set { this.versionFilePath = value; }
}

The property set accessor is required so that the property value can be passed from the MSBuild project file to the task but is the property get accessor required ? In this example it isn’t because the task accesses the underlying private member value directly. The implementation of the property is actually the implementation of an interface to an external environment that only needs to pass a value to the task so this code is all that is required:

[Required]
public string File
{
    set { this.versionFilePath = value; }
}

I’ve finally encountered a use for write-only properties!

Note that this isn’t always true of MSBuild task parameters. Although tasks typically implement input parameters and output parameters there is no reason why a parameter shouldn’t be defined as an input and output parameter.

Written by Sea Monkey

July 7, 2009 at 8:00 pm

Posted in Development

Tagged with

What you're looking for is at the end of the book

leave a comment »

Something I noticed a long time ago but have never formalised: when you’re struggling with a technical issue and you pick up a book that you think might help you, the index entry will point you further towards the end of the book in direct proportion to your current level of knowledge of the technology and the difficulty, or obscurity, of the problem.

For example, let’s say you’re trying to load and execute an some .NET code in an AppDomain. Something that ought to be straightforward but, equally, something that not many application developers ever need to do. Your code nearly works but there’s a weird type deserialization issue that results in failure. So you pick up your favourite .NET bible and look up ‘AppDomain’ and the index says something like ‘Page 798’ and you think, “That’s weird, this index page is only page 804.” You turn to page 798 and there’s a page and a half covering the whole subject of AppDomains and you quickly realise that your knowledge and experience is already way beyond what’s covered here.

So you find a book that covers the specific subject. The title looks promising: “Everything you need to know about the CLR and AppDomains” (no, it doesn’t really exist but there are several books in print that cover the subject). You look in the index. There’s a few promising references that you check each one but they’re all references to fairly straightforward topics that you already understand. Finally, there’s one reference left. And, again, the page number is very close to the end of the book: page 478 but the book only has 485 pages including the index!  At least page 478 appears to cover the subject area that you’re having problems with but it’s just regurgitating the MSDN documentation and there’s little added value here.

I think the problem arises because most software development books are now written in advance of a product or technology being released. So the manuscript is written against a beta, or earlier, release and the author concentrates on the 80% of the subject that will be most relevant to readers wishing to get up to speed as quickly as possible. The remaining 20% is the tricky stuff that probably isn’t even implemented in the beta release or is very buggy if it is. But, of course, this is the area that we all need help with once we’ve got experience with the technology.

Written by Sea Monkey

July 5, 2009 at 2:00 pm

Posted in Comment, Development

Tagged with ,