<< Tend to the Trolls or just ignore them? | Home | How to fix a frozen Zune and other interesting tips. >>

How to escape the ampersand in WiX and MSI UI.

Someone asked recently how to use an ampersand (&) in the Product Name for their .wxs file.  Probably something like:

<Product Name="Stuff & Stuff Demo" ...

The error message itself is pretty brutal but does pinpoint (to the exact character) the problem:

stuff.wxs(3) : error CNDL0104 : Not a valid source file; detail: An error
occurred while parsing EntityName. Line 3, position 27.

The error message is coming from the XML parser (we currently don't try to trap those and print out friendlier error messages, not sure that is even possible) telling you that the the "entity" (things that start with an ampersand) name is invalid. The trick is to realize that ampersands are special characters in XML. Fortunately, this fact is pretty well documented all over the Internet. So the fix is easy:

<Product Name="Stuff &amp; Stuff Demo" ...

The follow up question was how to get an ampersand to show up in the UI. The issue is that if you have something like:

<Control Text="&amp;Print" ...

The control's text is going to look like "Print". For as long as I can remember, Windows dialogs have used used an ampersand to mark the accelerator key (or is it accessibility key?) . So hopefully it is no surprise that the Windows Installer chose to follow the same convention for their dialogs. Anyway, if you really wanted "&Print" to be the text of the control then you'd need to escape the ampersand like:

<Control Text="&amp;&amp;Print" ...

This is one of those cases where the special characters in one language (XML) also used represent special characters another language (MSI UI) end up complicating the escaping across the board. Fortunately, this doesn't happen too often (and isn't nearly as ugly as the escaping of XSL in Formatted text fields).

 

posted @ Monday, April 21, 2008 9:50 AM

Print

Comments on this entry:

 re: How to escape the ampersand in WiX and MSI UI.

Left by Roger at 4/21/2008 10:17 AM

I've posted this question on the WiX-users mailing list, but here it goes.

I see that you can show the ampersand in the product name by using one &amp;, but in the CancelDlg it would show an underscored space since the ampersand in ProductName was marked it as the accelerator key.

Now, you "could" put two &amp; to correctly show the ampersand in dialog controls, but then ProductName in the title bar would show 2 ampersands.

I'm not sure how I can get around it...

 re: How to escape the ampersand in WiX and MSI UI.

Left by Anonymous at 4/21/2008 11:12 AM

Wouldn't this be a non-issue if WiX just had a visual designer to facilate the data entry? Other tools such as InstallShield and WiXAware save their projects in XML format and this escaping is handled automatically for the developer. The only time one is aware of it is when diffing the SCC versions.

# re: How to escape the ampersand in WiX and MSI UI.

Left by Rob Mensching at 4/21/2008 3:38 PM

Roger, that is amusing. I was not aware that the Windows Installer resolved properties then evaulated the accelerator keys. I suppose that works out in one's favor sometimes.

Anyway, one way to work around this is to brute force replace the ProductName property anywhere it shows up in a control's text. Or, I suppose you could just create a ProductNameSafeForUI property (or some such) and double encode the name there. Or you could change the product's name to not contain an ampersand (but that might be harder than the rest <smile/>).

# re: How to escape the ampersand in WiX and MSI UI.

Left by Rob Mensching at 4/21/2008 3:40 PM

Anonymous, you are correct that visual designers should take care of escaping the data in the source file.

# re: How to escape the ampersand in WiX and MSI UI.

Left by Mike Dimmick at 4/22/2008 2:11 AM

All Text controls that aren't actually intended to be used as the accelerator for a following control - such as an edit box, a list box or whatever - should have the msidbControlAttributesNoPrefix attribute set. That stops the accelerator-key behaviour and outputs your &s. The standard WiX dialogs should be updated to apply this flag (Control/@NoPrefix="Yes") on all Text controls except where the accelerator behaviour is actually required.

It's a source of continual frustration that the Windows default is to enable this feature when it's so rarely needed. The .NET Compact Framework team were idiotic enough to leave out Label.UseMnemonic which means you can't turn it off on that platform. Not helpful when you want to databind a Label control. I reported it as a bug and it got closed as 'By Design'.

# re: How to escape the ampersand in WiX and MSI UI.

Left by Roger Lipscombe at 4/22/2008 2:53 AM

You can use a single &amp; if you use the NoPrefix attribute on <Control>. This is equivalent to the SS_NOPREFIX style in Win32.

 re: How to escape the ampersand in WiX and MSI UI.

Left by Roger at 4/22/2008 8:27 AM

Good to know the NoPrefix attribute as well as the suggestions made by Rob, but for some default dialogs like Canceldlg, unless the whole thing is replaced, I can't really do anything about it, right?

Another interesting thing that I saw, the references to [ProductName] in some of the "bigger" dialogs such as WelcomeDlg and ExitDlg are shown correctly, so I guess NoPrefix is set in those text controls. But not in CancelDlg. Would this be a bug, in WiX or the Windows Installer itself?

# re: How to escape the ampersand in WiX and MSI UI.

Left by Rob Mensching at 4/22/2008 10:05 AM

Great suggestion, Mike and Roger L. I totally forgot about the suppression option.

Roger, let's first assume the bug is in the standard WiX UI. More likely than not we just missed a few controls with that attribute.

Your comment:



 (will not be displayed)


 
 
 
Please add 8 and 7 and type the answer here:
 

Live Comment Preview: