Using WebClient
Before concluding this chapter, a brief discussion of WebClient is warranted. As mentioned near the start of this chapter, if your application only needs to upload or download data to or from the Internet, then you can use WebClient instead of WebRequest and WebResponse. The advantage to WebClient is that it handles many of the details for you.
WebClient defines one constructor, shown here:
public WebClient( )
It defines the properties shown in Table 24-6. WebClient defines a large number of methods that support both synchronous and asynchronous communication. (Asynchronous support was added to WebClient by C# 2.0.) Because asynchronous communication is beyond the scope of this chapter, only those methods that support synchronous requests are shown in Table 24-7. All methods throw a WebException if an error occurs during transmission.
| Property | Description |
|---|---|
| public string BaseAddress { get; set; } | Obtains or sets the base address of the desired URI. If this property is set, then addresses specified by the WebClient methods will be relative to the base address. |
| public RequestCachePolicy CachePolicy { get; set; } | Obtains or sets the policy that determines when the cache is used. (Added by C# 2.0.) |
| public ICredentials Credentials { get; set; } | Obtains or sets authentication information. This property is null by default. |
| public Encoding Encoding { get; set; } | Obtains or sets the character encoding used while transferring strings. (Added by C# 2.0.) |
| public WebHeaderCollection Headers{ get; set; } | Obtains or sets the collection of the request headers. |
| public bool IsBusy( get; } | If the request is still transferring information, this property is true. It is false otherwise. (Added by C# 2.0.) |
| public IWebProxy Proxy { get; set; } | Obtains or sets the proxy. (Added by C# 2.0.) |
| public NameValueCollection QueryString { get; set; } | Obtains or sets a query string consisting of name/value pairs that can be attached to a request. The query string is separated from the URI by a ?. If more than one name/value pair exists, then an @ separates each pair. |
| public WebHeaderCollection ResponseHeaders { get; } | Obtains a collection of the response headers. |
| public bool UseDefaultCredentials { get; set; } | Obtains or sets a value that determines if default credentials are used for authentication. If true, the default credentials (i.e., those of the user) are used. They are not used if false. (Added by C# 2.0.) |
| Method | Description |
|---|---|
| public byte[ ] DownloadData(string uri) | Downloads the information at the URI specified by uri and returns the result in an array of bytes. |
| public byte[ ] DownloadData(Uri uri) | Downloads the information at the URI specified by uri and returns the result in an array of bytes. (Added by C# 2.0.) |
| public void DownloadFile(string uri, string fname) | Downloads the information at the URI specified by uri and stores the result in the file specified by fname. |
| public void DownloadFile(Uri uri, string fname) | Downloads the information at the URI specified by uri and stores the result in the file specified by fname. (Added by C# 2.0.) |
| public string DownloadString(string uri) | Downloads the information at the URI specified by uri and returns the result as a string. (Added by C# 2.0.) |
| public string DownloadString(Uri uri) | Downloads the information at the URI specified by uri and returns the result as a string. (Added by C# 2.0.) |
| public Stream OpenRead(string uri) | Returns an input stream from which the information at the URI specified by uri can be read. This stream must be closed after reading is completed. |
| public Stream OpenRead(Uri uri) | Returns an input stream from which the information at the URI specified by uri can be read. This stream must be closed after reading is completed. (Added by C# 2.0.) |
| public Stream OpenWrite(string uri) | Returns an output stream to which information can be written to the URI specified by uri. This stream must be closed after writing is completed. |
| public Stream OpenWrite(Uri uri) | Returns an output stream to which information can be written to the URI specified by uri. This stream must be closed after writing is completed. (Added by C# 2.0.) |
| public Stream OpenWrite(string uri, string how) | Returns an output stream to which information can be written to the URI specified by uri. This stream must be closed after writing is completed. The string passed in how specifies how the information will be written. |
| public Stream OpenWrite(Uri uri, string how) | Returns an output stream to which information can be written to the URI specified by uri. This stream must be closed after writing is completed. The string passed in how specifies how the information will be written. (Added by C# 2.0.) |
| public byte[ ] UploadData(string uri, byte[ ] info) | Writes the information specified by info to the URI specified by uri. The response is returned. |
| public byte[ ] UploadData(Uri uri, byte[ ] info) | Writes the information specified by info to the URI specified by uri. The response is returned. (Added by C# 2.0.) |
| public byte[ ] UploadData(string uri, string how, byte[ ] info) | Writes the information specified by info to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. |
| public byte[ ] UploadData(Uri uri, string how, byte[ ] info) | Writes the information specified by info to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. (Added by C# 2.0.) |
| public byte[ ] UploadFile(string uri, string fname) | Writes the information in the file specified by fname to the URI specified by uri. The response is returned. |
| public byte[ ] UploadFile(Uri uri, string fname) | Writes the information in the file specified by fname to the URI specified by uri. The response is returned. (Added by C# 2.0.) |
| public byte[ ] UploadFile(string uri, string how, string fname) | Writes the information in the file specified by fname to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. |
| public byte[ ] UploadFile(Uri uri, string how, string fname) | Writes the information in the file specified by fname to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. (Added by C# 2.0.) |
| public string UploadString(string uri, string str) | Writes str to the URI specified by uri. The response is returned. (Added by C# 2.0.) |
| public string UploadString(Uri uri, string str) | Writes str to the URI specified by uri. The response is returned. (Added by C# 2.0.) |
| public string UploadString(string uri, string how, string str) | Writes str to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. (Added by C# 2.0.) |
| public string UploadString(Uri uri, string how, string str) | Writes str to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. (Added by C# 2.0.) |
| public byte[ ] UploadValues(string uri, NameValueCollection vals) | Writes the values in the collection specified by vals to the URI specified by uri. The response is returned. |
| public byte[ ] UploadValues(Uri uri, NameValueCollection vals) | Writes the values in the collection specified by vals to the URI specified by uri. The response is returned. (Added by C# 2.0.) |
| public byte[ ] UploadValues(string uri, string how, NameValueCollection vals) | Writes the values in the collection specified by vals to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. |
| public byte[ ] UploadValues(Uri uri, string how, NameValueCollection vals) | Writes the values in the collection specified by vals to the URI specified by uri. The response is returned. The string passed in how specifies how the information will be written. (Added by C# 2.0.) |
The following program demonstrates how to use WebClient to download data into a file:
// Use WebClient to download information into a file. using System; using System.Net; using System.IO; class WebClientDemo { public static void Main() { WebClient user = new WebClient(); string uri = "http://www.McGraw-Hill.com"; string fname = "data.txt"; try { Console.WriteLine("Downloading data from " + uri + " to " + fname); user.DownloadFile(uri, fname); } catch (WebException exc) { Console.WriteLine(exc); } Console.WriteLine("Download complete."); } } This program downloads the information at McGrawHill.com and puts it into a file called data.txt. Notice how few lines of code are involved. By changing the string specified by uri, you can download information from any URI, including specific files.
Although WebRequest and WebResponse give you greater control and access to more information, WebClient is all that many applications will need. It is particularly useful when all you need to do is download information from the Web. For example, you might use WebClient to allow an application to obtain documentation updates.
EAN: 2147483647
Pages: 300