Hi Jim,
First, you need to understand something about the FTP protocol. It has
nothing to do with whether you use a Console app, a browser, or any other
kind of interface. It is a messaging protocol, just like HTTP is a messaging
protocol. Now, stick with me, because I'm going to give you some technical
information you should be familiar with in order to use FTP effectively, but
I will follow that with a more detailed explanation of the
System.Net.FtpWebRequest class, which encapsulates a lot of the lower-level
protocol stuff and is pretty easy to use (if you know how!).
An FTP Session is a "conversation" in the FTP protocol that occurs between a
client application and an FTP server. The client application opens a network
connection to the FTP server, and the FTP server starts the conversation by
acknowledging the client. The client then responds to the FTP server with a
command, and the FTP server responds to that command. This occurs repeatedly
until the client disconnects.
It begins with the client logging in to the server, as in the following
example:
Server: 220 Sample FTP server ready. Please give user-name
Client: USER anonymous
Server: 331 User name OK. Please give your email address as password
Client: PASS (e-mail address removed)
Server: 230 User logged in
In this example, the server begins with a status code followed by a message.
The client sends the command USER and the parmeter "anonymous" which
indicates that the client is requesting anonymous access to the server. The
server, which allows anonymous connections (in this case), responds with a
status code followed by a message. The client then sends the PASS command
with an email address as the password parameter. The server responds with a
status code followed by a message.
You can read a more detailed explanation of the protocol here:
http://war.jgaa.com/ftp/?cmd=show_page&ID=ftp_brief
This includes information about status codes, etc.
http://cr.yp.to/ftp.html
Here is another listing and explanation of the various FTP commands:
http://www.nsftools.com/tips/RawFTP.htm
Now, as to the System.Net.FtpWebRequest class.
In the .Net platform 2.0, several different network messaging protocols
which share common functionality are exposed via the base WebRequest and
WebResponse classes. FtpWebRequest and HttpWebRequest are the most salient
of these, and as you can see, each has a similar "Request/Response" type of
operation, although the actual protocol syntax is quite different.
This is why you use the WebRequest.Create method to create an instance of
either one. The WebRequest.Create method looks at the URI passed to it to
determine the protocol, and returns an instance of the appropriate
WebRequest descendant for that protocol.
There are a couple of important differences. First, an HTTP Session is
actually a series of disconnected Request/Response transactions. There is no
persistent network connection involved. In the case of an FTP Session, a
persistent connection is used throughout the Session, so the URI for an HTTP
Request always either includes or implies a resource (usually a document or
file), while the initial FTP Request may only include an initial directory.
However, if the FtpWebRequest is going to perform a single operation on a
single file, or perhaps multiple operations beginning with a single file
operation, it may include a file name. Example:
HttpWebRequest:
http://www.microsoft.com
The document is implied, as the default home page document for that
directory.
HttpWebRequest:
http://cr.yp.to/ftp.html
The document is explicitly named.
FtpWebRequest: ftp://weather.noaa.gov/
This is an actual FTP location, the root folder of the National Weather
Service's FTP server.
FtpWebRequest: ftp://weather.noaa.gov/data/directory_contents.txt
In a browser, this is automatically interpreted as a request for the
document, but in an FtpWebRequest, it may be used to request a document, get
information about a document, delete a document, or upload a document,
depending.
An HTTP Request takes place in a vacuum. There is precisely 1 Request, and
precisely 1 Response.
With FTP, there can be a whole series of Requests and Responses.
Although you can't see it, the HTTP Request also includes login information,
which is sent in the HTTP Header of the Request. This is exposed in the
FtpWebRequest, because it is only used one time for the entire
"conversation" (in a browser, this exchange is hidden from you). This is
done via the Credentials property of the FtpWebRequest, which is an instance
of the System.Net.NetworkCredentials class. Alternatively, the user name and
password can be included in the URI, in the format of:
ftp://<user>:<password>@<host>:<port>/<url-path>
Example:
ftp://anonymous:
[email protected]/data/
This includes the "anonymous" user name and my email address (up to the '@'
character). With anonymous login, any email address will do.
ftp://anonymous:
[email protected]:21/data/
This one also includes the port. 21 is the default FTP port, so you don't
need to specify the port unless the FTP server is *not* using port 21.
Creating the FtpWebRequest has the effect of logging you in to the FTP
server, and executing a command. So, the way you initially do this is to set
the URI, the Credentials, the Method property (which exposes an underlying
FTP command), and call the WebRequest.Create method. At least in most cases.
For example, to download a file, you don't even need to set the Method
property, as WebRequestMethods.Ftp.DownloadFile is the default method.
What is happening "under the covers" is that the FtpWebRequest is conducting
an FTP Session and conversation with the server. But that is hidden from
you.
For the most part, the other properties are not particularly important to
know. The defaults for these are the most commonly-used settings. For
example, the UsePassive property indicates whether or not to use Passive
mode in the Session. By default this is true, which simplifies things when
working behind a firewall.
You can get the Response from the server by calling GetResponse. This method
returns any Response information collected during the Session, such as the
current Status code, response message, the welcome banner message,
ContentLength, and headers. Usually, you will only need the status code.
When uploading a file, it is a little more tricky. You set your properties,
and then call the GetRequestStream method. This method returns a writiable
Stream to which you write the contents of a file to be uploaded. After
writing to the Stream and closing it, you call the GetResponse method to
ensure that the upload went through without any issues, and you're done.
More detailed information about the FtpWebRequest class can be found at:
http://msdn2.microsoft.com/en-us/library/system.net.ftpwebrequest(VS.80).aspx
--
HTH,
Kevin Spencer
Microsoft MVP
Professional Numbskull
Show me your certification without works,
and I'll show my certification
*by* my works.
