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
[ComVisibleAttribute(true)]
public ref class WebClient : Component
[<ComVisibleAttribute(true)>]
type WebClient = 
    class
        inherit Component
    end
<ComVisibleAttribute(True)>
Public Class WebClient
	Inherits Component
NameDescription
System_CAPS_pubmethod WebClient

Initializes a new instance of the WebClient class.

NameDescription
System_CAPS_pubproperty

Obsolete.Gets or sets a value that indicates whether to buffer the data read from the Internet resource for a WebClient instance.

System_CAPS_pubproperty

Obsolete.Gets or sets a value that indicates whether to buffer the data written to the Internet resource for a WebClient instance.

System_CAPS_pubproperty

Gets or sets the base URI for requests made by a WebClient.

System_CAPS_pubproperty

Gets or sets the application's cache policy for any resources obtained by this WebClient instance using WebRequest objects.

System_CAPS_protproperty

Gets a value indicating whether the component can raise an event.(Inherited from Component.)

System_CAPS_pubproperty

Gets the IContainer that contains the Component.(Inherited from Component.)

System_CAPS_pubproperty

Gets or sets the network credentials that are sent to the host and used to authenticate the request.

System_CAPS_protproperty

Gets a value that indicates whether the Component is currently in design mode.(Inherited from Component.)

System_CAPS_pubproperty

Gets and sets the Encoding used to upload and download strings.

System_CAPS_protproperty

Gets the list of event handlers that are attached to this Component.(Inherited from Component.)

System_CAPS_pubproperty

Gets or sets a collection of header name/value pairs associated with the request.

System_CAPS_pubproperty

Gets whether a Web request is in progress.

System_CAPS_pubproperty

Gets or sets the proxy used by this WebClient object.

System_CAPS_pubproperty

Gets or sets a collection of query name/value pairs associated with the request.

System_CAPS_pubproperty

Gets a collection of header name/value pairs associated with the response.

System_CAPS_pubproperty

Gets or sets the ISite of the Component.(Inherited from Component.)

System_CAPS_pubproperty

Gets or sets a Boolean value that controls whether the are sent with requests.

NameDescription
System_CAPS_pubmethod CancelAsync

Cancels a pending asynchronous operation.

System_CAPS_pubmethod CreateObjRef

Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.(Inherited from MarshalByRefObject.)

System_CAPS_pubmethod Dispose

Releases all resources used by the Component.(Inherited from Component.)

System_CAPS_protmethod Dispose

Releases the unmanaged resources used by the Component and optionally releases the managed resources.(Inherited from Component.)

System_CAPS_pubmethod DownloadData

Downloads the resource as a Byte array from the URI specified.

System_CAPS_pubmethod DownloadData

Downloads the resource as a Byte array from the URI specified.

System_CAPS_pubmethod DownloadDataAsync

Downloads the resource as a Byte array from the URI specified as an asynchronous operation.

System_CAPS_pubmethod DownloadDataAsync

Downloads the resource as a Byte array from the URI specified as an asynchronous operation.

System_CAPS_pubmethod DownloadDataTaskAsync

Downloads the resource as a Byte array from the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod DownloadDataTaskAsync

Downloads the resource as a Byte array from the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod DownloadFile

Downloads the resource with the specified URI to a local file.

System_CAPS_pubmethod DownloadFile

Downloads the resource with the specified URI to a local file.

System_CAPS_pubmethod DownloadFileAsync

Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.

System_CAPS_pubmethod DownloadFileAsync

Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.

System_CAPS_pubmethod DownloadFileTaskAsync

Downloads the specified resource to a local file as an asynchronous operation using a task object.

System_CAPS_pubmethod DownloadFileTaskAsync

Downloads the specified resource to a local file as an asynchronous operation using a task object.

System_CAPS_pubmethod DownloadString

Downloads the requested resource as a String. The resource to download is specified as a String containing the URI.

System_CAPS_pubmethod DownloadString

Downloads the requested resource as a String. The resource to download is specified as a Uri.

System_CAPS_pubmethod DownloadStringAsync

Downloads the resource specified as a Uri. This method does not block the calling thread.

System_CAPS_pubmethod DownloadStringAsync

Downloads the specified string to the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod DownloadStringTaskAsync

Downloads the resource as a String from the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod DownloadStringTaskAsync

Downloads the resource as a String from the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod Equals

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethod Finalize

Releases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection.(Inherited from Component.)

System_CAPS_pubmethod GetHashCode

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethod GetLifetimeService

Retrieves the current lifetime service object that controls the lifetime policy for this instance.(Inherited from MarshalByRefObject.)

System_CAPS_protmethod GetService

Returns an object that represents a service provided by the Component or by its Container.(Inherited from Component.)

System_CAPS_pubmethod GetType

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_protmethod GetWebRequest

Returns a WebRequest object for the specified resource.

System_CAPS_protmethod GetWebResponse

Returns the WebResponse for the specified WebRequest.

System_CAPS_protmethod GetWebResponse

Returns the WebResponse for the specified WebRequest using the specified IAsyncResult.

System_CAPS_pubmethod InitializeLifetimeService

Obtains a lifetime service object to control the lifetime policy for this instance.(Inherited from MarshalByRefObject.)

System_CAPS_protmethod MemberwiseClone

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethod MemberwiseClone

Creates a shallow copy of the current MarshalByRefObject object.(Inherited from MarshalByRefObject.)

System_CAPS_protmethod OnDownloadDataCompleted

Raises the DownloadDataCompleted event.

System_CAPS_protmethod OnDownloadFileCompleted

Raises the DownloadFileCompleted event.

System_CAPS_protmethod OnDownloadProgressChanged

Raises the DownloadProgressChanged event.

System_CAPS_protmethod OnDownloadStringCompleted

Raises the DownloadStringCompleted event.

System_CAPS_protmethod OnOpenReadCompleted

Raises the OpenReadCompleted event.

System_CAPS_protmethod OnOpenWriteCompleted

Raises the OpenWriteCompleted event.

System_CAPS_protmethod OnUploadDataCompleted

Raises the UploadDataCompleted event.

System_CAPS_protmethod OnUploadFileCompleted

Raises the UploadFileCompleted event.

System_CAPS_protmethod OnUploadProgressChanged

Raises the UploadProgressChanged event.

System_CAPS_protmethod OnUploadStringCompleted

Raises the UploadStringCompleted event.

System_CAPS_protmethod OnUploadValuesCompleted

Raises the UploadValuesCompleted event.

System_CAPS_protmethod OnWriteStreamClosed

Obsolete.Raises the WriteStreamClosed event.

System_CAPS_pubmethod OpenRead

Opens a readable stream for the data downloaded from a resource with the URI specified as a String.

System_CAPS_pubmethod OpenRead

Opens a readable stream for the data downloaded from a resource with the URI specified as a Uri

System_CAPS_pubmethod OpenReadAsync

Opens a readable stream containing the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod OpenReadAsync

Opens a readable stream containing the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod OpenReadTaskAsync

Opens a readable stream containing the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod OpenReadTaskAsync

Opens a readable stream containing the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod OpenWrite

Opens a stream for writing data to the specified resource.

System_CAPS_pubmethod OpenWrite

Opens a stream for writing data to the specified resource, using the specified method.

System_CAPS_pubmethod OpenWrite

Opens a stream for writing data to the specified resource.

System_CAPS_pubmethod OpenWrite

Opens a stream for writing data to the specified resource, by using the specified method.

System_CAPS_pubmethod OpenWriteAsync

Opens a stream for writing data to the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod OpenWriteAsync

Opens a stream for writing data to the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod OpenWriteAsync

Opens a stream for writing data to the specified resource, using the specified method. This method does not block the calling thread.

System_CAPS_pubmethod OpenWriteTaskAsync

Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod OpenWriteTaskAsync

Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod OpenWriteTaskAsync

Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod OpenWriteTaskAsync

Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod ToString

Returns a String containing the name of the Component, if any. This method should not be overridden.(Inherited from Component.)

System_CAPS_pubmethod UploadData

Uploads a data buffer to a resource identified by a URI.

System_CAPS_pubmethod UploadData

Uploads a data buffer to the specified resource, using the specified method.

System_CAPS_pubmethod UploadData

Uploads a data buffer to a resource identified by a URI.

System_CAPS_pubmethod UploadData

Uploads a data buffer to the specified resource, using the specified method.

System_CAPS_pubmethod UploadDataAsync

Uploads a data buffer to a resource identified by a URI, using the POST method. This method does not block the calling thread.

System_CAPS_pubmethod UploadDataAsync

Uploads a data buffer to a resource identified by a URI, using the specified method. This method does not block the calling thread.

System_CAPS_pubmethod UploadDataAsync

Uploads a data buffer to a resource identified by a URI, using the specified method and identifying token.

System_CAPS_pubmethod UploadDataTaskAsync

Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadDataTaskAsync

Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadDataTaskAsync

Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadDataTaskAsync

Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadFile

Uploads the specified local file to a resource with the specified URI.

System_CAPS_pubmethod UploadFile

Uploads the specified local file to the specified resource, using the specified method.

System_CAPS_pubmethod UploadFile

Uploads the specified local file to a resource with the specified URI.

System_CAPS_pubmethod UploadFile

Uploads the specified local file to the specified resource, using the specified method.

System_CAPS_pubmethod UploadFileAsync

Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.

System_CAPS_pubmethod UploadFileAsync

Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.

System_CAPS_pubmethod UploadFileAsync

Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.

System_CAPS_pubmethod UploadFileTaskAsync

Uploads the specified local file to a resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadFileTaskAsync

Uploads the specified local file to a resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadFileTaskAsync

Uploads the specified local file to a resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadFileTaskAsync

Uploads the specified local file to a resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadString

Uploads the specified string to the specified resource, using the POST method.

System_CAPS_pubmethod UploadString

Uploads the specified string to the specified resource, using the specified method.

System_CAPS_pubmethod UploadString

Uploads the specified string to the specified resource, using the POST method.

System_CAPS_pubmethod UploadString

Uploads the specified string to the specified resource, using the specified method.

System_CAPS_pubmethod UploadStringAsync

Uploads the specified string to the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod UploadStringAsync

Uploads the specified string to the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod UploadStringAsync

Uploads the specified string to the specified resource. This method does not block the calling thread.

System_CAPS_pubmethod UploadStringTaskAsync

Uploads the specified string to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadStringTaskAsync

Uploads the specified string to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadStringTaskAsync

Uploads the specified string to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadStringTaskAsync

Uploads the specified string to the specified resource as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadValues

Uploads the specified name/value collection to the resource identified by the specified URI.

System_CAPS_pubmethod UploadValues

Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.

System_CAPS_pubmethod UploadValues

Uploads the specified name/value collection to the resource identified by the specified URI.

System_CAPS_pubmethod UploadValues

Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.

System_CAPS_pubmethod UploadValuesAsync

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.

System_CAPS_pubmethod UploadValuesAsync

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.

System_CAPS_pubmethod UploadValuesAsync

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.

System_CAPS_pubmethod UploadValuesTaskAsync

Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadValuesTaskAsync

Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadValuesTaskAsync

Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.

System_CAPS_pubmethod UploadValuesTaskAsync

Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.

NameDescription
System_CAPS_pubevent Disposed

Occurs when the component is disposed by a call to the Dispose method. (Inherited from Component.)

System_CAPS_pubevent DownloadDataCompleted

Occurs when an asynchronous data download operation completes.

System_CAPS_pubevent DownloadFileCompleted

Occurs when an asynchronous file download operation completes.

System_CAPS_pubevent DownloadProgressChanged

Occurs when an asynchronous download operation successfully transfers some or all of the data.

System_CAPS_pubevent DownloadStringCompleted

Occurs when an asynchronous resource-download operation completes.

System_CAPS_pubevent OpenReadCompleted

Occurs when an asynchronous operation to open a stream containing a resource completes.

System_CAPS_pubevent OpenWriteCompleted

Occurs when an asynchronous operation to open a stream to write data to a resource completes.

System_CAPS_pubevent UploadDataCompleted

Occurs when an asynchronous data-upload operation completes.

System_CAPS_pubevent UploadFileCompleted

Occurs when an asynchronous file-upload operation completes.

System_CAPS_pubevent UploadProgressChanged

Occurs when an asynchronous upload operation successfully transfers some or all of the data.

System_CAPS_pubevent UploadStringCompleted

Occurs when an asynchronous string-upload operation completes.

System_CAPS_pubevent UploadValuesCompleted

Occurs when an asynchronous upload of a name/value collection completes.

System_CAPS_pubevent WriteStreamClosed

Obsolete.Occurs when an asynchronous operation to write data to a resource using a write stream is closed.

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 WebRequestRegisterPrefix method.

System_CAPS_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 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.

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 ();
    }
}
Imports System
Imports System.Net
Imports System.IO



Public Class Test

    Public Shared Sub Main(args() As String)
        If args Is Nothing OrElse args.Length = 0 Then
            Throw New ApplicationException("Specify the URI of the resource to retrieve.")
        End If
        Dim client As 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;)")

        Dim data As Stream = client.OpenRead(args(0))
        Dim reader As New StreamReader(data)
        Dim s As String = reader.ReadToEnd()
        Console.WriteLine(s)
        data.Close()
        reader.Close()
    End Sub 'Main
End Class 'Test
#using <System.dll>

using namespace System;
using namespace System::Net;
using namespace System::IO;
int main()
{
   array<String^>^args = Environment::GetCommandLineArgs();
   if ( args == nullptr || args->Length == 1 )
   {
      throw gcnew ApplicationException( "Specify the URI of the resource to retrieve." );
   }

   WebClient^ client = gcnew 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[ 1 ] );
   StreamReader^ reader = gcnew StreamReader( data );
   String^ s = reader->ReadToEnd();
   Console::WriteLine( s );
   data->Close();
   reader->Close();
}
WebPermission

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

.NET Framework
Available since 1.1
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top