WebClient Class (System.Net)

WebClient Class

.NET Framework Class Library

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)

Syntax

Visual Basic (Declaration)

<ComVisibleAttribute(True)> _
Public Class WebClient
    Inherits Component

Visual Basic (Usage)

Dim instance As WebClient

[ComVisibleAttribute(true)] 
public class WebClient : Component

C++

[ComVisibleAttribute(true)] 
public ref class WebClient : public Component

/** @attribute ComVisibleAttribute(true) */ 
public class WebClient extends Component

JScript

ComVisibleAttribute(true) 
public class WebClient extends Component

Remarks

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.

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

Example

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

Visual Basic

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

C++

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

.NET Framework Security

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

Inheritance Hierarchy

System.Object
   System.MarshalByRefObject
     System.ComponentModel.Component
      System.Net.WebClient

Thread Safety

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

Platforms

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

Version Information

.NET Framework

Supported in: 2.0, 1.1, 1.0

Reference

WebClient Members
System.Net Namespace
WebRequest
WebResponse
HttpWebRequest Class
HttpWebResponse Class