Image.ImageFailed Event

Definition

Namespace:

Windows.UI.Xaml.Controls

Occurs when there is an error associated with image retrieval or format.

public:
 virtual event ExceptionRoutedEventHandler ^ ImageFailed;

// Register
event_token ImageFailed(ExceptionRoutedEventHandler const& handler) const;

// Revoke with event_token
void ImageFailed(event_token const* cookie) const;

// Revoke with event_revoker
Image::ImageFailed_revoker ImageFailed(auto_revoke_t, ExceptionRoutedEventHandler const& handler) const;

public event ExceptionRoutedEventHandler ImageFailed;

function onImageFailed(eventArgs) { /* Your code */ }
image.addEventListener("imagefailed", onImageFailed);
image.removeEventListener("imagefailed", onImageFailed);
- or -
image.onimagefailed = onImageFailed;

Public Custom Event ImageFailed As ExceptionRoutedEventHandler 

<Image ImageFailed="eventhandler"/>

Event Type

ExceptionRoutedEventHandler

Remarks

Conditions in which this event can occur include:

• File not found
• Invalid (unrecognized or unsupported) file format
• Unknown file format decoding error after upload
• Qualified resource reload by the system You might be able to use the ErrorMessage in event data to determine the nature of the failure.

ImageFailed and ImageOpened are mutually exclusive. One event or the other will always fire whenever an Image has a Source value set or reset.

One scenario for handling ImageFailed is to set the UriSource of the underlying BitmapImage source to a different local image file. This can serve as a fallback value to display instead of empty space. For example, if you are trying to display an external image where it's possible that the source is no longer there, or for when the user has no Internet connection, you could set the UriSource to reference a local fallback or placeholder image that's part of your app package and is always guaranteed to be available.

When the Image element isn’t in the live visual tree, the Image element will not fire ImageOpened or ImageFailed events. If you need to receive these events while the element isn’t in the live tree, use the BitmapImage.ImageOpened/ImageFailed events.

private void Image_ImageFailed(object sender, ExceptionRoutedEventArgs e) {
    Image img = sender as Image;
    BitmapImage fallbackImage = new BitmapImage(new Uri("ms-appx:///Images/fallback.png"));
    img.Width = 100; //set to known width of this source's natural size
     //might instead want image to stretch to fill, depends on scenario
    img.Source = fallbackImage;
}

Windows 8 behavior

For Windows 8, resources can use a resource qualifier pattern to load different resources depending on device-specific scaling. However, resources aren't automatically reloaded if the scaling factor changes while the app is running. In this case apps would have to take care of reloading resources, by handling the DpiChanged event (or the deprecated LogicalDpiChanged event) and using ResourceManager API to manually reload the resource that's appropriate for the new scaling factor. Starting with Windows 8.1, any resource that was originally retrieved for your app is automatically re-evaluated if the scaling factor changes while the app is running. In addition, when that resource is the image source for an Image object, then one of the source-load events (ImageOpened or ImageFailed) is fired as a result of the system's action of requesting the new resource and then applying it to the Image. The scenario where a run-time scale change might happen is if the user moves your app to a different monitor when more than one is available.

If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in ImageOpened or ImageFailed events that happen at run-time when the scale change is handled, even in cases where the Source is set in XAML. Also, if you did have code that handled DpiChanged/LogicalDpiChanged and reset the resources, you should examine whether that code is still needed given the new Windows 8.1 automatic reload behavior.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.