ImageBrush.ImageSource Property

Definition

Namespace:

Microsoft.UI.Xaml.Media

Gets or sets the image source displayed by this ImageBrush. In code you set this with an ImageSource subclass instance, in XAML you set this with a URI to an image source file.

public:
 property ImageSource ^ ImageSource { ImageSource ^ get(); void set(ImageSource ^ value); };

ImageSource ImageSource();

void ImageSource(ImageSource value);

public ImageSource ImageSource { get; set; }

var imageSource = imageBrush.imageSource;
imageBrush.imageSource = imageSource;

Public Property ImageSource As ImageSource

<ImageBrush ImageSource="imageUri"/>

Property Value

ImageSource

An object representing the image source, to be displayed by this ImageBrush when it's applied to content.

Remarks

Setting an image source from an image source file or stream 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 for verification, plus ImageFailed as a way to provide a fallback image source or recompose your UI.

Setting ImageSource in XAML

You can set this property in XAML, but in this case you are setting the ImageSource attribute value as a string representing a Uniform Resource Identifier (URI). This behavior relies on underlying type conversion that processes the string as a Uniform Resource Identifier (URI), and calls the internal 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 Uniform Resource Identifier (URI) to reference an image from a server. If you are using an image source that's packaged as part of 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 Uniform Resource Identifier (URI)) in code. If your source is a stream, use the SetSourceAsync method to initialize the value. If your source is a Uniform Resource Identifier (URI) referencing a file, which includes content in your app that uses the ms-appx or ms-resource schemes, use the BitmapImage constructor that takes a Uniform Resource Identifier (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.

If you need to compose a URI in relation to another object in the UI to help scope the resource request, you can sometimes use the FrameworkElement.BaseUri property as called on another object in the UI. This provides a base URI that is where the XAML page comes from within the app's project structure.

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 UX guidelines for layout and scaling.

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

See also

• BitmapImage(Uri)
• Image
• Image and ImageBrush