Export (0) Print
Expand All
3 out of 9 rated this helpful - Rate this topic

WebClient Class

Provides common methods for sending data to and receiving data from a resource identified by a URI.

Namespace:  System.Net
Assembly:  System (in System.dll)
[ComVisibleAttribute(true)]
public class WebClient : Component

The WebClient type exposes the following members.

  NameDescription
Public methodSupported by Portable Class LibraryWebClientInitializes a new instance of the WebClient class.
Top
  NameDescription
Public propertySupported by Portable Class LibraryBaseAddressGets or sets the base URI for requests made by a WebClient.
Public propertyCachePolicyGets or sets the application's cache policy for any resources obtained by this WebClient instance using WebRequest objects.
Protected propertyCanRaiseEventsGets a value indicating whether the component can raise an event. (Inherited from Component.)
Public propertyContainerGets the IContainer that contains the Component. (Inherited from Component.)
Public propertySupported by Portable Class LibraryCredentialsGets or sets the network credentials that are sent to the host and used to authenticate the request.
Protected propertyDesignModeGets a value that indicates whether the Component is currently in design mode. (Inherited from Component.)
Public propertySupported by Portable Class LibraryEncodingGets and sets the Encoding used to upload and download strings.
Protected propertyEventsGets the list of event handlers that are attached to this Component. (Inherited from Component.)
Public propertySupported by Portable Class LibraryHeadersGets or sets a collection of header name/value pairs associated with the request.
Public propertySupported by Portable Class LibraryIsBusyGets whether a Web request is in progress.
Public propertyProxyGets or sets the proxy used by this WebClient object.
Public propertyQueryStringGets or sets a collection of query name/value pairs associated with the request.
Public propertySupported by Portable Class LibraryResponseHeadersGets a collection of header name/value pairs associated with the response.
Public propertySiteGets or sets the ISite of the Component. (Inherited from Component.)
Public propertySupported by Portable Class LibraryUseDefaultCredentialsGets or sets a Boolean value that controls whether the DefaultCredentials are sent with requests.
Top
  NameDescription
Public methodSupported by Portable Class LibraryCancelAsyncCancels a pending asynchronous operation.
Public methodCreateObjRefCreates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
Public methodDispose()Releases all resources used by the Component. (Inherited from Component.)
Protected methodDispose(Boolean)Releases the unmanaged resources used by the Component and optionally releases the managed resources. (Inherited from Component.)
Public methodDownloadData(String)Downloads the resource with the specified URI as a Byte array.
Public methodDownloadData(Uri)Downloads the resource with the specified URI as a Byte array.
Public methodDownloadDataAsync(Uri)Downloads the specified resource as a Byte array. This method does not block the calling thread.
Public methodDownloadDataAsync(Uri, Object)Downloads the specified resource as a Byte array. This method does not block the calling thread.
Public methodDownloadFile(String, String)Downloads the resource with the specified URI to a local file.
Public methodDownloadFile(Uri, String)Downloads the resource with the specified URI to a local file.
Public methodDownloadFileAsync(Uri, String)Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.
Public methodDownloadFileAsync(Uri, String, Object)Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.
Public methodDownloadString(String)Downloads the requested resource as a String. The resource to download is specified as a String containing the URI.
Public methodDownloadString(Uri)Downloads the requested resource as a String. The resource to download is specified as a Uri.
Public methodSupported by Portable Class LibraryDownloadStringAsync(Uri)Downloads the resource specified as a Uri. This method does not block the calling thread.
Public methodSupported by Portable Class LibraryDownloadStringAsync(Uri, Object)Downloads the specified string to the specified resource. This method does not block the calling thread.
Public methodSupported by Portable Class LibraryEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeReleases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection. (Inherited from Component.)
Public methodSupported by Portable Class LibraryGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetLifetimeServiceRetrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodGetServiceReturns an object that represents a service provided by the Component or by its Container. (Inherited from Component.)
Public methodSupported by Portable Class LibraryGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by Portable Class LibraryGetWebRequestReturns a WebRequest object for the specified resource.
Protected methodGetWebResponse(WebRequest)Returns the WebResponse for the specified WebRequest.
Protected methodSupported by Portable Class LibraryGetWebResponse(WebRequest, IAsyncResult)Returns the WebResponse for the specified WebRequest using the specified IAsyncResult.
Public methodInitializeLifetimeServiceObtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodSupported by Portable Class LibraryMemberwiseClone()Creates a shallow copy of the current Object. (Inherited from Object.)
Protected methodMemberwiseClone(Boolean)Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
Protected methodOnDownloadDataCompletedRaises the DownloadDataCompleted event.
Protected methodOnDownloadFileCompletedRaises the DownloadFileCompleted event.
Protected methodSupported by Portable Class LibraryOnDownloadProgressChangedRaises the DownloadProgressChanged event.
Protected methodSupported by Portable Class LibraryOnDownloadStringCompletedRaises the DownloadStringCompleted event.
Protected methodSupported by Portable Class LibraryOnOpenReadCompletedRaises the OpenReadCompleted event.
Protected methodSupported by Portable Class LibraryOnOpenWriteCompletedRaises the OpenWriteCompleted event.
Protected methodOnUploadDataCompletedRaises the UploadDataCompleted event.
Protected methodOnUploadFileCompletedRaises the UploadFileCompleted event.
Protected methodSupported by Portable Class LibraryOnUploadProgressChangedRaises the UploadProgressChanged event.
Protected methodSupported by Portable Class LibraryOnUploadStringCompletedRaises the UploadStringCompleted event.
Protected methodOnUploadValuesCompletedRaises the UploadValuesCompleted event.
Public methodOpenRead(String)Opens a readable stream for the data downloaded from a resource with the URI specified as a String.
Public methodOpenRead(Uri)Opens a readable stream for the data downloaded from a resource with the URI specified as a Uri
Public methodSupported by Portable Class LibraryOpenReadAsync(Uri)Opens a readable stream containing the specified resource. This method does not block the calling thread.
Public methodSupported by Portable Class LibraryOpenReadAsync(Uri, Object)Opens a readable stream containing the specified resource. This method does not block the calling thread.
Public methodOpenWrite(String)Opens a stream for writing data to the specified resource.
Public methodOpenWrite(Uri)Opens a stream for writing data to the specified resource.
Public methodOpenWrite(String, String)Opens a stream for writing data to the specified resource, using the specified method.
Public methodOpenWrite(Uri, String)Opens a stream for writing data to the specified resource, by using the specified method.
Public methodSupported by Portable Class LibraryOpenWriteAsync(Uri)Opens a stream for writing data to the specified resource. This method does not block the calling thread.
Public methodSupported by Portable Class LibraryOpenWriteAsync(Uri, String)Opens a stream for writing data to the specified resource. This method does not block the calling thread.
Public methodSupported by Portable Class LibraryOpenWriteAsync(Uri, String, Object)Opens a stream for writing data to the specified resource, using the specified method. This method does not block the calling thread.
Public methodToStringReturns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component.)
Public methodUploadData(String, Byte[])Uploads a data buffer to a resource identified by a URI.
Public methodUploadData(Uri, Byte[])Uploads a data buffer to a resource identified by a URI.
Public methodUploadData(String, String, Byte[])Uploads a data buffer to the specified resource, using the specified method.
Public methodUploadData(Uri, String, Byte[])Uploads a data buffer to the specified resource, using the specified method.
Public methodUploadDataAsync(Uri, Byte[])Uploads a data buffer to a resource identified by a URI, using the POST method. This method does not block the calling thread.
Public methodUploadDataAsync(Uri, String, Byte[])Uploads a data buffer to a resource identified by a URI, using the specified method. This method does not block the calling thread.
Public methodUploadDataAsync(Uri, String, Byte[], Object)Uploads a data buffer to a resource identified by a URI, using the specified method and identifying token.
Public methodUploadFile(String, String)Uploads the specified local file to a resource with the specified URI.
Public methodUploadFile(Uri, String)Uploads the specified local file to a resource with the specified URI.
Public methodUploadFile(String, String, String)Uploads the specified local file to the specified resource, using the specified method.
Public methodUploadFile(Uri, String, String)Uploads the specified local file to the specified resource, using the specified method.
Public methodUploadFileAsync(Uri, String)Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
Public methodUploadFileAsync(Uri, String, String)Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
Public methodUploadFileAsync(Uri, String, String, Object)Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
Public methodUploadString(String, String)Uploads the specified string to the specified resource, using the POST method.
Public methodUploadString(Uri, String)Uploads the specified string to the specified resource, using the POST method.
Public methodUploadString(String, String, String)Uploads the specified string to the specified resource, using the specified method.
Public methodUploadString(Uri, String, String)Uploads the specified string to the specified resource, using the specified method.
Public methodSupported by Portable Class LibraryUploadStringAsync(Uri, String)Uploads the specified string to the specified resource. This method does not block the calling thread.
Public methodSupported by Portable Class LibraryUploadStringAsync(Uri, String, String)Uploads the specified string to the specified resource. This method does not block the calling thread.
Public methodSupported by Portable Class LibraryUploadStringAsync(Uri, String, String, Object)Uploads the specified string to the specified resource. This method does not block the calling thread.
Public methodUploadValues(String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI.
Public methodUploadValues(Uri, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI.
Public methodUploadValues(String, String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.
Public methodUploadValues(Uri, String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.
Public methodUploadValuesAsync(Uri, NameValueCollection)Uploads the data in the specified name/value collection to the resource identified by the specified URI. This method does not block the calling thread.
Public methodUploadValuesAsync(Uri, String, NameValueCollection)Uploads the data in the specified name/value collection to the resource identified by the specified URI, using the specified method. This method does not block the calling thread.
Public methodUploadValuesAsync(Uri, String, NameValueCollection, Object)Uploads the data in the specified name/value collection to the resource identified by the specified URI, using the specified method. This method does not block the calling thread, and allows the caller to pass an object to the method that is invoked when the operation completes.
Top
  NameDescription
Public eventDisposedOccurs when the component is disposed by a call to the Dispose method. (Inherited from Component.)
Public eventDownloadDataCompletedOccurs when an asynchronous data download operation completes.
Public eventDownloadFileCompletedOccurs when an asynchronous file download operation completes.
Public eventSupported by Portable Class LibraryDownloadProgressChangedOccurs when an asynchronous download operation successfully transfers some or all of the data.
Public eventSupported by Portable Class LibraryDownloadStringCompletedOccurs when an asynchronous resource-download operation completes.
Public eventSupported by Portable Class LibraryOpenReadCompletedOccurs when an asynchronous operation to open a stream containing a resource completes.
Public eventSupported by Portable Class LibraryOpenWriteCompletedOccurs when an asynchronous operation to open a stream to write data to a resource completes.
Public eventUploadDataCompletedOccurs when an asynchronous data-upload operation completes.
Public eventUploadFileCompletedOccurs when an asynchronous file-upload operation completes.
Public eventSupported by Portable Class LibraryUploadProgressChangedOccurs when an asynchronous upload operation successfully transfers some or all of the data.
Public eventSupported by Portable Class LibraryUploadStringCompletedOccurs when an asynchronous string-upload operation completes.
Public eventUploadValuesCompletedOccurs when an asynchronous upload of a name/value collection completes.
Top

The WebClient class provides common methods for sending data to or receiving data from any local, intranet, or Internet resource identified by a URI.

The WebClient class uses the WebRequest class to provide access to resources. WebClient instances can access data with any WebRequest descendant registered with the WebRequest.RegisterPrefix method.

NoteNote

By default, the .NET Framework supports URIs that begin with http:, https:, ftp:, and file: scheme identifiers.

The following table describes WebClient methods for uploading data to a resource.

Method

Description

OpenWrite

Retrieves a Stream used to send data to the resource.

OpenWriteAsync

Retrieves a Stream used to send data to the resource, without blocking the calling thread.

UploadData

Sends a byte array to the resource and returns a Byte array containing any response.

UploadDataAsync

Sends a Byte array to the resource, without blocking the calling thread.

UploadFile

Sends a local file to the resource and returns a Byte array containing any response.

UploadFileAsync

Sends a local file to the resource, without blocking the calling thread.

UploadValues

Sends a NameValueCollection to the resource and returns a Byte array containing any response.

UploadValuesAsync

Sends a NameValueCollection to the resource and returns a Byte array containing any response, without blocking the calling thread.

UploadString

Sends a String to the resource, without blocking the calling thread.

UploadStringAsync

Sends a String to the resource, without blocking the calling thread.

The following table describes WebClient methods for downloading data from a resource.

Method

Description

OpenRead

Returns the data from a resource as a Stream.

OpenReadAsync

Returns the data from a resource, without blocking the calling thread.

DownloadData

Downloads data from a resource and returns a Byte array.

DownloadDataAsync

Downloads data from a resource and returns a Byte array, without blocking the calling thread.

DownloadFile

Downloads data from a resource to a local file.

DownloadFileAsync

Downloads data from a resource to a local file, without blocking the calling thread.

DownloadString

Downloads a String from a resource and returns a String.

DownloadStringAsync

Downloads a String from a resource, without blocking the calling thread.

You can use the CancelAsync method to cancel asynchronous operations that have not completed.

A WebClient instance does not send optional HTTP headers by default. If your request requires an optional header, you must add the header to the Headers collection. For example, to retain queries in the response, you must add a user-agent header. Also, servers may return 500 (Internal Server Error) if the user agent header is missing.

AllowAutoRedirect is set to true in WebClient instances.

Notes to Inheritors

Derived classes should call the base class implementation of WebClient to ensure the derived class works as expected.

The following code example takes the URI of a resource, retrieves it, and displays the response.


using System;
using System.Net;
using System.IO;

public class Test
{
    public static void Main (string[] args)
    {
        if (args == null || args.Length == 0)
        {
            throw new ApplicationException ("Specify the URI of the resource to retrieve.");
        }
        WebClient client = new WebClient ();

        // Add a user agent header in case the 
        // requested URI contains a query.

        client.Headers.Add ("user-agent", "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.2; .NET CLR 1.0.3705;)");

        Stream data = client.OpenRead (args[0]);
        StreamReader reader = new StreamReader (data);
        string s = reader.ReadToEnd ();
        Console.WriteLine (s);
        data.Close ();
        reader.Close ();
    }
}


.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library
  • WebPermission 

    to access the requested URI or any URI that the request is redirected to. Associated enumeration: Connect.

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.