匯出 (0) 列印
全部展開
本文章是由機器翻譯。 將指標移到文章內的文字上方即可查看原文。 其他資訊。
譯文
原文

FtpWebRequest 類別

實作檔案傳輸通訊協定 (FTP) 用戶端。

命名空間:  System.Net
組件:  System (在 System.dll 中)

public sealed class FtpWebRequest : WebRequest

FtpWebRequest 類型會公開下列成員。

  名稱描述
公用屬性AuthenticationLevel取得或設定值,指出用於這個要求的驗證和模擬等級。 (繼承自 WebRequest)。
公用屬性CachePolicy取得或設定這個要求的快取原則。 (繼承自 WebRequest)。
公用屬性ClientCertificates取得或設定用來建立與 FTP 伺服器之加密連接的憑證。
公用屬性ConnectionGroupName取得或設定連接群組的名稱,這個連接群組包含用來傳送目前要求的服務點。 (覆寫 WebRequest.ConnectionGroupName。)
公用屬性ContentLength基礎架構。取得或設定 FtpWebRequest 類別忽略的值。 (覆寫 WebRequest.ContentLength。)
公用屬性ContentOffset取得或設定這個要求所下載之檔案的位元組位移。
公用屬性ContentType基礎架構。永遠擲回 NotSupportedException (覆寫 WebRequest.ContentType。)
公用屬性CreatorInstance 已過時。在子代類別中覆寫時,取得衍生自 IWebRequestCreate 類別的 Factory 物件,用來建立為了要求指定的 URI 執行個體化的 WebRequest (繼承自 WebRequest)。
公用屬性Credentials取得或設定用來與 FTP 伺服器通訊的認證。 (覆寫 WebRequest.Credentials。)
公用屬性靜態成員DefaultCachePolicy為所有 FTP 要求,定義預設的快取原則。
公用屬性EnableSsl取得或設定 Boolean,指定是否應使用 SSL 連接。
公用屬性Headers基礎架構。取得空的 WebHeaderCollection 物件。 (覆寫 WebRequest.Headers。)
公用屬性ImpersonationLevel取得或設定目前要求的模擬等級。 (繼承自 WebRequest)。
公用屬性KeepAlive取得或設定 Boolean 值,指定在要求完成之後,與 FTP 伺服器的控制連接是否關閉。
公用屬性Method取得或設定要傳送至 FTP 伺服器的命令。 (覆寫 WebRequest.Method。)
公用屬性PreAuthenticate基礎架構。永遠擲回 NotSupportedException (覆寫 WebRequest.PreAuthenticate。)
公用屬性Proxy取得或設定用來與 FTP 伺服器通訊的 Proxy。 (覆寫 WebRequest.Proxy。)
公用屬性ReadWriteTimeout取得或設定讀取或寫入資料流的逾時。
公用屬性RenameTo取得或設定重新命名檔案的新名稱。
公用屬性RequestUri取得這個執行個體所要求的 URI。 (覆寫 WebRequest.RequestUri。)
公用屬性ServicePoint取得用來連接到 FTP 伺服器的 ServicePoint 物件。
公用屬性Timeout取得或設定等待要求的毫秒數。 (覆寫 WebRequest.Timeout。)
公用屬性UseBinary取得或設定 Boolean 值,指定檔案傳輸的資料型別。
公用屬性UseDefaultCredentials基礎架構。永遠擲回 NotSupportedException (覆寫 WebRequest.UseDefaultCredentials。)
公用屬性UsePassive取得或設定用戶端應用程式之資料傳輸處理序的行為。
回頁首

  名稱描述
公用方法Abort結束非同步 FTP 作業。 (覆寫 WebRequest.Abort()。)
公用方法BeginGetRequestStream開始非同步開啟要求的內容資料流,以進行寫入。 (覆寫 WebRequest.BeginGetRequestStream(AsyncCallback, Object)。)
公用方法BeginGetResponse開始以非同步的方式傳送要求,並且接收來自 FTP 伺服器的回應。 (覆寫 WebRequest.BeginGetResponse(AsyncCallback, Object)。)
公用方法CreateObjRef建立包含所有相關資訊的物件,這些資訊是產生用來與遠端物件通訊的所需 Proxy。 (繼承自 MarshalByRefObject)。
公用方法EndGetRequestStream結束由 BeginGetRequestStream 所啟動的暫止非同步作業。 (覆寫 WebRequest.EndGetRequestStream(IAsyncResult)。)
公用方法EndGetResponse結束由 BeginGetResponse 所啟動的暫止非同步作業。 (覆寫 WebRequest.EndGetResponse(IAsyncResult)。)
公用方法Equals(Object)判斷指定的物件是否等於目前物件。 (繼承自 Object)。
公用方法GetHashCode做為預設雜湊函式。 (繼承自 Object)。
公用方法GetLifetimeService擷取控制這個執行個體存留期 (Lifetime) 原則的目前存留期服務物件。 (繼承自 MarshalByRefObject)。
公用方法GetRequestStream擷取用來上載資料至 FTP 伺服器的資料流。 (覆寫 WebRequest.GetRequestStream()。)
公用方法GetRequestStreamAsync在子代類別中覆寫時,傳回用來將資料寫入網際網路資源的 Stream,做為非同步作業。 (繼承自 WebRequest)。
公用方法GetResponse傳回 FTP 伺服器回應。 (覆寫 WebRequest.GetResponse()。)
公用方法GetResponseAsync在子代類別中覆寫時,傳回對網際網路要求的回應,做為非同步作業。 (繼承自 WebRequest)。
公用方法GetType取得目前執行個體的 Type (繼承自 Object)。
公用方法InitializeLifetimeService取得存留期服務物件來控制這個執行個體的存留期原則。 (繼承自 MarshalByRefObject)。
公用方法ToString傳回表示目前物件的字串。 (繼承自 Object)。
回頁首

  名稱描述
明確介面實作私用方法ISerializable.GetObjectData基礎架構。在子代類別中覆寫時,以序列化 WebRequest 所需的資料填入 SerializationInfo 執行個體。 (繼承自 WebRequest)。
回頁首

若要取得 FtpWebRequest 的執行個體,請使用 Create 方法。 您也可以使用 WebClient 類別,上載資料至 FTP 伺服器並從 FTP 伺服器下載資訊。 只要使用以上任何一種方法,當您指定使用 FTP 配置 (例如,"ftp://contoso.com") 的網路資源時,FtpWebRequest 類別都能讓您以程式設計方式與 FTP 伺服器互動。

這個 URI 可為相對或絕對的。 如果 URI 的格式為 "ftp://contoso.com/%2fpath" (%2f 是逸出字元 '/'),則 URI 是絕對的,目前的目錄為 /path 不過,如果 URI 的格式為 "ftp://contoso.com/path",則首先 .NET Framework 會登入 FTP 伺服器 (使用 Credentials 屬性設定的使用者名稱和密碼),然後將目前的目錄設為 <UserLoginDirectory>/path

您必須有伺服器的有效使用者名稱和密碼,或者伺服器必須允許匿名登入。 您可以設定 Credentials 屬性,指定連接到伺服器時使用的認證,或將它們包含在 URI 的 UserInfo 部分,傳遞至 Create 方法。 如果在 URI 中包含 UserInfo 資訊,Credentials 屬性會設為具有指定使用者名稱和密碼資訊的新網路認證。

注意事項警告

除非 EnableSsl 屬性為 true,否則所有資料和命令 (包括使用者名稱和密碼資訊) 都會以純文字方式傳送至伺服器。 監視網路流量的任何人,都可以檢視這些認證並使用它們來連接到伺服器。 如果連接的 FTP 伺服器需要認證並支援 Secure Sockets Layer (SSL),您就應該將 EnableSsl 設為 true

您必須擁有存取 FTP 資源的 WebPermission,否則會擲回 SecurityException 例外狀況。

請將 Method 屬性設定為 WebRequestMethods.Ftp 結構中定義的值,指定要傳送至伺服器的 FTP 命令。 若要傳輸文字資料,請將 UseBinary 屬性預設值 (true) 變更為 false 如需詳細資訊和限制,請參閱 Method

使用 FtpWebRequest 物件,將檔案上載至伺服器時,您必須將檔案內容寫入要求資料流 (呼叫 GetRequestStream 方法或其非同步的 BeginGetRequestStreamEndGetRequestStream 對應方法取得此資料流)。 您必須先寫入資料流、關閉資料流,然後傳送要求。

呼叫 GetResponse 方法或其非同步的 BeginGetResponseEndGetResponse 對應方法,將要求傳送至伺服器。 所要求的作業完成時,會傳回 FtpWebResponse 物件。 FtpWebResponse 物件會提供作業狀態以及從伺服器下載的任何資料。

您可以使用 ReadWriteTimeout 屬性,設定讀取或寫入伺服器的逾時值。 如果已經超過逾時期限,呼叫方法會擲回 WebException,並將 WebExceptionStatus 設為 Timeout

從 FTP 伺服器下載檔案時,如果命令成功,在回應物件的資料流中會提供所要求的檔案內容。 您可以呼叫 GetResponseStream 方法,存取這個資料流。 如需詳細資訊,請參閱 FtpWebResponse

如果已設定 Proxy 屬性,無論是直接設定或在組態檔中設定,與 FTP 伺服器的通訊都會透過指定的 Proxy 進行。 如果指定的 Proxy 是 HTTP Proxy,只支援 DownloadFileListDirectoryListDirectoryDetails 命令。

只快取下載的二進位內容,亦即,使用 UseBinary 屬性設為 trueDownloadFile 命令所收到的內容。

在可能的情況下,多個 FtpWebRequest 會重複使用現有的連接。

如需 FTP 通訊協定的詳細資訊,請參閱 RFC 959<File Transfer Protocol>,網址為 http://www.rfc-editor.org/

下列程式碼範例將示範如何刪除 FTP 伺服器上的檔案。


public static bool DeleteFileOnServer(Uri serverUri)
{
    // The serverUri parameter should use the ftp:// scheme.
    // It contains the name of the server file that is to be deleted.
    // Example: ftp://contoso.com/someFile.txt.
    // 

    if (serverUri.Scheme != Uri.UriSchemeFtp)
    {
        return false;
    }
    // Get the object used to communicate with the server.
    FtpWebRequest request = (FtpWebRequest)WebRequest.Create(serverUri);
    request.Method = WebRequestMethods.Ftp.DeleteFile;

    FtpWebResponse response = (FtpWebResponse) request.GetResponse();
    Console.WriteLine("Delete status: {0}",response.StatusDescription);  
    response.Close();
    return true;
}


下列程式碼範例將示範如何使用 WebClient 類別,從 FTP 伺服器下載檔案。


public static bool DisplayFileFromServer(Uri serverUri)
{
    // The serverUri parameter should start with the ftp:// scheme.
    if (serverUri.Scheme != Uri.UriSchemeFtp)
    {
        return false;
    }
    // Get the object used to communicate with the server.
    WebClient request = new WebClient();

    // This example assumes the FTP site uses anonymous logon.
    request.Credentials = new NetworkCredential ("anonymous","janeDoe@contoso.com");
    try 
    {
        byte [] newFileData = request.DownloadData (serverUri.ToString());
        string fileString = System.Text.Encoding.UTF8.GetString(newFileData);
        Console.WriteLine(fileString);
    }
    catch (WebException e)
    {
        Console.WriteLine(e.ToString());
    }
    return true;
}


下列程式碼範例將示範如何使用非同步作業,將檔案上載至 FTP 伺服器。


using System;
using System.Net;
using System.Threading;

using System.IO;
namespace Examples.System.Net
{
    public class FtpState
    {
        private ManualResetEvent wait;
        private FtpWebRequest request;
        private string fileName;
        private Exception operationException = null;
        string status;

        public FtpState()
        {
            wait = new ManualResetEvent(false);
        }

        public ManualResetEvent OperationComplete
        {
            get {return wait;}
        }

        public FtpWebRequest Request
        {
            get {return request;}
            set {request = value;}
        }

        public string FileName
        {
            get {return fileName;}
            set {fileName = value;}
        }
        public Exception OperationException
        {
            get {return operationException;}
            set {operationException = value;}
        }
        public string StatusDescription
        {
            get {return status;}
            set {status = value;}
        }
    }
    public class AsynchronousFtpUpLoader
    {  
        // Command line arguments are two strings:
        // 1. The url that is the name of the file being uploaded to the server.
        // 2. The name of the file on the local machine.
        //
        public static void Main(string[] args)
        {
            // Create a Uri instance with the specified URI string.
            // If the URI is not correctly formed, the Uri constructor
            // will throw an exception.
            ManualResetEvent waitObject;

            Uri target = new Uri (args[0]);
            string fileName = args[1];
            FtpState state = new FtpState();
            FtpWebRequest request = (FtpWebRequest)WebRequest.Create(target);
            request.Method = WebRequestMethods.Ftp.UploadFile;

            // This example uses anonymous logon.
            // The request is anonymous by default; the credential does not have to be specified. 
            // The example specifies the credential only to
            // control how actions are logged on the server.

            request.Credentials = new NetworkCredential ("anonymous","janeDoe@contoso.com");

            // Store the request in the object that we pass into the
            // asynchronous operations.
            state.Request = request;
            state.FileName = fileName;

            // Get the event to wait on.
            waitObject = state.OperationComplete;

            // Asynchronously get the stream for the file contents.
            request.BeginGetRequestStream(
                new AsyncCallback (EndGetStreamCallback), 
                state
            );

            // Block the current thread until all operations are complete.
            waitObject.WaitOne();

            // The operations either completed or threw an exception.
            if (state.OperationException != null)
            {
                throw state.OperationException;
            }
            else
            {
                Console.WriteLine("The operation completed - {0}", state.StatusDescription);
            }
        }
        private static void EndGetStreamCallback(IAsyncResult ar)
        {
            FtpState state = (FtpState) ar.AsyncState;

            Stream requestStream = null;
            // End the asynchronous call to get the request stream.
            try
            {
                requestStream = state.Request.EndGetRequestStream(ar);
                // Copy the file contents to the request stream.
                const int bufferLength = 2048;
                byte[] buffer = new byte[bufferLength];
                int count = 0;
                int readBytes = 0;
                FileStream stream = File.OpenRead(state.FileName);
                do
                {
                    readBytes = stream.Read(buffer, 0, bufferLength);
                    requestStream.Write(buffer, 0, readBytes);
                    count += readBytes;
                }
                while (readBytes != 0);
                Console.WriteLine ("Writing {0} bytes to the stream.", count);
                // IMPORTANT: Close the request stream before sending the request.
                requestStream.Close();
                // Asynchronously get the response to the upload request.
                state.Request.BeginGetResponse(
                    new AsyncCallback (EndGetResponseCallback), 
                    state
                );
            } 
            // Return exceptions to the main application thread.
            catch (Exception e)
            {
                Console.WriteLine("Could not get the request stream.");
                state.OperationException = e;
                state.OperationComplete.Set();
                return;
            }

        }

        // The EndGetResponseCallback method  
        // completes a call to BeginGetResponse.
        private static void EndGetResponseCallback(IAsyncResult ar)
        {
            FtpState state = (FtpState) ar.AsyncState;
            FtpWebResponse response = null;
            try 
            {
                response = (FtpWebResponse) state.Request.EndGetResponse(ar);
                response.Close();
                state.StatusDescription = response.StatusDescription;
                // Signal the main application thread that 
                // the operation is complete.
                state.OperationComplete.Set();
            }
            // Return exceptions to the main application thread.
            catch (Exception e)
            {
                Console.WriteLine ("Error getting response.");
                state.OperationException = e;
                state.OperationComplete.Set();
            }
        }
    }
}


.NET Framework

支援版本:4.5、4、3.5、3.0、2.0

.NET Framework Client Profile

支援版本:4、3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (不支援伺服器核心角色), Windows Server 2008 R2 (SP1 (含) 以後版本支援伺服器核心角色,不支援 Itanium)

此.NET Framework 並不支援各種平台的所有版本。如需支援版本的清單,請參閱.NET Framework 系統需求.

這個類型的任何 Publicstatic (在 Visual Basic 中為 Shared) 成員都是安全執行緒。不保證任何執行個體成員是安全執行緒。

社群新增項目

新增
顯示:
© 2015 Microsoft