Svg​Image​Source Svg​Image​Source Svg​Image​Source Class

Definition

Provides a source object for properties that use a Scalable Vector Graphics (SVG) source. You can define a SvgImageSource by using a Uniform Resource Identifier (URI) that references a SVG file, or by calling SetSourceAsync(IRandomAccessStream) and supplying a stream.

public : class SvgImageSource : ImageSource, ISvgImageSourcepublic class SvgImageSource : ImageSource, ISvgImageSourcePublic Class SvgImageSource Inherits ImageSource Implements ISvgImageSource
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Inherited Members

Inherited methods

Inherited properties

Remarks

Remarks

SvgImageSource lets you use a SVG source to be displayed using an ImageBrush or directly in an Image control. SvgImageSource supports secure static mode from the SVG specification and does not support animations or interactions. The Direct2D API supplies the underlying SVG rendering support and for more info on specific SVG element and attribute support, see SVG Support. For more info on formats and how to use Uniform Resource Identifier (URI) to access image source files that come from app resources, see Image and ImageBrush.

The SvgImageSource represents an abstraction so that a SVG source can be set asynchronously but still be referenced in XAML markup as a property value, or in code as an object that doesn't use awaitable syntax. When you create a SvgImageSource object in code, it initially has no valid source. You should then set its source using one of these techniques:

  • Use the SvgImageSource(Uri) constructor rather than the default contsructor. Although it's a constructor, you can think of this as having an implicit asynchronous behavior: the SvgImageSource(svgimagesource.md) won't be ready for use until it raises an Opened event that indicates a successful async source set operation.
  • Set the UriSource property. As with the Uri constructor, this action is implicitly asynchronous, and the SvgImageSource won't be ready for use until it raises an Opened event.
  • Use SetSourceAsync(IRandomAccessStream). This method is explicitly asynchronous. The properties where you might use a SvgImageSource, such as Source, are designed for this asynchronous behavior, and won't throw exceptions if they are set using a SvgImageSource that doesn't have a complete source yet. Rather than handling exceptions, you should handle Opened or OpenFailed events either on the SvgImageSource directly or on the control that uses the source (if those events are available on the control class).

Opened and OpenFailed are mutually exclusive. One event or the other will always be raised whenever a SvgImageSource object has its source value set or reset.

Sizing

Depending on your intended use case, you can specify the size of a SvgImageSource in several different ways:

  • Use the RasterizePixelHeight and RasterizePixelWidth properties to specify an explicit height and width in logical pixels to decode the SVG source at.
  • If you don't specify a RasterizePixelHeight or RasterizePixelWidth, then the application's layout will dictate the decode size while still preserving aspect ratio. If no size can be determined from the application's layout, then the SVG source will be decoded to the maximum window size.

Version compatibility

The SvgImageSource class is not available prior to Windows 10, version 1703. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you will not be able to use SvgImageSource. For more info, see Version adaptive code.

To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this class before you use it.

Examples

Here's an example of how to set the source of an Image to a SVG file. Since there is no height or width explicitly specified, the application layout will dictate the appropriate size for the SVG to decode at.

<Image Source="Assets/mysvg.svg"/>

Constructors

SvgImageSource() SvgImageSource() SvgImageSource()

Initializes a new instance of the SvgImageSource class.

public : SvgImageSource()public SvgImageSource()Public Sub New()
Attributes

SvgImageSource(Uri) SvgImageSource(Uri) SvgImageSource(Uri)

Initializes a new instance of the SvgImageSource class, using the supplied Uniform Resource Identifier (URI).

public : SvgImageSource(Uri uriSource)public SvgImageSource(Uri uriSource)Public Sub New(uriSource As Uri)
Parameters
uriSource
Uri Uri Uri

A reference to the SVG source file.

Attributes

Properties

RasterizePixelHeight RasterizePixelHeight RasterizePixelHeight

Gets or sets the height to use for SVG rasterization operations.

public : double RasterizePixelHeight { get; set; }public double RasterizePixelHeight { get; set; }Public ReadWrite Property RasterizePixelHeight As double
<SvgImageSource RasterizePixelHeight="double"/>
Value
double double double

The height (in logical pixels) to use for SVG decoding operations. The default is Double.NaN.

Attributes

Remarks

Since the units are logical pixels, the SVG is decoded using values that are pre-factored for the logical resolution, and it potentially won't use as much memory.

If RasterizePixelHeight and RasterizePixelWidth aren't explicitly set, then the application's layout will determine the decode size so that the SvgImageSource fits in the available space.

RasterizePixelHeightProperty RasterizePixelHeightProperty RasterizePixelHeightProperty

Identifies the RasterizePixelHeight dependency property.

public : static DependencyProperty RasterizePixelHeightProperty { get; }public static DependencyProperty RasterizePixelHeightProperty { get; }Public Static ReadOnly Property RasterizePixelHeightProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the RasterizePixelHeight dependency property.

Attributes

RasterizePixelWidth RasterizePixelWidth RasterizePixelWidth

Gets or sets the width to use for SVG rasterization operations.

public : double RasterizePixelWidth { get; set; }public double RasterizePixelWidth { get; set; }Public ReadWrite Property RasterizePixelWidth As double
<SvgImageSource RasterizePixelWidth="double"/>
Value
double double double

The width (in logical pixels) to use for SVG decoding operations. The default is Double.NaN.

Attributes

Remarks

Since the units are logical pixels, the SVG is decoded using values that are pre-factored for the logical resolution, and it potentially won't use as much memory.

If RasterizePixelHeight and RasterizePixelWidth aren't explicitly set, then the application's layout will determine the decode size so that the SvgImageSource fits in the available space.

RasterizePixelWidthProperty RasterizePixelWidthProperty RasterizePixelWidthProperty

Identifies the RasterizePixelWidth dependency property.

public : static DependencyProperty RasterizePixelWidthProperty { get; }public static DependencyProperty RasterizePixelWidthProperty { get; }Public Static ReadOnly Property RasterizePixelWidthProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the RasterizePixelWidth dependency property.

Attributes

UriSource UriSource UriSource

Gets or sets the Uniform Resource Identifier (URI) of the SVG source file that generated this SvgImageSource.

public : Uri UriSource { get; set; }public Uri UriSource { get; set; }Public ReadWrite Property UriSource As Uri
<SvgImageSource UriSource="uri" />
Value
Uri Uri Uri

An object describing the Uniform Resource Identifier (URI) of the SVG source file that generated this SvgImageSource.

Attributes

UriSourceProperty UriSourceProperty UriSourceProperty

Identifies the UriSource dependency property.

public : static DependencyProperty UriSourceProperty { get; }public static DependencyProperty UriSourceProperty { get; }Public Static ReadOnly Property UriSourceProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the UriSource dependency property.

Attributes

Methods

SetSourceAsync(IRandomAccessStream) SetSourceAsync(IRandomAccessStream) SetSourceAsync(IRandomAccessStream)

Sets the source SVG for a SvgImageSource by accessing a stream and processing the result asynchronously.

public : IAsyncOperation<SvgImageSourceLoadStatus> SetSourceAsync(IRandomAccessStream streamSource)public IAsyncOperation<SvgImageSourceLoadStatus> SetSourceAsync(IRandomAccessStream streamSource)Public Function SetSourceAsync(streamSource As IRandomAccessStream) As IAsyncOperation( Of SvgImageSourceLoadStatus )
Parameters
streamSource
IRandomAccessStream IRandomAccessStream IRandomAccessStream

The stream source that sets the SVG source value.

Returns

A SvgImageSourceLoadStatus value that indicates whether the operation was successful. If it failed, indicates the reason for the failure.

Attributes

Examples

This example shown here uses a file stream (obtained using a file picker, not shown) to load an image source by calling SetSourceAsync(IRandomAccessStream). The file picker, stream and call to SetSourceAsync(IRandomAccessStream) are all asynchronous.

// Ensure the stream is disposed once the SVG is loaded
using (IRandomAccessStream fileStream = await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
{
    // Set the SVG source to the selected file
    SvgImageSource svgImage = new SvgImageSource();

    await svgImage.SetSourceAsync(fileStream);
    Scenario2Image.Source = svgImage;
}

Remarks

Setting a SVG source by calling the asynchronous SetSourceAsync(IRandomAccessStream) method avoids blocking the UI thread. For more info on how to use async or await, see Call asynchronous APIs in C# or Visual Basic. If the app changes the SVG source again via SetSourceAsync(IRandomAccessStream) or UriSource while a SetSourceAsync(IRandomAccessStream) call is already in progress, the pending SetSourceAsync(IRandomAccessStream) action will throw a TaskCanceledException.

Events

Opened Opened Opened

Occurs when the SVG source is downloaded and decoded with no failure.

public : event TypedEventHandler Openedpublic event TypedEventHandler OpenedPublic Event Opened
<SvgImageSource Opened="eventhandler"/>
Attributes

Remarks

When the Opened event occurs, it serves as the notification that any asynchronous operations have completed and all the properties of an SvgImageSource are ready for use.

OpenFailed OpenFailed OpenFailed

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

public : event TypedEventHandler OpenFailedpublic event TypedEventHandler OpenFailedPublic Event OpenFailed
<SvgImageSource OpenFailed="eventhandler"/>
Attributes

Remarks

You can use the OpenFailed event to determine why the SVG didn't load correctly by checking the SvgImageSourceFailedEventArgs, which contain error information in the Status property. One scenario for handling OpenFailed is to set the UriSource to a different local SVG source file that can serve as a fallback value. For example, if you are trying to display an external image where it's possible that either the source is no longer there, the user has no Internet connection, or the SVG source is not in the correct format, you could set the UriSource to reference a local fallback or placeholder SVG that's part of your app package and is always guaranteed to be available.

private void SvgImageSource_OpenFailed(SvgImageSource sender, SvgImageSourceFailedEventArgs args) {
    if(args.Status != SvgImageSourceLoadStatus.Success) {
        sender.UriSource = new Uri("ms-appx:///Assets/fallback.svg");
    }
}