WebClient 類別

定義

命名空間:

System.Net

組件:

System.Net.WebClient.dll

提供從 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 所識別的任何本機、內部網路或網際網路資源或接收資料。

類別 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 設定為 true 實例中的 WebClient 。

給繼承者的注意事項

衍生類別應該呼叫 的基類實 WebClient 作，以確保衍生類別如預期般運作。

建構函式

WebClient()

已淘汰. 初始化 WebClient 類別的新執行個體。

屬性

AllowReadStreamBuffering	已淘汰. 取得或設定值，這個值表示是否要為 WebClient 執行個體緩衝處理從網際網路資源讀取的資料。
AllowWriteStreamBuffering	已淘汰. 取得或設定值，這個值表示是否要為 WebClient 執行個體緩衝處理寫入網際網路資源的資料。
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 物件使用的 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()	已淘汰. 擷取控制這個執行個體存留期 (Lifetime) 原則的目前存留期服務物件。 (繼承來源 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)	使用指定的方法並辨識語彙基元 (Token)，將資料緩衝區上載至由 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