XamlImageConverter

Installation

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" ?>
<xic:XamlImageConverter
   xmlns:xic="http://schemas.johnshope.com/XamlImageConverter/2012"
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
 
   <xic:Scene OutputPath="~/img">
      <xic:Xaml Source="Image.xaml"/>
      <xic:Snapshot Filename="Image.png" />
     
      <xic:Group Element="IconBar" OutputPath="~/img/icons">
         <xic:Snapshot Filename="bar.png" />
         <xic:Snapshot Element="rotatingIcon" Storyboard="rotation" Frames="20" Filename="animated.gif" />
      </xic:Group>
 
      <xic:Snapshot Left="0" Top="0" Width="14" Height="164" Dpi="600" Filename="page_header_lft.png" />
      <xic:Snapshot Left="14" Top="0" Width="748" Height="164" Dpi="600" Filename="page_header_ctr.png" />
 
      <xic:Set>
         <Copyright.Content>
            <Button>Chris Cavanagh &amp; johnshope.com</Button>
         </Copyright.Content>
      </xic:Set>
      <xic:Snapshot Element="Copyright" Filename="copyright_bar_element.png" />
      <xic:Reset/>
 
      <sb:Set Copyright.Content="Johnshope Software" />
      <xic:Snapshot Element="Copyright" Filename="copyright_bar_element.png" />
      <xic:Reset/>
   </xic:Scene>
 
   <xic:Scene OutputPath="~/img">
      <xic:Xaml Type="MyNamespace.Document"/>
      <xic:Snapshot Cultures="en;en-GB;fr" Element=”Page1” Filename="doc.pdf" Page=”a4” /> <!—Page 1 -->
      <xic:Snapshot Cultures="en;en-GB;fr" Element="Page2" Filename="doc.pdf" Page="1cmx5cm" />< !—Page 2 -->
   </xic:Scene>
</xic:SkinBuilder>

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 Xaml element.
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: For animated GIF’s. The storyboard chooses a xaml storyboard and the Frames specified in frames per second. In the current implementation it is not possible to create loops.
• 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 snapshot’s size.
• 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:

SkinBuilderPreCompile is for loose xaml images, that get converted before compilation, so you can use the generated images as a resource.
SkinBuilderPostCompile 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:

<system.webServer>
   <handlers>
      <add name="XamlImages" verb="*" path="*.sb.xaml" preCondition="integratedMode"
         type="XamlImageConverter.HttpHandler, XamlImageConverter,
             Version=3.1.0.0,Culture=neutral, PublicKeyToken=60c2ec984bc1bb45"/>
      <add name="XamlJpgImages" verb="*" path="*.xaml.jpg" preCondition="integratedMode"          type="XamlImageConverter.HttpHandler, XamlImageConverter,
             Version=3.1.0.0,Culture=neutral, PublicKeyToken=60c2ec984bc1bb45"/>
      <add name="XamlPngImages" verb="*" path="*.xaml.png" preCondition="integratedMode"          type="XamlImageConverter.HttpHandler, XamlImageConverter,
             Version=3.1.0.0,Culture=neutral, PublicKeyToken=60c2ec984bc1bb45"/>
   </handlers>
</system.webServer>

Or IIS6:

<system.web>
   <httpHandlers>
      <add verb="*" path="*.sb.xaml, *.xaml.jpg, *.xaml.png"
         type="XamlImageConverter.HttpHandler, XamlImageConverter,
             Version=3.1.0.0,Culture=neutral, PublicKeyToken=60c2ec984bc1bb45"/>
   </httpHandlers>
</system.web>

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.sb.xaml, that’s creating an image ~/img/dummy.png you would refer to the image as ~/img/MakeImages.sb.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 *.sb.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 .

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 simply because WPF is not tested in server environments. 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:

<configSections>
   <section name="XamlImageConverter" type="XamlImageConverter.HttpHandler"/>
</configSections>
<XamlImages Log="true" />

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.

Example:

<xic:ImageMap Image="USA.Map.png" File="~/USA.Map.ascx">
   <Area Element="California" OnClientClick="alert('California was clicked...')" />
   <Area Element="NewYork" OnClick="NewYorkNeedsServerSideProcessing" />
   <Areas Elements="All;Your;IDs;Of;Your;Shape;Xaml;Or;Svg;Elements;Go;Here" OnClientClick="alert('Shape %ID% was clicked...');" />
</xic:ImageMap>

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:

<xic:Scene Source="MyImage.xaml">
   <xic:Snapshot File="MyImage.png" />
   <xic:ImageMap ID="MyMap" Image="MyImage.png" File="MyMap.aspx">
     <Areas Elements="All;Your;IDs;Go;Here" OnClientClick="alert('Shape %ID% was clicked...');" />
   </xic:ImageMap>
</xic:Scene>

And in your .aspx file you would insert a tag like this:
<asp:ImageMap ID="MyMap" runat="server" />
that would then be replaced by the computed map.

For plain html you would write in the .xic.xaml:

<xic:Map ID="MyMap" Image="MyImage.png" File="MyMap.aspx">
   <Areas Elements="All;Your;IDs;Go;Here" onclick="alert('Shape %ID% was clicked...');" />
</xic:Map>

and in the .aspx:
<map name="MyMap" />

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.