Image Library Viewer

Applies to: Visual Studio Visual Studio for Mac

The Visual Studio Image Library Viewer tool can load and search image manifests, allowing the user to manipulate them in the same way Visual Studio would. The user can alter background, sizes, DPI, high contrast, and other settings. The tool also displays loading information for each image manifest and displays source information for each image in the image manifest. This tool is useful for:

1. Diagnosing errors

2. Ensuring attributes are set correctly in custom image manifests

3. Searching for images in the Visual Studio Image Catalog so that a Visual Studio extension can use images that fit the style of Visual Studio

   

   Image moniker

   An image moniker (or moniker for short) is a GUID:ID pair that uniquely identifies an image asset or image list asset in the Image Library.

   Image manifest files

   Image manifest (.imagemanifest) files are XML files that define a set of image assets, the monikers that represent those assets, and the real image or images that represent each asset. Image manifests can define standalone images or image lists for legacy UI support. Additionally, there are attributes that can be set either on the asset or on the individual images behind each asset to change when and how those assets are displayed.

   Image manifest schema

   A complete image manifest looks like this:

<ImageManifest>
      <!-- zero or one Symbols elements -->
      <Symbols>
        <!-- zero or more Guid, ID, or String elements -->
      </Symbols>
      <!-- zero or one Images elements -->
      <Images>
        <!-- zero or more Image elements -->
      </Images>
      <!-- zero or one ImageLists elements -->
      <ImageLists>
        <!-- zero or more ImageList elements -->
      </ImageLists>
</ImageManifest>

Symbols

As a readability and maintenance aid, the image manifest can use symbols for attribute values. Symbols are defined like this:

<Symbols>
      <Import Manifest="manifest" />
      <Guid Name="ShellCommandGuid" Value="8ee4f65d-bab4-4cde-b8e7-ac412abbda8a" />
      <ID Name="cmdidSaveAll" Value="1000" />
      <String Name="AssemblyName" Value="Microsoft.VisualStudio.Shell.UI.Internal" />
</Symbols>

Symbols are case-sensitive, and referenced using $(symbol-name) syntax:

<Image Guid="$(ShellCommandGuid)" ID="$(cmdidSaveAll)" >
      <Source Uri="/$(AssemblyName);Component/Resources/image.xaml" />
</Image>

Some symbols are predefined for all manifests. These can be used in the Uri attribute of the <Source> or <Import> element to reference paths on the local machine.

Image

The <Image> element defines an image that can be referenced by a moniker. The GUID and ID taken together form the image moniker. The moniker for the image must be unique across the entire image library. If more than one image has a given moniker, the first one encountered while building the library is the one that is retained.

It must contain at least one source. Although size-neutral sources will give the best results across a broad range of sizes, they are not required. If the service is asked for an image of a size not defined in the <Image> element and there is no size-neutral source, the service will choose the best size-specific source and scale it to the requested size.

<Image Guid="guid" ID="int" AllowColorInversion="true/false">
      <Source ... />
      <!-- optional additional Source elements -->
</Image>

Source

The <Source> element defines a single image source asset (XAML and PNG).

<Source Uri="uri" Background="background">
      <!-- optional NativeResource element -->
 </Source>

A <Source> element can have exactly one of the following optional subelements:

A <Source> element can also have an optional <NativeResource> subelement, which defines a <Source> that is loaded from a native assembly rather than a managed assembly.

<NativeResource Type="type" ID="int" />

ImageList

The <ImageList> element defines a collection of images that can be returned in a single strip. The strip is built on demand, as needed.

<ImageList>
      <ContainedImage Guid="guid" ID="int" External="true/false" />
      <!-- optional additional ContainedImage elements -->
 </ImageList>

The moniker for the contained image does not have to reference an image defined in the current manifest. If the contained image cannot be found in the image library, a blank placeholder image will be used in its place.

How to use the tool

Validating a custom image manifest

To create a custom manifest, we recommend that you use the ManifestFromResources tool to autogenerate the manifest. To validate the custom manifest, launch the Image Library Viewer and select File > Set Paths... to open the Search Directories dialog. The tool will use the search directories to load image manifests, but it will also use it them to find the .dll files that contain the images in a manifest, so make sure to include both the manifest and DLL directories in this dialog.

Click Add... to select new search directories to search for manifests and their corresponding DLLs. The tool will remember these search directories, and they can be turned on or off by checking or unchecking a directory.

By default, the tool will attempt to find the Visual Studio install directory and add those directories to the search directories list. You can manually add directories the tool doesn't find.

Once all the manifests are loaded, the tool can be used to toggle background colors, DPI, high contrast, or grayscaling for the images so that a user can visually inspect image assets to verify they are being rendered correctly for various settings.

The background color can be set to Light, Dark, or a custom value. Selecting "Custom Color" will open a color selection dialog and add that custom color to the bottom of the background combo box for easy recall later.

Selecting an image moniker displays the information for each real image behind that moniker in the Image Details pane on the right. The pane also allows users to copy a moniker by name or by raw GUID:ID value.

The information displayed for each image source includes what kind of background to display it on, whether it can be themed or supports High Contrast, what sizes it's valid for or whether it's size-neutral, and whether the image comes from a native assembly.

When validating an image manifest, we recommend that you deploy the manifest and image DLL in their real-world locations. This will verify that any relative paths are working correctly and that the image library can find and load the manifest and image DLL.

Searching for image catalog KnownMonikers

To better match Visual Studio styling, a Visual Studio extension can use images in the Visual Studio Image Catalog rather than creating and using its own. This has the benefit of not having to maintain those images, and guarantees that the image will have a high-DPI backing image so it should look correct in all DPI settings that Visual Studio supports.

The image library viewer allows a manifest to be searched so that a user can find the moniker that represents an image asset and use that moniker in code. To search for images, enter the desired search term in the search box and press Enter. The status bar at the bottom will display how many matches were found out of the total images in all of the manifests.

When searching for image monikers in existing manifests, we recommend that you search for and use only the Visual Studio Image Catalog's monikers, other intentionally publicly accessible monikers, or your own custom monikers. If you use nonpublic monikers, custom UI might be broken or have its images changed in unexpected ways if or when those nonpublic monikers and images are changed or updated.

Additionally, searching by GUID is possible. This type of search is useful for filtering down the list to a single manifest, or single subsection of a manifest if that manifest contains multiple GUIDs.

Finally, searching by ID is possible as well.

Notes

• By default, the tool will pull in several image manifests present in the Visual Studio install directory. The only one that has publicly consumable monikers is the Microsoft.VisualStudio.ImageCatalog manifest. GUID: ae27a6b0-e345-4288-96df-5eaf394ee369 (do not override this GUID in a custom manifest) Type: KnownMonikers

• The tool attempts on launch to load all image manifests it finds, so it might take several seconds for the application to actually appear. It might also be slow or nonresponsive while loading the manifests.

Sample Output

This tool does not generate any output.