ComponentSpace FTP Class Library

FTP Class Library

Introduction provides an overview of the FTP Class Library.

Getting Started lists the steps to start using the product.

Installation details the prerequisite system requirements and installation procedures for the FTP Class Library.

Reference documents the namespaces and classes that constitute the FTP Class Library.

Examples describes the included example code.

Tracing describes how to enable tracing to track problems down.

FAQ lists frequently asked questions.

Support describes how to get support.

Send comments on this topic.


Introduction

The ComponentSpace FTP Class Library is a Microsoft .NET class library that allows you to connect to FTP servers and perform file transfers and remote directory functions.

Features

  • Upload and download binary and ASCII files
  • Supports both passive and active data connections
  • All directory commands fully supported
  • Restart interrupted uploads and downloads
  • Easy to use high level methods for file uploads, file downloads, directory commands and the most common FTP operations
  • Full access to the low level methods for full control of the command connection and data connection
  • Calling applications may make either synchronous (blocking) calls or asynchronous (nonblocking) calls to send and receive FTP messages
  • Asynchronous calls may either use an event or a callback method
  • Receive command tracing and data transfer status via events
  • Send and receive timeouts may be specified

Benefits

  • Supported on all .NET platforms
  • Supports all .NET languages including C# and VB.NET
  • Developed in C#
  • Numerous VB.NET, C# and ASP.NET examples with full source code
  • Runtime royalty free

Example

    ' This simple download example uses the Download static method of the FtpClient class.
    ' It will connect, download and disconnect in a single method call.

    FtpClient.Download("ftp.microsoft.com", _
                       "anonymous", _
                       "me@mycompany.com", _
                       TransferMode.Binary, _
                       "/Services/Museum/pictures/ballmerplunge.jpg", _
                       "c:\temp\ballmerplunge.jpg")


Getting Started
  • Install the product in your development environment.
  • Compile and run one of the examples.
  • If you need further details, refer to the reference section.
  • Add a reference to the class library in your application.
  • Once completed, distribute the class library with your application.

Most developers will use either the FtpClient or FtpClientComponent class. FtpClient provides comprehensive support of all the FTP operations. FtpClientComponent is a .NET component that exposes the most common properties and events at design and run time.

If you're having trouble getting started, need some advice or assistance, have a product suggestion, or want to report a bug, please contact our support staff.


Installation

If you haven't already done so, install this product by double clicking the FtpSetup.msi file and follow the installation steps.

Prerequisites

The Microsoft .NET framework runtime must already be installed on your computer. The Microsoft .NET framework redistributable may be downloaded from msdn.microsoft.com.

You will also need a development environment such as Visual Studio .NET.

Add a Reference

To use the product in Visual Studio .NET, you need to add a reference to the product DLL from within your project. With your project open, in the Solution Explorer right click References and click Add Reference.... On the .NET panel click the Browse button and browse to ComponentSpace.Ftp.dll. You will find the DLL in the installation directory.

Once the reference has been added you can refer to the various product classes from within your project.

Visual Studio .NET Toolbox

This optional step is only required if you wish to take advantage of the design time features of the FtpClientComponent component. An example of using this component is included.

To add the component to the Visual Studio .NET Toolbox, right click on the Components panel of the Toolbox window and click Add/Remove Items.... On the .NET Framework Components panel click the Browse button and browse to ComponentSpace.Ftp.dll. You will find the DLL in the installation directory.

Once the component has been added to the Toolbox you can use it in your application simply by dragging it onto your application's forms.

Distribution

The class library's runtime is royalty free which means it may be freely distributed with your application. The only file that should be distributed is the class library's DLL.


Reference

The reference section is contained within a separate help file. You can find the reference help file in the same location as this help file or navigate to it using the Start menu.


Examples

Example code, with full source code and developed using Microsoft Visual Studio .NET, is included with the product. You will find these projects in sub-directories of the installation directory or you may nevigate to them from the Start menu.

There are VB.NET, C#, ASP.NET, Windows, console, web and web service examples. VBTestFtp and TestFtp are the most comprehensive examples and use the FtpClient class. TestFtpClientComponent is a VB.NET example that uses the FtpClientComponent class which exposes the most common properties and events at design time.

Most developers will either use the FtpClient class or the FtpClientComponent class.

VBTestFtp
Demonstrates the use of the class library's FtpClient and related classes within a VB.NET Windows application. This example uses asynchronous invocation with event notification.
TestFtp
Demonstrates the use of the class library's FtpClient and related classes within a C# Windows application. This example uses asynchronous invocation with event notification.
TestFtpClientComponent
Demonstrates the use of the class library's FtpClientComponent and related classes within a VB.NET Windows application. This example makes use of design time properties and uses asynchronous invocation with event notification.
TestFileTransfer
Demonstrates the use of the class library's FtpClient and related classes within a VB.NET console application. This example uses synchronous invocation.
TestFileUpload
Demonstrates the use of the class library's FtpClient and related classes within a C# console application. This example uses synchronous invocation.
TestRestartDownload
Demonstrates the use of the class library's FtpClient and related classes within a VB.NET console application. This example demonstrates restarting an aborted download.
TestRestartUpload
Demonstrates the use of the class library's FtpClient and related classes within a VB.NET console application. This example demonstrates restarting an aborted upload.
TestFtpWebRequest
Demonstrates the use of the class library's FtpWebRequest and related classes within a VB.NET Windows application. This example demonstrates using the Microsoft pluggable protocols architecture.
FtpWebApplication
Demonstrates the use of the class library's FtpClient and related classes within a ASP.NET web application. This example uses synchronous invocation.
FtpWebService
Demonstrates the use of the class library's FtpClient and related classes within a ASP.NET web service. This example uses synchronous invocation.
TestMultiFile
Demonstrates the use of the class library's MultiFile and related classes within a VB.NET console application.
TestMultiFileFilter
Demonstrates the use of custom filters used with the class library's MultiFile and related classes within a VB.NET console application.
TestFtpWindowsService
Demonstrates the use of the class library's FtpClient and related classes within a C# Windows service application.
VBTestFtpWindowsService
Demonstrates the use of the class library's FtpClient and related classes within a VB.NET Windows service application.
TestFailSafeDownload
Demonstrates the use of the class library's FailSafeTransfer class to download a file within a VB.NET console application.
TestFailSafeUpload
Demonstrates the use of the class library's FailSafeTransfer class to upload a file within a VB.NET console application.
Tests
NUnit tests for the class library.


Tracing

To help resolve problems, tracing internal to the product may be enabled. Tracing information includes FTP commands and replies, and other significant data and events.

Create a standard .NET configuration file for your application, if one doesn't already exist. The configuration file name consists of your application file name and .config. For example, if your application is called myapplication.exe then its configuration file should be named myapplication.exe.config.

Include in the system.diagnostics section a switch and listeners as shown in the example configuration below.

  <?xml version="1.0" encoding="utf-8" ?>
  <configuration>
      <system.diagnostics>
          <switches>
              <add name="ComponentSpace.Ftp" value="1"/>
          </switches>
          <trace autoflush="true" indentsize="4">
              <listeners>
                  <add name="TextWriter"
                       type="System.Diagnostics.TextWriterTraceListener"
                       initializeData="Ftp.log"/>
              </listeners>
          </trace>
      </system.diagnostics>
  </configuration>

Alternatively you may add this configuration information to machine.config to trace all applications using the product.


FAQ

Frequently Asked Questions
  1. I can't build the examples. Why can't the ComponentSpace namespace be found?

    2. The assembly containing the namespace or the project referencing it has been moved. The simplest way to fix this is to re-add the reference to the project by browsing to where the DLL is located (typically the installation directory).

  2. What is FTP?

    3. The File Transfer Protocol (FTP) defines a protocol for transferring files between machines and accessing the file system of remote machines. It is defined by RFC-959 and related RFCs.

  3. What if I'm behind a firewall?

    4. Outgoing TCP traffic to port 21 (the default FTP command port) must be permitted. Also, the FtpClient's DataConnectionType affects the way the FTP data connection is made. You may need to talk to your network administrator.

  4. I'm confused by all the classes. Where do I start?

    5. For the majority of users, you don't need to worry about the low level classes. They're only exposed for those who need maximum control in unusual situations. The best place to start is by looking at the example code. There's VB.NET, C#, ASP.NET, Windows, Console, Web, and Web Services examples with full source code. Compile and run one of the examples that matches closest to what you want to do. You can also browse through the comprehensive reference help for the class library. If you're still stuck, don't hestiate to contact our support staff.

  5. Why do the sample web applications and web services seem to hang?

    6. Evaluation copies of the FTP component display a reminder dialog the first time a process calls into it. If you run the web application or service on a remote machine, the dialog will be displayed on the remote machine and it won't be apparent you need to cancel the dialog. The client machine, running the browser or web service client, will appear to be waiting forever for the FTP component. Go to the remote machine and cancel the dialog and you can continue your testing. The reminder dialog is only displayed by evaluation copies of the FTP component.


Support

For further information, visit us at http://www.componentspace.com or send email to info@componentspace.com.

If you need assistance, have a bug to report, or a product enhancement request send email to support@componentspace.com.