ImageSource
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Gets or sets the Uniform Resource Identifier (URI) of the image file source that is displayed by an ImageBrush.
<ImageBrush ImageSource="string" .../>
value = object.ImageSource
object.ImageSource = value
Property Value
Type: string, or BitmapImage
The URI for the image displayed by the ImageBrush, or potentially a BitmapImage object in the get usage.
This property is read/write. The default value is null.
Remarks
The ImageSource property can be used to reference images in the JPEG and PNG file formats.
The string provided for the ImageSource property is interpreted as a URI instead of an Internationalized Resource Identifier (IRI). This distinction means that characters used to identify an ImageSource that are outside the US-ASCII character set will have to be encoded.
Relative references are permitted. The starting location for the relative reference is the HTML page that contains the current Silverlight plug-in.
Cross-domain URIs are permitted, and specifying the scheme is permitted, but mixing URI schemes (such as accessing an HTTPS image from a Silverlight plug-in that is hosted on an HTTP-served HTML page) is not permitted. The JPEG and PNG file name extensions are not required to be in the URI. However, if the retrieved file is not determined to be either in JPEG or PNG format, a run-time exception is thrown.
If you are not accessing cross-domain sources, you should consider using SetSource instead of setting ImageSource directly. This provides the advantage of being able to track the download. Also, you can download images as a package and access parts from within the package.
In JavaScript, you can set the value to null or an empty string at run time to cause the image to unload and no longer render. Doing so does not raise an ImageFailed event. In contrast, setting an ImageSource to a URI value that does not resolve or that does not result in a valid image file download will raise an ImageFailed event. Also, a SetValue error is thrown, even if ImageFailed is handled.
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.
The ImageFailed event can occur if the initial ImageSource attribute value in XAML does not specify a valid source.
For Silverlight 2, there is also a verbose XAML usage that specifies a BitmapImage object, rather than relying on a native conversion from Uri:
<ImageBrush ...>
<ImageBrush.ImageSource>
<BitmapImage UriSource="string" .../>
</ImageBrush.ImageSource>
</ImageBrush>