WebClient.DownloadFileAsync 方法

定義

命名空間:

System.Net

組件:

System.Net.WebClient.dll

將指定的資源下載到本機檔案作為異步操作。 這些方法不會封鎖呼叫線程。

多載

DownloadFileAsync(Uri, String)	將具有指定 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫線程。
DownloadFileAsync(Uri, String, Object)	將具有指定 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫線程。

DownloadFileAsync(Uri, String)

來源:

WebClient.cs

將具有指定 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫線程。

public:
 void DownloadFileAsync(Uri ^ address, System::String ^ fileName);

public void DownloadFileAsync (Uri address, string fileName);

member this.DownloadFileAsync : Uri * string -> unit

Public Sub DownloadFileAsync (address As Uri, fileName As String)

參數

address

Uri

要下載之資源的 URI。

fileName

String

要放在本機電腦上的檔名。

例外狀況

ArgumentNullException

address 參數是 null。

-或-

fileName 參數是 null。

WebException

結合 BaseAddress 和 address 所形成的 URI 無效。

-或-

下載資源時發生錯誤。

InvalidOperationException

fileName 所指定的本機檔案正由另一個線程使用。

備註

謹慎

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

此方法會在 address 參數中指定的 URI 下載資源。 下載成功完成時，下載的檔案會命名為本機計算機上的 fileName。 檔案會使用從線程集區自動配置的線程資源，以異步方式下載。 若要在檔案可用時接收通知，請將事件處理程式新增至 DownloadFileCompleted 事件。

此方法不會在下載資源時封鎖呼叫線程。 若要在等候下載完成時封鎖，請使用其中一個 DownloadFile 方法。

在 .NET Framework 和 .NET Core 1.0 中，您可以呼叫 CancelAsync 方法來取消尚未完成的異步操作。

如果 BaseAddress 屬性不是空字串 （“”），且 address 未指定絕對 URI，address 必須是與 BaseAddress 結合的相對 URI，才能形成所要求數據的絕對 URI。 如果 QueryString 屬性不是空字串，則會附加至 address。

此方法會使用 RETR 命令來下載 FTP 資源。 針對 HTTP 資源，會使用 GET 方法。

注意

當您在應用程式中啟用網路追蹤時，此成員會輸出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

在 ASP.NET 頁面中使用這個方法時，如果頁面執行的帳戶沒有存取本機檔案的許可權，您會收到錯誤。

這個方法會儲存在工作中，它會傳回方法同步對應項可以擲回的所有非使用例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用例外狀況，例如 ArgumentException，仍會同步擲回。 如需預存的例外狀況，請參閱 DownloadFile(Uri, String)擲回的例外狀況。

DownloadFileAsync(Uri, String, Object)

來源:

WebClient.cs

將具有指定 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫線程。

public:
 void DownloadFileAsync(Uri ^ address, System::String ^ fileName, System::Object ^ userToken);

public void DownloadFileAsync (Uri address, string fileName, object? userToken);

member this.DownloadFileAsync : Uri * string * obj -> unit

Public Sub DownloadFileAsync (address As Uri, fileName As String, userToken As Object)

參數

address

Uri

要下載之資源的 URI。

fileName

String

要放在本機電腦上的檔名。

userToken

Object

使用者定義對象，傳遞至異步操作完成時叫用的方法。

例外狀況

ArgumentNullException

address 參數是 null。

-或-

fileName 參數是 null。

WebException

結合 BaseAddress 和 address 所形成的 URI 無效。

-或-

下載資源時發生錯誤。

InvalidOperationException

fileName 所指定的本機檔案正由另一個線程使用。

備註

謹慎

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

此方法會在 address 參數中指定的 URI 下載資源。 下載成功完成時，下載的檔案會命名為本機計算機上的 fileName。 檔案會使用從線程集區自動配置的線程資源，以異步方式下載。 若要在檔案可用時接收通知，請將事件處理程式新增至 DownloadFileCompleted 事件。

此方法不會在下載資源時封鎖呼叫線程。 若要在等候下載完成時封鎖，請使用其中一個 DownloadFile 方法。

在 .NET Framework 和 .NET Core 1.0 中，您可以呼叫 CancelAsync 方法來取消尚未完成的異步操作。

如果 BaseAddress 屬性不是空字串 （“”），且 address 未指定絕對 URI，address 必須是與 BaseAddress 結合的相對 URI，才能形成所要求數據的絕對 URI。 如果 QueryString 屬性不是空字串，則會附加至 address。

此方法會使用 RETR 命令來下載 FTP 資源。 針對 HTTP 資源，會使用 GET 方法。

注意

當您在應用程式中啟用網路追蹤時，此成員會輸出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

在 ASP.NET 頁面中使用這個方法時，如果頁面執行的帳戶沒有存取本機檔案的許可權，您會收到錯誤。