Xaml Image Converter Manual
Run the XamlImageconverter.vsix to install the xaml image converter. All files will be installed in the extensions path of your VisualStudio Installation, i.e. ..\VisualStudioInstallationFolder\Common7\IDE\Extensions
If you want to install the sourcecode, install Git and clone the repository you find on
http://xamlimageconverter.codeplex.com/SourceControl/list/changesets or just
download the source from the same link.
Image Converter Batch files
Normally you tell the converter what to do through a xaml batch file with the extension xic.xaml.
To create a new batch file, right click your project and choose Add > New Item... . Next select the Category
General and there you can see an Item called XamlImageConverter Image Conversion. Choose that and give the batch a meaningful name.
The ItemWizard adds an additional import to your project file, needed for building XamlImageConverter batch files. It also makes changes to your web.config (the old web.config is backed up), like registering
the HttpHandler, and registering the xic tagPrefix for use within you aspx pages.
Such a batch file could look like this:
<?xml version="1.0" encoding="utf-8" ?>
Frames="20" Filename="animated.gif" />
Dpi="600" Filename="page_header_lft.png" />
Dpi="600" Filename="page_header_ctr.png" />
Cavanagh & johnshope.com</Button>
/> <!—Page 1 -->
Page="1cmx5cm" />< !—Page 2 -->
If you import the MSBuild target into a VisualStudio Project file (see below), you get intellisense in a batch file.
For each xaml file you want to convert you must specify a Scene element. Each Scene contains a single
Xaml Source, that can be a file, a class or direct xaml in the batch file. You can Specify files through the
Source or File Attribute. If you reference a class you specify the type of the class in the
Type attribute. Optionally you can also specify an assembly with the
Assembly attribute, or you can specify the assembly in the type name in the
Type attribute. You can also directly specify the Xaml as a child element of the
As a shortcut you can also omit the
Xaml element and specify the corresponding attributes directly in the Scene element.
For each Scene you can define many Snapshots. You also can Group the Snapshots with a
Group Element, where you can define a common OutputPath or a xaml
Element, that all Snapshots should be children of. For the Snapshots there are the following attributes:
- Filename or File: The name and filetype of the image file to create. Supported types are png, gif, jpg, jpeg, bmp, tif, tiff, wdp, pdf, xps.
- Element: The xaml element to take a snapshot of.
- Left, Top, Right, Bottom, Width,
Height: The image position relative to the Scene’s root Element, the Group’s Element or the Snapshot’s Element of the snapshot to take.
- Dpi: The final dots per inch of the output for raster images.
- Storyboard, Frames & Loop: For animated GIF’s. The storyboard chooses a xaml storyboard and the Frames specified in frames per second. If you specify Loop="1" you create a looping animated GIF.
- Page: For pdf & xps documents. Specifies the page size, either a name as “a4” or “letter” or a size as “10cmx20cm” or “13inx3in”. If you omit the page size, the document’s size will be the
- FitToPage: For pdf & xps documents. If you specify the argument FitToPage=”true” the image will be resized so it fit’s to the page.
- For pdf & xps documents you can create multiple pages by just creating multiple snapshots that refer to the same file.
You can dynamically change the content of the xaml through the
Set element. With Set you can either specify an attribute that refers to an
Element.Attribute, like Button1.Text, or you can specify a child element of the form <Element.Attribute> with child xaml elements you want to assign to that attribute. You can revert the changes made with
Set with the Reset or Undo element, where Undo reverts the last
Set command and Reset reverts all Set commands.
You can create culture specific images if you use compiled localized xaml. You can specify the Cultures attribute where you can specify one or more comma or semicolon separated cultures. The xaml is then converted
with those cultures, to images with names ending on image.culure.imagetype, i.e. with a filename of apple.png and a
Culture attribute of “en;en-GB;de” the files apple.en.png, apple.en-GB.png and apple.de.png are generated.
You can set the Build Action of the xic.xaml, to one of the following values:
XamlImageConverterPreCompile is for loose xaml images, that get converted before compilation, so you can use the generated images as a resource.
XamlImageConverterPostCompile is for compiled xaml images, so the xaml files get compiled and coverted afterwards.
Setting up a VisualStudio Project for using the Xaml Image Converter
Normaly the Project is setup automatically when you create a XamlImageConverter Image Conversion Item in your project.
For intellisense support you might want to reference the XamlImageConverter.dll
in your project. You can find that dll in the installation folder.
Setting up a ASP.NET Site to use the Xaml Image Converter Handler
In order to use the Xaml Image Converter Handler, copy the XamlIamgeConverter.dll and the
gxps and psd2xaml folders from the XamlImageConverter installation folder to your bin folder. Next include the handler in your
web.config like this:
For IIS7 & IIS8:
The first entry is a xaml handler for a converter batch file. You can reference the images of such a batch file from your ASP.NET code like this:
If you have a batch file ~/img/MakeImages.xic.xaml, that’s creating an image ~/img/dummy.png you would refer to the image as ~/img/MakeImages.xic.xaml?image=~/img/dummy.png
If your browser request an url like this the first time, the handler executes the batch file and generates all files. Subsequent calls will only create those files anew that are older than the batch file. The hander
will also create a *.xic.xaml.log file with the details of the conversion.
The next entries are for direct conversions of loose xaml files. You must specify an entry for each image type you want to support. The image type is of the form *.xaml.??? where ??? is your image file type. For
supported types see above under Snapshot attributes. Also, here a log file with the conversion details is created. You can refer to those images directly by their name, i.e. if you have a xaml file ~/img/apple.xaml you can refer to it as ~/img/apple.xaml.png.
The same also works for SVG & PSD files, e.g. test.psd.png would render a Photoshop file test.psd as the PNG file test.psd.png, if you configured an appropriate HttpHandler for the path .psd.png . Be aware tough, that the Photoshop converter is rather
limited, and cannot convert every file. Also the SVG converter has some bugs in resolving fonts.
Note that the current version of the ASP.NET handler does support 3D xaml objects only in IIS6 and not in IIS7. This is due to WPF not working correctly under IIS7, and is because IIS7 runs in user session 0 that
has no display drivers loaded. convert.exe can also be run as a Windows Service, so the ASP.NET Pages will use the Service to convert images, but unfortunately it still has the same issues as when converting under IIS7.
There are some further settings you can configure, in the
web.config in the root configuration section:
Here you can choose if the XamlImageHandler should generate a log file or not.
Generating Html Image Maps
Finally it is also possible to generate html image maps from visual shapes of xaml elements or svg paths with the
ImageMap or Map element.
The ImageMap or Map element can generate a map inside a .html, .aspx, .cshtml etc. file or a UserControl .ascx file or include file containing the image map. Whereas the
ImageMap creates an asp:ImageMap element, the Map creates a standard html map element.
The ImageMap or Map has the following parameters:
- Image: The filename of the Image to determine the Snapshot's parameters which created the image.
- File: The filename of the html file, UserControl or include file to generate.
- Scale: The Zooming Scale to apply to the map's area's coordinates.
- Dpi: The dpi value of the image. Usually this value is determined from the Snapshot that created the image.
- Flatness: The quality of the polygon approximation for Bezier and arc curves.
- Type: Either AspNet (default for ImageMap) or Html (default for Map).
- FileType: Either UserControl, IncludeFile or Insert.
- Ident: Either Tab(default) or Space for the indentation characters used. If Space is used and
FileType is not Insert, 2 spaces are used for indentation.
Type and FileType are set by the created file type by default. For .aspx files the defaults are Type="AspNet" and FileType="Insert", for .ascx, Type="AspNet" and FileType="UserControl", for all others
Type="Html" and FileType="Insert".
All the other attributes you specify to the ImageMap are applied to the generated asp:ImageMap or map element, or to the UserControl, if it is a parameter that applies to UserControls and a UserControl is generated.
The ImageMap can contain area or areas tags or the ASP HotSpot tags. You can specify tags that are copied unchanged to the generated map or you can specify Area elements that have a property Element, so the shape and coordinates for the generated
area or HotSpot tag are calculated from the visual shape of the xaml or svg element. The placeholder %ID% in the area's attributes is replaced by the x:Name or SVG id of the corresponding shape element.
OnClientClick="alert('California was clicked...')" />
OnClientClick="alert('Shape %ID% was clicked...');" />
When the FileType is set to Insert, the destination file is searched for a <map>or <asp:ImageMap> tag with the same ID as specified in the xic.xaml file, and the tag is replaced with the computed tag. So to insert a html map in
a file called "MyMap.aspx" you would create a xic.xaml like this:
OnClientClick="alert('Shape %ID% was clicked...');" />
And in your .aspx file you would insert a tag like this:
that would then be replaced by the computed map.
For plain html you would write in the .xic.xaml:
onclick="alert('Shape %ID% was clicked...');" />
and in the .aspx:
You can also specify Elements="*" in the map to create areas for all named elements.
Command line version of the converter
In the installation path is also a command line version of the converter, though most of the time you will use msbuild with the msbuild tasks. The command line program is called
convert.exe. Note that the exe requires the XamlImageConverter.dll. For pdf support it requires also the gxps folder and for Photoshop support the folder
psd2xaml is required.
Contribute to the Code
If you’re a Web Designer and Programmer and use Xaml Image Converter, and it lacks a feature you need don’t hesitate to improve it. There are many useful possible extensions:
- Fix of SVG font selection bug.
- Automatic conversion of Expression Design & Illustrator files to Xaml and then to images.