Artikel
11/18/2011

ImageBrush.ImageSource Property

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Gets or sets the image displayed by this ImageBrush.

Namespace: System.Windows.Media
Assembly: System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Property ImageSource As ImageSource

public ImageSource ImageSource { get; set; }

<ImageBrush ImageSource="imageUri"/>

XAML Values

imageUri
A URI that references an image file. See "Setting ImageSource in XAML" section in Remarks for this topic.

Property Value

Type: System.Windows.Media.ImageSource
The image displayed by this ImageBrush.

Remarks

Dependency property identifier field: ImageSourceProperty

The XAML usage for ImageSource is significantly different than the code usage. The XAML usage uses a URI whereas the code usage uses an ImageSource. See "Setting ImageSource in XAML" section of this topic.

In the JavaScript API for Silverlight, the equivalent ImageSource property can be set by a string that evaluated as a URI. In the managed API, this property uses an underlying ImageSource instance (actually this is usually a BitmapImage, which is a derived class).

See BitmapImage for information on the types of image sources and formats that can be used for an Image.

Cross-domain URIs are permitted (if permitted by configuration on the target server), and specifying the scheme is permitted, but mixing URI schemes (such as accessing an HTTPS image from a Silverlight plug-in hosted on an HTTP-served HTML page) is not permitted. For more information, see URL Access Restrictions in Silverlight.

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 BitmapImage(Uri) constructor. This in turn potentially requests a stream from that URI and returns the image source object.

The string provided for the property is interpreted as a Uniform Resource Identifier (URI). This is in contrast to an Internationalized Resource Identifier (IRI). This distinction means that characters used to identify a ImageSource that are outside of US-ASCII will need to be encoded.

The format-specific filename extensions for the Silverlight supported image formats are not required to be in the URI naming. However, if the retrieved file is a valid image format when it is opened or processed, a runtime exception is thrown.

The ImageFailed event can occur if the initial ImageSource attribute value in XAML does not specify a valid source.

You can use a relative URI to reference an image that you package with the application, or an absolute URI to reference an image from a server. For more information about how Silverlight processes URIs in general, and how relative URIs are interpreted according to your application model or resource structure, see Resource Files.

Tip:
You can specify an initial XAML value of "" (empty string) and then set the value in script at a later time, to create a nonrendering placeholder.

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Freigeben über