The following is the signature of an OpenReadCompleted event handler.

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

The most relevant API in this handler is the Result of the OpenReadCompletedEventArgs. The Result is of type Stream. You can use this stream directly to set properties or call methods that can take a stream, for example SetSource. Alternatively, you can use a StreamReader or other APIs to access the stream.

The following is the signature of an DownloadStringCompleted event handler.

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

The most relevant API in this handler is the Result of the DownloadStringCompletedEventArgs. 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.

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(Uri), so that the returned type is a Stream.

Obtaining named parts from the package is not done by the WebClient class APIs 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));
    BitmapImage imgsrc = new BitmapImage();
    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 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.

Visual progress indicator

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 version 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();
     }
}

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 Make a Service Available Across Domain Boundaries.

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 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 (/).