Creating Compiled Icons
The most common type of icon is the compiled icon), represented by
CompiledIconId. These icons are embedded into assembly references at compile type, as XAML resources.
The ReSharper SDK includes MSBuild build actions and a custom task that will generate icons from either XAML or PNG files. The custom task generates two files - a new XAML file containing a
DrawingBrush resource for each image, and a C# file providing the
CompiledIconId instances, and pointers to the new XAML resource dictionary. Once the files have been generated, they should both be added to the Visual Studio project.
Themed icons are supported by including multiple images in the generated XAML file, one version for each theme aspect supported. Each image is annotated with its own name and the theme aspect that it is intended for, so themed icons will have multiple images with the same name, but different theme aspect names.
When retrieving an icon, the aspects from the current theme are enumerated in priority order, and the first matching image for the icon is used. If there are no images that match any of the theme aspects, the fallback image is used, if available. A fallback image is an image that is created without a theme aspect. If there are no fallback images, an arbitrary themed image for the icon is used.
See the theming section for more details about theming and theme aspects.
XAML images are the preferred format for icons, as they scale better for larger sizes and higher screen DPI resolutions.
The input XAML file should be a
ResourceDictionary containing a number of
DrawingBrush resources, all marked with an
x:Key attribute that uniquely identifies the icon by name. The file should be added to the Visual Studio project and have its build action set to
Each brush can contain multiple individual images, one for each supported theme aspect. The images are placed horizontally, and, rather than conforming to a strict grid, the custom task will automatically discover distinct, non-overlapping images. These images are saved to the new, generated XAML file, again as a
ResourceDictionary, with each theme image being saved as its own individual
The new XAML images need to be annotated, with both the name of the icon and the name of the theme aspect it is intended for. The theme aspect is retrieved from MSBuild metadata attached to the original XAML file. The
ThemeColumns element is used to provide a semi-colon separated list of theme aspect names, one for each image in the horizontal strip, in the same order.
Similar metadata is required to specify how the background of an individual image is processed. The
RemoveBackgroundElement describes this behaviour. To all intents and purposes, there is no need to configure this, other than to set the value to
Both pieces of metadata are required, or the custom task will not process the XAML file. To add the metadata, edit the
.csproj project file, find the element that represents the original XAML file and set it as follows:
The names of the theme aspects are listed in the theming section.
ReSharper also supports using PNG files as icons, although it is recommended to use XAML instead, as XAML files can scale better to larger sizes and higher screen DPI resolutions.
In order to create an icon from a PNG file, add the file to the Visual Studio project, and set its build action to
ThemedIconPng. The PNG file will typically be square, e.g. 16×16, although there are no restrictions to enforce this - a larger icon could be included for high DPI or simply for displaying at a larger size.
Theming is supported by a naming convention. The theme aspect name should be placed in square brackets, e.g.
Foo[GrayDark].png, and a separate PNG file used for each theme aspect. If a theme aspect name isn't specified, the image is treated as a fallback image when failing to find a theme specific image.
The theme aspect names are listed in the theming section.
The custom task generates two files - a new XAML file containing the processed images, and a C# file that contains the
The filenames are based on the name of the containing folder, using the format
<DIR> is the name of the containing folder, minus any
Icons suffix. E.g. the folder
BarIcons would create files called
The generated XAML is a
ResourceDictionary where each themed image is created as an individual
DrawingBrush, annotated with the name of the icon and the theme aspect it is intended for.
The generated C# file contains
CompiledIconId instances used to identify and consume the icons. The generated classes are created inside a sealed class to prevent any clashes with other classes inside that namespace. Each class derives from the empty, abstract
CompiledIconClass class and are marked with the
[CompiledIconClass] attribute, to allow for discovery of icon XAML files at runtime. The class also declares a couple of assembly level attributes, to help with identifying and loading the icon XAML files, assigning the friendly name to the image in the XAML, and to register a XAML namespace for the icons.
Each class has a single public static field called
Id, which is the instance of
IconId that you use when consuming the icon.
Once the files have been generated for the first time, they should be added to the Visual Studio project.
Other useful metadata
The custom task also recognises the
FullPath metadata, which is useful if the icons are being linked into the Visual Studio project from another location, perhaps shared between projects. The
FullPath metadata should be the expected full path to the output location, where the generated files will be placed.