Downloading Content on Demand

The following is the signature of an OpenReadCompleted event handler.

void wc_OpenReadCompleted(object sender, OpenReadCompletedEventArgs e) {
...
}

The second parameter passed to the event handler is an instance of the OpenReadCompletedEventArgs class. The most important member is the Result property of the OpenReadCompletedEventArgs class. The Result property is of type Stream. You can use this stream directly to set properties or call methods that can take a stream, for example SetSource(Stream). Alternatively, you can use a StreamReader or other classes to access the stream.

An application should check the AsyncCompletedEventArgs.Error and AsyncCompletedEventArgs.Cancelled properties inherited by the OpenReadCompletedEventArgs class instance before using the data that is returned by the Result property. If the inherited AsyncCompletedEventArgs.Error property's value is an Exception object or the inherited AsyncCompletedEventArgs.Cancelled property's value is true, the asynchronous operation did not complete correctly and the Result property's value will not be valid. Otherwise, an exception will be thrown that should be handled when the Result property is accessed.

The following is the signature of an DownloadStringCompleted event handler.

void wc_DownloadStringCompleted(object sender, DownloadStringCompletedEventArgs e) {
...
}

The second parameter passed to the event handler is an instance of the DownloadStringCompletedEventArgs class. The most important member is the Result property of the DownloadStringCompletedEventArgs class. The Result is of type String. You can use this string directly to set properties or call methods that can take a string, for example Load. Or you can perform your own processing of the string.

An application should check the AsyncCompletedEventArgs.Error and AsyncCompletedEventArgs.Cancelled properties inherited by the DownloadStringCompletedEventArgs class instance before using the data that is returned by the Result property. If the inherited AsyncCompletedEventArgs.Error property's value is an Exception object or the inherited AsyncCompletedEventArgs.Cancelled property's value is true, the asynchronous operation did not complete correctly and the Result property's value will not be valid. Otherwise, an exception will be thrown that should be handled when the Result property is accessed.

Silverlight provides the ability to download content as a package, which is a collection of independent files that contain XAML content, media assets, and other application data. If you are downloading a package, you call OpenReadAsync, so that the returned type is a Stream.

Obtaining named parts from the package is not done by the WebClient class directly. Instead, you use StreamResourceInfo to process the stream as a package, and then return one of the parts of the package as a new stream.

Using the SetSource Method

void DownloadImagePart(string imgPart)
{
    WebClient wc = new WebClient();
    wc.OpenReadCompleted += new OpenReadCompletedEventHandler(wc_OpenReadCompleted);
    wc.OpenReadAsync(new Uri("imgs.zip", UriKind.Relative), imgPart);
}

void wc_OpenReadCompleted(object sender, OpenReadCompletedEventArgs e)
{
    StreamResourceInfo sri = new StreamResourceInfo(e.Result as Stream, null);
    String sURI = e.UserState as String;
    StreamResourceInfo imageStream = Application.GetResourceStream(sri, new Uri(sURI, UriKind.Relative));
    BitmapSource imgsrc = new BitmapSource ();
    imgsrc.SetSource(imageStream.Stream);
    ImgToFill.Source = imgsrc;
}

using System.IO;
using System.Windows.Resources;

using System.Windows.Media.Imaging;

FontSource

You can also retrieve fonts from downloaded packages, which are added to the font source collection for text display elements, such as TextBox and TextBlock. The mechanism for getting fonts for a font source is slightly different. You request the package that contains the fonts as a stream (by using OpenReadAsync(Uri)). After handling OpenReadCompleted, retain a reference to the stream. Use the stream as the constructor parameter for FontSource (FontSource constructor). All font sources in the package are available and are added to the font collection in the FontSource. You do not have to specify a part by name. Constructing a FontSource turns the parts into collection items, with the font name / part name becoming the key for the font source of an individual font in the collection. Then you set FontSource properties, such as FontSource, with the FontSource object. You specify specific font names when you set the FontFamily properties on various types and the corresponding font is obtained from the font source collection.

Note:
You can retrieve fonts from packages that contain non-font parts. Only the font source parts are used for the FontSource.

The DownloadProgressChanged event is often used with a visual progress indicator, which displays the percentage of content that has been downloaded. A visual progress indicator can be a simple set of XAML content, such as Rectangle and TextBlock objects, as shown in the following XAML example.

<!-- Visual progress indicator -->
<Canvas Canvas.Top="70">
  <Rectangle
    Name="progressRectangle"
    Canvas.Left="20"
    Height="10" Width="0"
    Fill="Maroon" />
  <Rectangle
    Canvas.Top ="-1"
    Canvas.Left="19" Height="12"
    Width="202"
    StrokeThickness="1" Stroke="Black" />
  <TextBlock
    x:Name="progressText"
    Canvas.Top ="-4" Canvas.Left="230"
    Text="0%" FontSize="12" />
</Canvas>

To add the handler for progress, add it at the same time that you add either the OpenReadCompleted or DownloadStringCompleted handlers.

 void DownloadImagePart(string imgPart)
{
    WebClient wc = new WebClient();
    wc.OpenReadCompleted += new OpenReadCompletedEventHandler(wc_OpenReadCompleted);
    wc.DownloadProgressChanged += new DownloadProgressChangedEventHandler(wc_DownloadProgressChanged);
    wc.OpenReadAsync(new Uri("imgs.zip", UriKind.Relative), imgPart);
}

The following C# example shows how to define a DownloadProgressChanged event-handler function that updates the visual progress indicator shown in the previous XAML.

// Event handler for updating visual progress indicator
void wc_DownloadProgressChanged(object sender, DownloadProgressChangedEventArgs e)
{
    // Calculate the downloaded percentage.
    // Update the Rectangle and TextBlock objects of the visual progress indicator.
    progressText.Text = e.ProgressPercentage.ToString();
    progressRectangle.Width = (double) e.ProgressPercentage;
}

The following illustration shows the visual progress indicator at the starting, middle, and ending position of the download.

A visual progress indicator can be constructed from a wide variety of XAML content, such as animated objects. The progress is reported by the ProgressPercentage property as a Double value between 0 and 100.

Note:
If you are migrating Silverlight 1.0 code, the equivalent Downloader progress properties returned a double between 0 and 1, so you may have to eliminate any *100 logic you used to get a percentage number between 0 and 100.

You might call CancelAsync in response to your own timers, or you might provide a UI option so that the user can cancel any download. Before calling CancelAsync you should check IsBusy to make sure that you are not about to cancel a request that just completed. The following code shows how to perform this check.

void CancelButton_ClickHandler(object sender, RoutedEventArgs e)
{
     // Check if async download is in progress
     if (wc.IsBusy)
     {
            // Initiate cancel
            wc.CancelAsync();
     }
}

When you call the CancelAsync method, your application still receives the completion event associated with the operation. For example, if you call CancelAsync to cancel a DownloadStringAsync operation and you have specified an event handler for the DownloadStringCompleted event, your event handler receives notification that the operation has ended. To learn whether the operation completed successfully, check the AsyncCompletedEventArgs.Cancelled property of the System.ComponentModel.AsyncCompletedEventArgs inherited by the class (DownloadStringCompletedEventArgs, for example) for the relevant completed event handler. The AsyncCompletedEventArgs.Cancelled property inherited by the class is set to true if the true if the operation was cancelled.

If you cancel a string download operation and you check the Result property of the

DownloadStringCompletedEventArgs object, an exception will occur since the operation was cancelled.

The URI that you specify for the OpenReadAsync and DownloadStringAsync APIs will generally use relative URIs. The relative URI will then use the same URI scheme that is used to serve the HTML page, which is generally HTTP. The starting location for the relative reference is the HTML page that contains the current Silverlight plug-in, also known as the site of origin.

You can download cross-domain content using WebClient APIs from the client perspective. But the server that is serving cross-domain must have a client access policy that allows cross-domain access. For more information, see Network Security Access Restrictions in Silverlight.

WebClient does not support downloads through the FILE scheme. This may be an issue if you are testing Silverlight-based applications locally in the file system, instead of developing and then deploying your Web site to a test server or to the localhost.

You can use HTTPS as the implied protocol for downloads, but only if the HTML page that contains the current Silverlight plug-in is also HTTPS.

Backslashes (\) are not permitted in URIs; always use forward slashes (/).