ImageBrush.ImageSource property

Gets or sets the image displayed by this ImageBrush.

Syntax

public ImageSource ImageSource { get; set; }

<ImageBrush ImageSource="imageUri"/>

XAML Values

imageUri

A URI that references an image file.

Property value

Type: ImageSource

The image displayed by this ImageBrush.

Remarks

Setting an image source is inherently an asynchronous action. Setting the source to a Uniform Resource Identifier (URI) value that cannot be resolved to a valid image source file does not throw an error. Instead, it fires an ImageFailed event on the ImageBrush. If you want to verify that an image source file did load correctly, you can handle ImageOpened.

Setting ImageSource in XAML

You can set this property in XAML, but in this case you are setting the ImageSource property as a URI. This behavior relies on underlying type conversion that processes the string as a URI, and calls the equivalent of the BitmapImage(Uri) constructor.

The ImageFailed event can occur if the initial ImageSource attribute value in XAML does not specify a valid source. You can use a relative path to reference an image that you package with the app, or an absolute URI to reference an image from a server. If you are using an image source from your app, it's common to use either the ms-appx or ms-resource schemes.

Setting ImageSource in code

If you define an ImageBrush using code, ImageBrush.ImageSource requires a BitmapImage (not a URI) in code. If your source is a stream, use the SetSourceAsync method to initialize the value. If your source is a URI, which includes content in your app that uses the ms-appx or ms-resource schemes, use the BitmapImage constructor that takes a URI. You might also consider handling the ImageOpened event if there are any timing issues with retrieving or decoding the image source, where you might need alternate content to display until the image source is available. See XAML images sample for example code.

Note  You can use automatic handling for accessing unqualified resources with current scale and culture qualifiers, or you can use ResourceManager and ResourceMap with qualifiers for culture and scale to obtain the resources directly. For more info see Resource management system.

Image sources and scaling

You should create your image sources at several recommended sizes, to ensure that your app looks great when Windows 8 scales it. When specifying an ImageSource for an ImageBrush, you can use a naming convention that will automatically reference the correct resource for the current scaling. For specifics of the naming convention and more info, see Quickstart: Using file or image resources.

For more info on how to design for scaling, see Guidelines for scaling to pixel density.

For more info on app resources and how to package image sources in an app, see Defining app resources.

Requirements

See also

ImageBrush

Image

Quickstart: Image and ImageBrush

Build date: 12/4/2012