Quickstart: Using file or image resources (XAML)

  • Article

You can add images and other file resources to your app, and reference those files from within your app. Support for swapping images based on high contrast settings or display scaling is built in, if you follow the instructions below for naming and organizing your file resources in folders.

Instructions

  1. Create tailored images or other file assets for different scales (dpi) and contrast settings.

    Create your images at several recommended sizes, to ensure that your app looks great when Windows scales it. See the guidelines for scaling to pixel density.

    1. Create multiple copies of each image:

      1. Original size, for a typical 96dpi device.
      2. 140% the original size. For example, a 100x100px image should also have a 140x140px image version.
      3. 180% the original size. For example, a 100x100px image should also have a 180x180px image version.
      4. 240% the original size, for Windows Phone apps. For example, a 100x100px image should also have a 240x240px image version.
      5. For the logo, wideLogo, and smallLogo resources specified in the app's manifest file, 80% of the original size. For example, a 100x100px image should also have an 80x80px image version. See App images and Tile image sizes.
      6. High contrast image with a black background and white foreground at the original size.
      7. High contrast image with a white background and black foreground at the original size.

    2. Name the images with qualifiers for the various scales and contrast settings:

      1. name.scale-100.ext
      2. name.scale-140.ext
      3. name.scale-180.ext
      4. name.scale-240.ext
      5. name.scale-80.ext (For the logo, wideLogo, and smallLogo resources)
      6. name.scale-100_contrast-black.ext
      7. name.scale-100_contrast-white.ext

      In this example, name.ext is the name of the image as referenced in code and markup.

    3. Place the images side by side in the same folder. For example:

      1. images/logo.scale-100.png
      2. images/logo.scale-140.png
      3. images/logo.scale-180.png
      4. images/logo.scale-240.png
      5. images/logo.scale-80.png
      6. images/logo.scale-100_contrast-black.png
      7. images/logo.scale-100_contrast-white.png

  2. Refer to the images in XAML without the qualifiers.

    <Image Source="images/logo.png" />

  3. Refer to the images in code without the qualifiers.

    var uri = new System.Uri("ms-appx:///images/logo.png");
var file = Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

  4. Refer to the image in the manifest without the qualifiers.

    1. Open the Package.appxmanifest file in Microsoft Visual Studio.

    2. Edit the manifest reference to refer to the file in the correct element or attribute, such as:

      Logo:   images\logo.png

Some images or other files may need to be localized, particularly when they contain text or culturally sensitive material. Files can also vary depending on a user's location, separate from their language. For example, a map may have different borders depending on the user's location, but the labels should follow the user's preferred language.

Files can be marked or qualified with basic folder and file name conventions for all different user and device configurations. See How to name resources using qualifiers for more details on qualifying resources, and for a list of qualifiers.

How to name resources using qualifiers

App images

Guidelines for scaling to pixel density

Tile image sizes

Roadmap for creating apps using C#, C++, or VB