System 2.0.0.0 4.0.0.0 System.Net.WebRequest

To obtain an instance of , use the method. You can also use the class to upload and download information from an FTP server. Using either of these approaches, when you specify a network resource that uses the FTP scheme (for example, "ftp://contoso.com") the class provides the ability to programmatically interact with FTP servers.

The URI may be relative or absolute. If the URI is of the form "ftp://contoso.com/%2fpath" (%2f is an escaped '/'), then the URI is absolute, and the current directory is /path. If, however, the URI is of the form "ftp://contoso.com/path", first the .NET Framework logs into the FTP server (using the user name and password set by the property), then the current directory is set to <UserLoginDirectory>/path.

You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information.

Unless the property is true, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports Secure Sockets Layer (SSL), you should set to true.

You must have to access the FTP resource; otherwise, a exception is thrown.

Specify the FTP command to send to the server by setting the property to a value defined in the structure. To transmit text data, change the property from its default value (true) to false. For details and restrictions, see .

When using an object to upload a file to a server, you must write the file content to the request stream obtained by calling the method or its asynchronous counterparts, the and methods. You must write to the stream and close the stream before sending the request.

Requests are sent to the server by calling the method or its asynchronous counterparts, the and methods. When the requested operation completes, an object is returned. The object provides the status of the operation and any data downloaded from the server.

You can set a time-out value for reading or writing to the server by using the property. If the time-out period is exceeded, the calling method throws a with set to .

When downloading a file from an FTP server, if the command was successful, the contents of the requested file are available in the response object's stream. You can access this stream by calling the method. For more information, see .

If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. If the specified proxy is an HTTP proxy, only the , , and commands are supported.

Only downloaded binary content is cached; that is, content received using the command with the property set to true.

Multiple s reuse existing connections, if possible.

For more information about the FTP protocol, see RFC 959, "File Transfer Protocol," available at http://www.rfc-editor.org/.

Implements a File Transfer Protocol (FTP) client.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  If there is no operation in progress, this method does nothing. If a file transfer is in progress, this method terminates the transfer.

  This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].

  Terminates an asynchronous FTP operation.

- Method
  2.0.0.0
  4.0.0.0
  System.IAsyncResult `` ``

  You must complete the asynchronous operation by calling the method. Typically, is called by the method referenced by . To determine the state of the operation, check the properties in the object returned by this method.

  This method does not block while waiting for the stream. To block, call in place of this method.

  For detailed information about using the asynchronous programming model, see [<topic://cpovrAsynchronousProgrammingOverview>].

  This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].

  Begins asynchronously opening a request's content stream for writing.

  An instance that indicates the status of the operation.

  An delegate that references the method to invoke when the operation is complete. A user-defined object that contains information about the operation. This object is passed to the delegate when the operation completes.
- Method
  2.0.0.0
  4.0.0.0
  System.IAsyncResult `` ``

  You must complete the asynchronous operation by calling the method. Typically, is called by the method referenced by . To determine the state of the operation, check the properties in the object returned by the method.

  If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy.

  does not block while waiting for the response from the server. To block, call the method in place of .

  For more information about using the asynchronous programming model, see [<topic://cpovrAsynchronousProgrammingOverview>].

  This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].

  If a is thrown, use the and properties of the exception to determine the response from the server.

  Begins sending a request and receiving a response from an FTP server asynchronously.

  An instance that indicates the status of the operation.

  An delegate that references the method to invoke when the operation is complete. A user-defined object that contains information about the operation. This object is passed to the delegate when the operation completes.
- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO
  System.Security.Cryptography.X509Certificates.X509CertificateCollection To be added.

  Client certificates are used to authenticate the client during the initial SSL connection negotiation. For more information, see .

  The .NET Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the .NET Framework uses the first element of (if there is one), or tries to reuse an anonymous session if is empty.

  Gets or sets the certificates used for establishing an encrypted connection to the FTP server.

- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO
  System.String To be added.

  Connection groups associate a set of requests with a particular connection or set of connections. The connections in a connection group can be reused only by requests originating in the same application domain, when the credentials on the request are the same and the request specifies the connection group name. When a request does not specify a connection group name, any existing connection to the requested server that is not associated with a connection group can be used. When the credentials are not the same, the existing connection is closed and the new request must be reauthenticated.

  Using connection groups can improve performance because this allows all of the requests for a user to reuse the connection authenticated with the user's credentials.

  Changing the property after calling the , , , or method causes an exception.

  Gets or sets the name of the connection group that contains the service point used to send the current request.

- Property
  2.0.0.0
  4.0.0.0
  System.Int64 To be added.

  The property is provided only for compatibility with other implementations of the and classes. There is no reason to use .

  Gets or sets a value that is ignored by the class.

- Property
  2.0.0.0
  4.0.0.0
  System.Int64 To be added.

  Set the property when downloading a file from an FTP server. This offset indicates the position in the server's file that marks the start of the data to be downloaded. The offset is specified as the number of bytes from the start of the file; the offset of the first byte is zero.

  Setting causes the to send a restart (REST) command to the server. This command is ignored by most FTP server implementations if you are uploading data to the server.

  Changing after calling the , , , or method causes an exception.

  Gets or sets a byte offset into the file being downloaded by this request.

- Property
  2.0.0.0
  4.0.0.0
  System.String To be added.

  The property is provided only for compatibility with other implementations of the and classes. There is no reason to use .

  Always throws a .

- Property
  2.0.0.0
  4.0.0.0
  System.Net.ICredentials To be added.

  You are not required to specify credentials when connecting using anonymous logon. You must set the property by using a credential of type ; this ensures that the user name and password can be read and sent to the server.

  Credentials information is not encrypted when transmitted to the server unless the property is set to true.

  Changing after calling the , , , or method causes an exception.

  Gets or sets the credentials used to communicate with the FTP server.

- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO
  System.Net.Cache.RequestCachePolicy To be added.

  Only content received using the command is cached.

  The following table describes the effects of FTP caching policies on .

  Policy

  Effect

  Returns the cached resource if the resource is fresh, the content length is accurate, and the expiration, modification, and content length attributes are present.

  Returns the resource from the server.

  Returns the cached resource if the content length is present and matches the entry size; otherwise, throws a .

  Returns the cached resource if the content length is provided and matches the entry size; otherwise, the resource is downloaded from the server and is returned to the caller.

  Returns the cached resource if the timestamp of the cached resource is the same as the time stamp of the resource on the server; otherwise, the resource is downloaded from the server, stored in the cache, and returned to the caller.

  Downloads the resource from the server, stores it in the cache, and returns the resource to the caller.

  If a cached resource exists, it is deleted. The resource is downloaded from the server and is returned to the caller.

  Setting overrides any configuration setting.

  Defines the default cache policy for all FTP requests.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  Unless the property is true, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports SSL, you should set to true.

  The "AUTH TLS" command is sent to the server to request an encrypted session. If the server does not recognize this command, you receive a exception.

  Gets or sets a that specifies that an SSL connection should be used.

- Method
  2.0.0.0
  4.0.0.0
  System.IO.Stream ``

  If the operation has not completed, the method blocks until the operation completes. To determine whether the operation has completed, check the property before calling .

  In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while opening the stream for writing.

  This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].

  Ends a pending asynchronous operation started with .

  A writable instance associated with this instance.

  The object that was returned when the operation started.
- Method
  2.0.0.0
  4.0.0.0
  System.Net.WebResponse ``

  If the operation has not completed at the time the method is called, blocks until the operation completes. To prevent blocking, check the property before calling .

  In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while communicating with the server.

  This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].

  Ends a pending asynchronous operation started with .

  A reference that contains an instance. This object contains the FTP server's response to the request.

  The that was returned when the operation started.
- Method
  2.0.0.0
  4.0.0.0
  System.IO.Stream

  Set the request properties before calling the method. After writing the data to the stream, you must close the stream prior to sending the request.

  If you have not set the property to or , you cannot get the stream.

  blocks while waiting for the stream. To prevent this, call the method in place of .

  This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].

  Retrieves the stream used to upload data to an FTP server.

  A writable instance used to store data to be sent to the server by the current request.

- Method
  2.0.0.0
  4.0.0.0
  System.Net.WebResponse

  To access the FTP-specific properties, you must cast the object returned by this method to .

  causes a control connection to be established, and might also create a data connection. blocks until the response is received. To prevent this, you can perform this operation asynchronously by calling the and methods in place of .

  If the property is set, either directly or in a configuration file, communications with the FTP server are made through the proxy.

  If a is thrown, use the and properties of the exception to determine the response from the server.

  This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].

  Multiple calls to return the same response object; the request is not reissued.

  Returns the FTP server response.

  A reference that contains an instance. This object contains the FTP server's response to the request.

- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO
  System.Net.WebHeaderCollection To be added.

  The property is provided only for compatibility with other implementations of the and classes. There is no reason to use .

  Gets an empty object.

- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO("We don't support KeepAlive = true")
  System.Boolean To be added.

  When the property is set to false, the control connection is closed when you call the method.

  Changing after calling the , , , or method causes an exception.

  Gets or sets a value that specifies whether the control connection to the FTP server is closed after the request completes.

- Property
  2.0.0.0
  4.0.0.0
  System.String To be added.

  The property determines which command is sent to the server. You set the by using the strings defined in the public field members of the class. Note that the strings defined in the class are the only supported options for the property. Setting the property to any other value will result in an exception.

  When setting to , you must do so before calling the method. Failure to call these members in the correct order causes a exception when you attempt to get the request stream.

  The credentials supplied for the object must have permission to perform the specified method. If not, the FTP command fails.

  To determine the success or failure of a command, check the and properties.

  Gets or sets the command to send to the FTP server.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  The property is provided only for compatibility with other implementations of the and classes.

  Always throws a .

- Property
  2.0.0.0
  4.0.0.0
  System.Net.IWebProxy To be added.

  The property identifies the instance that communicates with the FTP server. The proxy is set by the system by using configuration files and the Internet Explorer Local Area Network settings. To specify that no proxy should be used, set to the proxy instance returned by the method. For more information about automatic proxy detection, see Automatic Proxy Detection.

  You must set before writing data to the request's stream or getting the response. Changing after calling the , , , or method causes an exception.

  The class supports HTTP and ISA Firewall Client proxies.

  If the specified proxy is an HTTP proxy, only the , , and commands are supported.

  Gets or sets the proxy used to communicate with the FTP server.

- Property
  2.0.0.0
  4.0.0.0
  System.Int32 To be added.

  The is used when writing to the stream returned by the method or reading from the stream returned by the method.

  Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. If the time-out period is exceeded, the calling method throws a with set to .

  To specify the amount of time to wait for the request to complete, use the property.

  Gets or sets a time-out when reading from or writing to a stream.

- Property
  2.0.0.0
  4.0.0.0
  System.String To be added. To be added.

  Gets or sets the new name of a file being renamed.

- Property
  2.0.0.0
  4.0.0.0
  System.Uri To be added.

  The value of the property is the URI specified when the method was called to obtain this instance.

  Gets the URI requested by this instance.

- Property
  2.0.0.0
  4.0.0.0
  System.Net.ServicePoint To be added.

  If no object exists, one is created for the FTP server. To set the maximum number of connections that can be open for an FTP server, set the property of the instance returned by this property.

  Gets the object used to connect to the FTP server.

- Property
  2.0.0.0
  4.0.0.0
  System.Int32 To be added.

  To specify an infinite value, set the property to (-1). This is the default value.

  is the number of milliseconds that a synchronous request made with the method waits for a response and that the method waits for a stream. If a resource does not respond within the time-out period, the request throws a with the property set to .

  Changing after calling the , , , or method causes an exception.

  A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a time-out on your request.

  Gets or sets the number of milliseconds to wait for a request.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  If you are sending binary data, such as an image, set this property to true. If you are sending text, set the property to false. Specifying true causes the to send a "TYPE I" command to the server. Specifying false causes the to send a "Type A" command to the server. FTP servers can ignore these commands.

  Changing after calling the , , , or method causes an exception.

  Gets or sets a value that specifies the data type for file transfers.

- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO
  System.Boolean To be added.

  The property is provided only for compatibility with other implementations of the and classes. There is no reason to use .

  Always throws a .

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  Setting the property to true sends the "PASV" command to the server. This command requests the server to listen on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command.

  For a description of the behaviors that are specified using , see RFC 959, "File Transfer Protocol," Section 3.2, "Establishing Data Connections" and Section 4.1.2, "Transfer Parameter Commands," available at http://www.rfc-editor.org/.

  Changing after calling the , , , or method causes an exception.

  If is set to true, the FTP server may not send the size of the file, and download progress can always be zero. If is set to false, a firewall can raise an alert and block the file download.

  Gets or sets the behavior of a client application's data transfer process.