WebClient 類別

定義

命名空間:

System.Net

組件:

System.Net.WebClient.dll

來源:

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

備註

謹慎

WebRequest、HttpWebRequest、ServicePoint和 WebClient 已經過時，您不應該將它們用於新的開發。 請改用 HttpClient。

WebClient 類別提供一般方法，用來將數據傳送至 URI 所識別的任何本機、內部網路或因特網資源或接收數據。

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 實例的數據。
AllowWriteStreamBuffering	已淘汰. 取得或設定值，這個值表示是否要緩衝寫入 WebClient 實例之因特網資源的數據。
BaseAddress	取得或設定 WebClient所提出要求的基底 URI。
CachePolicy	取得或設定此 WebClient 實例使用 WebRequest 物件取得之任何資源的應用程式快取原則。
CanRaiseEvents	取得值，指出元件是否可以引發事件。 (繼承來源 Component)
Container	取得包含 Component的 IContainer。 (繼承來源 Component)
Credentials	取得或設定傳送至主機並用來驗證要求的網路認證。
DesignMode	取得值，這個值表示 Component 目前是否處於設計模式。 (繼承來源 Component)
Encoding	取得或設定用來上傳和下載字串的 Encoding。
Events	取得附加至這個 Component之事件處理程序的清單。 (繼承來源 Component)
Headers	取得或設定與要求相關聯的標頭名稱/值組集合。
IsBusy	取得 Web 要求是否正在進行中。
Proxy	取得或設定這個 WebClient 物件所使用的 Proxy。
QueryString	取得或設定與要求相關聯的查詢名稱/值組集合。
ResponseHeaders	取得與回應相關聯的標頭名稱/值組集合。
Site	取得或設定 Component的 ISite。 (繼承來源 Component)
UseDefaultCredentials	取得或設定 Boolean 值，這個值會控制是否以要求傳送 DefaultCredentials。

方法

CancelAsync()	取消暫止的異步操作。
CreateObjRef(Type)	建立物件，其中包含產生用來與遠端物件通訊之 Proxy 所需的所有相關信息。 (繼承來源 MarshalByRefObject)
Dispose()	釋放 Component所使用的所有資源。 (繼承來源 Component)
Dispose(Boolean)	釋放 Component 所使用的 Unmanaged 資源，並選擇性地釋放 Managed 資源。 (繼承來源 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)	傳回指定之 WebRequest的 WebResponse。
GetWebResponse(WebRequest, IAsyncResult)	使用指定的 IAsyncResult傳回指定之 WebRequest 的 WebResponse。
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