WebClient 类

定义

命名空间:

System.Net

程序集:

System.Net.WebClient.dll

Source:

WebClient.cs

提供用于将数据发送到由 URI 标识的资源及从这样的资源接收数据的常用方法。

public ref class WebClient : System::ComponentModel::Component

public class WebClient : System.ComponentModel.Component

type WebClient = class
    inherit Component

Public Class WebClient
Inherits Component

继承

Object

MarshalByRefObject

Component

WebClient

示例

下面的代码示例采用资源的 URI，检索它，并显示响应。

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

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.");
        }
        using 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;)");

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

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
        Using 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;)")
            
            Using data As Stream = client.OpenRead(args(0))
                Using reader As New StreamReader(data)
                    Dim s As String = reader.ReadToEnd()
                    Console.WriteLine(s)
                End Using
            End Using
        End Using
    End Sub
End Class

注解

重要

不建议使用 WebClient 类进行新开发。 请改用 System.Net.Http.HttpClient 类。

类 WebClient 提供用于将数据发送到或从 URI 标识的任何本地、Intranet 或 Internet 资源接收数据的常用方法。

类 WebClient 使用 WebRequest 类提供对资源的访问权限。 WebClient实例可以访问使用 方法注册WebRequest.RegisterPrefix的任何WebRequest后代的数据。

注意

默认情况下，.NET Framework支持以 http:、、 https:ftp:和 file: 方案标识符开头的 URI。

下表介绍了 WebClient 将数据上传到资源的方法。

方法	说明
OpenWrite	Stream检索用于将数据发送到资源的 。
OpenWriteAsync	Stream检索用于将数据发送到资源的 ，而不会阻止调用线程。
UploadData	将字节数组发送到资源，并返回包含任何响应的 Byte 数组。
UploadDataAsync	在不 Byte 阻止调用线程的情况下，将数组发送到资源。
UploadFile	将本地文件发送到资源并返回包含任何响应的 Byte 数组。
UploadFileAsync	在不阻止调用线程的情况下，将本地文件发送到资源。
UploadValues	将 发送到 NameValueCollection 资源并返回包含任何响应的 Byte 数组。
UploadValuesAsync	将 发送到 NameValueCollection 资源并返回包含 Byte 任何响应的数组，而不会阻止调用线程。
UploadString	将 发送到 String 资源，并返回包含 String 任何响应的 。
UploadStringAsync	将 发送到 String 资源，而不会阻止调用线程。

下表介绍了 WebClient 从资源下载数据的方法。

方法	说明
OpenRead	以 的形式 Stream返回资源中的数据。
OpenReadAsync	从资源返回数据，而不会阻止调用线程。
DownloadData	从资源下载数据并返回 Byte 数组。
DownloadDataAsync	从资源下载数据并返回 Byte 数组，而不会阻止调用线程。
DownloadFile	将数据从资源下载到本地文件。
DownloadFileAsync	将数据从资源下载到本地文件，而不会阻止调用线程。
DownloadString	String从资源下载 并返回 String。
DownloadStringAsync	从资源下载 ， String 而不会阻止调用线程。

可以使用 CancelAsync 方法尝试取消异步操作。

默认情况下，实例 WebClient 不发送可选的 HTTP 标头。 如果请求需要可选标头，则必须将该标头添加到集合中 Headers 。 例如，若要在响应中保留查询，必须添加用户代理标头。 此外，如果缺少用户代理标头，服务器可能会返回 500 (内部服务器错误) 。

AllowAutoRedirect在实例中WebClient设置为 true 。

继承者说明

派生类应调用 的基类实现 WebClient ，以确保派生类按预期工作。

构造函数

WebClient()

已过时. 初始化 WebClient 类的新实例。

属性

AllowReadStreamBuffering	已过时. 获取或设置一个值，该值指示是否对从某一 WebClient 实例的 Internet 资源读取的数据进行缓冲处理。
AllowWriteStreamBuffering	已过时. 获取或设置一个值，该值指示是否对写入到 WebClient 实例的 Internet 资源的数据进行缓冲处理。
BaseAddress	获取或设置 WebClient 发出请求的基 URI。
CachePolicy	对于此 WebClient 实例使用 WebRequest 对象获得的任何资源，获取或设置应用程序的缓存策略。
CanRaiseEvents	获取一个指示组件是否可以引发事件的值。 (继承自 Component)
Container	获取包含 IContainer 的 Component。 (继承自 Component)
Credentials	获取或设置发送到主机并用于对请求进行身份验证的网络凭据。
DesignMode	获取一个值，用以指示 Component 当前是否处于设计模式。 (继承自 Component)
Encoding	获取或设置用于上传和下载字符串的 Encoding。
Events	获取附加到此 Component 的事件处理程序的列表。 (继承自 Component)
Headers	获取或设置与请求关联的标头名称/值对集合。
IsBusy	了解是否存在进行中的 Web 请求。
Proxy	获取或设置此 WebClient 对象使用的代理。
QueryString	获取或设置与请求关联的查询名称/值对集合。
ResponseHeaders	获取与响应关联的标头名称/值对集合。
Site	获取或设置 Component 的 ISite。 (继承自 Component)
UseDefaultCredentials	获取或设置 Boolean 值，该值控制 DefaultCredentials 是否随请求一起发送。

方法

CancelAsync()	取消一个挂起的异步操作。
CreateObjRef(Type)	创建一个对象，该对象包含生成用于与远程对象进行通信的代理所需的全部相关信息。 (继承自 MarshalByRefObject)
Dispose()	释放由 Component 使用的所有资源。 (继承自 Component)
Dispose(Boolean)	释放由 Component 占用的非托管资源，还可以另外再释放托管资源。 (继承自 Component)
DownloadData(String)	从指定 URI 下载资源作为 Byte 数组。
DownloadData(Uri)	从指定 URI 下载资源作为 Byte 数组。
DownloadDataAsync(Uri)	从指定 URI 中将资源作为 Byte 数组下载以作为异步操作。
DownloadDataAsync(Uri, Object)	从指定 URI 中将资源作为 Byte 数组下载以作为异步操作。
DownloadDataTaskAsync(String)	使用任务对象从指定 URI 中将资源作为 Byte 数组下载以作为异步操作。
DownloadDataTaskAsync(Uri)	使用任务对象从指定 URI 中将资源作为 Byte 数组下载以作为异步操作。
DownloadFile(String, String)	将具有指定 URI 的资源下载到本地文件。
DownloadFile(Uri, String)	将具有指定 URI 的资源下载到本地文件。
DownloadFileAsync(Uri, String)	将具有指定 URI 的资源下载到本地文件。 此方法不会阻止调用线程。
DownloadFileAsync(Uri, String, Object)	将具有指定 URI 的资源下载到本地文件。 此方法不会阻止调用线程。
DownloadFileTaskAsync(String, String)	使用任务对象将指定资源下载到本地文件以作为异步操作。
DownloadFileTaskAsync(Uri, String)	使用任务对象将指定资源下载到本地文件以作为异步操作。
DownloadString(String)	以 String 形式下载请求的资源。 以包含 URI 的 String 的形式指定要下载的资源。
DownloadString(Uri)	以 String 形式下载请求的资源。 以 Uri 形式指定要下载的资源。
DownloadStringAsync(Uri)	下载以 Uri 形式指定的资源。 此方法不会阻止调用线程。
DownloadStringAsync(Uri, Object)	将指定的字符串下载到指定的资源。 此方法不会阻止调用线程。
DownloadStringTaskAsync(String)	使用任务对象从指定 URI 中将资源作为 String 下载以作为异步操作。
DownloadStringTaskAsync(Uri)	使用任务对象从指定 URI 中将资源作为 String 下载以作为异步操作。
Equals(Object)	确定指定对象是否等于当前对象。 (继承自 Object)
GetHashCode()	作为默认哈希函数。 (继承自 Object)
GetLifetimeService()	已过时. 检索控制此实例的生存期策略的当前生存期服务对象。 (继承自 MarshalByRefObject)
GetService(Type)	返回一个对象，该对象表示由 Component 或它的 Container 提供的服务。 (继承自 Component)
GetType()	获取当前实例的 Type。 (继承自 Object)
GetWebRequest(Uri)	为指定资源返回一个 WebRequest 对象。
GetWebResponse(WebRequest)	返回指定 WebResponse 的 WebRequest。
GetWebResponse(WebRequest, IAsyncResult)	使用指定的 WebResponse 获取对指定 WebRequest 的 IAsyncResult。
InitializeLifetimeService()	已过时. 获取生存期服务对象来控制此实例的生存期策略。 (继承自 MarshalByRefObject)
MemberwiseClone()	创建当前 Object 的浅表副本。 (继承自 Object)
MemberwiseClone(Boolean)	创建当前 MarshalByRefObject 对象的浅表副本。 (继承自 MarshalByRefObject)
OnDownloadDataCompleted(DownloadDataCompletedEventArgs)	引发 DownloadDataCompleted 事件。
OnDownloadFileCompleted(AsyncCompletedEventArgs)	引发 DownloadFileCompleted 事件。
OnDownloadProgressChanged(DownloadProgressChangedEventArgs)	引发 DownloadProgressChanged 事件。
OnDownloadStringCompleted(DownloadStringCompletedEventArgs)	引发 DownloadStringCompleted 事件。
OnOpenReadCompleted(OpenReadCompletedEventArgs)	引发 OpenReadCompleted 事件。
OnOpenWriteCompleted(OpenWriteCompletedEventArgs)	引发 OpenWriteCompleted 事件。
OnUploadDataCompleted(UploadDataCompletedEventArgs)	引发 UploadDataCompleted 事件。
OnUploadFileCompleted(UploadFileCompletedEventArgs)	引发 UploadFileCompleted 事件。
OnUploadProgressChanged(UploadProgressChangedEventArgs)	引发 UploadProgressChanged 事件。
OnUploadStringCompleted(UploadStringCompletedEventArgs)	引发 UploadStringCompleted 事件。
OnUploadValuesCompleted(UploadValuesCompletedEventArgs)	引发 UploadValuesCompleted 事件。
OnWriteStreamClosed(WriteStreamClosedEventArgs)	已过时. 引发 WriteStreamClosed 事件。
OpenRead(String)	为从具有 String 指定的 URI 的资源下载的数据打开一个可读的流。
OpenRead(Uri)	为从具有 Uri 指定的 URI 的资源下载的数据打开一个可读的流。
OpenReadAsync(Uri)	打开包含指定资源的可读流。 此方法不会阻止调用线程。
OpenReadAsync(Uri, Object)	打开包含指定资源的可读流。 此方法不会阻止调用线程。
OpenReadTaskAsync(String)	使用任务对象打开包含指定资源的可读流以作为异步操作。
OpenReadTaskAsync(Uri)	使用任务对象打开包含指定资源的可读流以作为异步操作。
OpenWrite(String)	打开一个流以将数据写入指定的资源。
OpenWrite(String, String)	打开一个流以使用指定的方法向指定的资源写入数据。
OpenWrite(Uri)	打开一个流以将数据写入指定的资源。
OpenWrite(Uri, String)	打开一个流以使用指定的方法将数据写入指定的资源。
OpenWriteAsync(Uri)	打开一个流以将数据写入指定的资源。 此方法不会阻止调用线程。
OpenWriteAsync(Uri, String)	打开一个流以将数据写入指定的资源。 此方法不会阻止调用线程。
OpenWriteAsync(Uri, String, Object)	打开一个流以使用指定的方法向指定的资源写入数据。 此方法不会阻止调用线程。
OpenWriteTaskAsync(String)	使用任务对象打开用于将数据写入指定资源的流以作为异步操作。
OpenWriteTaskAsync(String, String)	使用任务对象打开用于将数据写入指定资源的流以作为异步操作。
OpenWriteTaskAsync(Uri)	使用任务对象打开用于将数据写入指定资源的流以作为异步操作。
OpenWriteTaskAsync(Uri, String)	使用任务对象打开用于将数据写入指定资源的流以作为异步操作。
ToString()	返回包含 Component 的名称的 String（如果有）。 不应重写此方法。 (继承自 Component)
UploadData(String, Byte[])	将数据缓冲区上载到由 URI 标识的资源。
UploadData(String, String, Byte[])	使用指定的方法将数据缓冲区上载到指定资源。
UploadData(Uri, Byte[])	将数据缓冲区上载到由 URI 标识的资源。
UploadData(Uri, String, Byte[])	使用指定的方法将数据缓冲区上载到指定资源。
UploadDataAsync(Uri, Byte[])	使用 POST 方法将数据缓冲区上载到由 URI 标识的资源。 此方法不会阻止调用线程。
UploadDataAsync(Uri, String, Byte[])	使用指定的方法将数据缓冲区上载到由 URI 标识的资源。 此方法不会阻止调用线程。
UploadDataAsync(Uri, String, Byte[], Object)	使用指定的方法和标识标记将数据缓冲区上载到由 URI 标识的资源。
UploadDataTaskAsync(String, Byte[])	使用任务对象将包含 Byte 数组的数据缓冲区上载到指定 URI 以作为异步操作。
UploadDataTaskAsync(String, String, Byte[])	使用任务对象将包含 Byte 数组的数据缓冲区上载到指定 URI 以作为异步操作。
UploadDataTaskAsync(Uri, Byte[])	使用任务对象将包含 Byte 数组的数据缓冲区上载到指定 URI 以作为异步操作。
UploadDataTaskAsync(Uri, String, Byte[])	使用任务对象将包含 Byte 数组的数据缓冲区上载到指定 URI 以作为异步操作。
UploadFile(String, String)	将指定的本地文件上载到具有指定 URI 的资源。
UploadFile(String, String, String)	使用指定的方法将指定的本地文件上载到指定的资源。
UploadFile(Uri, String)	将指定的本地文件上载到具有指定 URI 的资源。
UploadFile(Uri, String, String)	使用指定的方法将指定的本地文件上载到指定的资源。
UploadFileAsync(Uri, String)	使用 POST 方法将指定的本地文件上载到指定的资源。 此方法不会阻止调用线程。
UploadFileAsync(Uri, String, String)	使用 POST 方法将指定的本地文件上载到指定的资源。 此方法不会阻止调用线程。
UploadFileAsync(Uri, String, String, Object)	使用 POST 方法将指定的本地文件上载到指定的资源。 此方法不会阻止调用线程。
UploadFileTaskAsync(String, String)	使用任务对象将指定本地文件上载到资源以作为异步操作。
UploadFileTaskAsync(String, String, String)	使用任务对象将指定本地文件上载到资源以作为异步操作。
UploadFileTaskAsync(Uri, String)	使用任务对象将指定本地文件上载到资源以作为异步操作。
UploadFileTaskAsync(Uri, String, String)	使用任务对象将指定本地文件上载到资源以作为异步操作。
UploadString(String, String)	使用 POST 方法将指定的字符串上载到指定的资源。
UploadString(String, String, String)	使用指定的方法将指定的字符串上载到指定的资源。
UploadString(Uri, String)	使用 POST 方法将指定的字符串上载到指定的资源。
UploadString(Uri, String, String)	使用指定的方法将指定的字符串上载到指定的资源。
UploadStringAsync(Uri, String)	将指定的字符串上载到指定的资源。 此方法不会阻止调用线程。
UploadStringAsync(Uri, String, String)	将指定的字符串上载到指定的资源。 此方法不会阻止调用线程。
UploadStringAsync(Uri, String, String, Object)	将指定的字符串上载到指定的资源。 此方法不会阻止调用线程。
UploadStringTaskAsync(String, String)	使用任务对象将指定字符串上载到指定资源以作为异步操作。
UploadStringTaskAsync(String, String, String)	使用任务对象将指定字符串上载到指定资源以作为异步操作。
UploadStringTaskAsync(Uri, String)	使用任务对象将指定字符串上载到指定资源以作为异步操作。
UploadStringTaskAsync(Uri, String, String)	使用任务对象将指定字符串上载到指定资源以作为异步操作。
UploadValues(String, NameValueCollection)	将指定的名称/值集合上载到指定的 URI 所标识的资源。
UploadValues(String, String, NameValueCollection)	使用指定的方法将指定的名称/值集合上载到指定的 URI 所标识的资源。
UploadValues(Uri, NameValueCollection)	将指定的名称/值集合上载到指定的 URI 所标识的资源。
UploadValues(Uri, String, NameValueCollection)	使用指定的方法将指定的名称/值集合上载到指定的 URI 所标识的资源。
UploadValuesAsync(Uri, NameValueCollection)	将指定的名称/值集合中的数据上载到由指定的 URI 标识的资源。 此方法不会阻止调用线程。
UploadValuesAsync(Uri, String, NameValueCollection)	使用指定的方法将指定的名称/值集合中的数据上载到由指定的 URI 标识的资源。 此方法不会阻止调用线程。
UploadValuesAsync(Uri, String, NameValueCollection, Object)	使用指定的方法将指定的名称/值集合中的数据上载到由指定的 URI 标识的资源。 此方法不会阻止调用线程，并允许调用方将对象传递给操作完成时所调用的方法。
UploadValuesTaskAsync(String, NameValueCollection)	使用任务对象将指定的名称/值集合上载到由指定 URI 标识的资源以作为异步操作。
UploadValuesTaskAsync(String, String, NameValueCollection)	使用任务对象将指定的名称/值集合上载到由指定 URI 标识的资源以作为异步操作。
UploadValuesTaskAsync(Uri, NameValueCollection)	使用任务对象将指定的名称/值集合上载到由指定 URI 标识的资源以作为异步操作。
UploadValuesTaskAsync(Uri, String, NameValueCollection)	使用任务对象将指定的名称/值集合上载到由指定 URI 标识的资源以作为异步操作。

事件

Disposed	在通过调用 Dispose() 方法释放组件时发生。 (继承自 Component)
DownloadDataCompleted	在异步数据下载操作完成时发生。
DownloadFileCompleted	在异步文件下载操作完成时发生。
DownloadProgressChanged	在异步下载操作成功传输部分或全部数据后发生。
DownloadStringCompleted	在异步资源下载操作完成时发生。
OpenReadCompleted	在以下异步操作完成时发生，该操作打开包含某个资源的流。
OpenWriteCompleted	在打开流以将数据写入资源的异步操作完成时发生。
UploadDataCompleted	在异步数据上载操作完成时发生。
UploadFileCompleted	在异步文件上载操作完成时发生。
UploadProgressChanged	在异步上载操作成功转换部分或全部数据后发生。
UploadStringCompleted	在异步字符串上载操作完成时发生。
UploadValuesCompleted	在名称/值集合的异步上载完成时发生。
WriteStreamClosed	已过时. 在使用写入流将数据写入资源的异步操作结束时发生。

另请参阅

• WebRequest
• WebResponse
• HttpWebRequest
• HttpWebResponse