0 out of 4 rated this helpful - Rate this topic

Image.Source property

[This documentation is preliminary and is subject to change.]

Gets or sets the source for the image.

Syntax

Copy


public ImageSource Source { get; set; }

XAML Attribute Usage

Copy


<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 BitmapSource object, constructed with the URI that describes the path to a valid image source file.

Remarks

When you set this property in XAML, you can set the URI of the image source file for the Image directly as a string. 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.

When you set this property in code, you are not setting a URI directly. The property type for this property is ImageSource. ImageSource is an abstract type. In most cases the practical type that you want to create as the Source property value is a BitmapSource. Create a new BitmapSource using the BitmapSource(Uri) constructor. Windows Runtime enforces that URIs be absolute. How you construct the URI will vary, depending on how and where you package the image source file within your app.

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 VB, use Uri(Uri,String). In C++ 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 any pathing that is part of the XAML page's location in app package structure.
You can reference an image source file that is not packaged with your app. For example you can reference image source files on the Web using "http:" scheme URIs. In this case, 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.
You can access image source files that are placed in your app's local storage, using a "ms-appdata:" scheme URI.

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.

Requirements