Image.Source property

Gets or sets the source for the image.

Syntax

Public Property Source As ImageSource
   Get
   Set

<Image Source="uri"/>

XAML Values

uri

The URI location of the image source file.

Property value

Type: ImageSource

An object that represents the image source file for the drawn image. Typically you set this with a BitmapImage object, constructed with the URI that describes the path to a valid image source file.

Remarks

Setting an image source is inherently an asynchronous action. Setting the source to a 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 Image itself. You can write an ImageFailed handler and attach it to the Image to detect this case, and possibly use the ErrorMessage in event data to determine the nature of the failure. If you want to verify that an image source file did load correctly, you can handle ImageOpened.

Setting Source in XAML

You can set this property in XAML, but in this case you are setting the Source 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 XAML parser interprets any strings that represent a relative URI in the context of the XAML page that is being parsed. For example, if you specify a value "images/myimage.png" in XAML, that is interpreted as a relative path suffix that is appended to the location within the app package where the XAML page itself exists.

The ImageFailed event can occur if the initial Source 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 Source in code

If you define an Image using code, Image.Source requires a BitmapImage or BitmapSource (not a URI) in code. If your source is a stream, use the BitmapSource.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. The Windows Runtime enforces that a URIs be absolute, you can't create relative URIs in code. How you construct the URI will vary, depending on how and where you package the image source file within your app.

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.

You can reference image source files that are packaged with your app. These are typically included as Content build action as part of your app project. To avoid specifying the entire absolute URI within your app packaging, you can construct a Uri using one of the signatures that creates a URI from an absolute base and then a relative part/path. In C# or Microsoft Visual Basic, use Uri(Uri,String). In Visual C++ component extensions (C++/CX) use Uri(String,String). For the first parameter in either case, call BaseUri on the Image instance where you are setting the source. This creates a URI with the correct ms-appx scheme and adds the path that is part of the XAML page's location. For example: CapturedPhoto.Source = new BitmapImage(new Uri(this.BaseUri, "Assets/placeholder-sdk.png"));

If you're using the http scheme, use a Uri constructor that takes a string, specifying the whole string of the URI including the scheme. If you are using a .NET Framework System.Uri value, and you use a signature that requires a UriKind value, make sure to specify Absolute.

Still another option is to use image source files that are placed in your app's local storage, using the ms-appdata scheme.

You should use SetSourceAsync if you're using image source files that are only available at run-time to set an Image, for example image files you've enabled the user to choose by using a FileOpenPicker in UI.

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 a Source for an Image, 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

Image

ImageFailed

Quickstart: Image and ImageBrush

Build date: 3/12/2013