How to Integrate wodSFTP into Windows Applications (ActiveX/.NET)

wodSFTP .NET API Reference: Key Methods, Properties, and Events

This reference summarizes the core .NET API surface for wodSFTP (a .NET SFTP component). It covers the primary classes, key methods, important properties, and common events you’ll use to implement secure file transfers, manage connections, and handle errors. Examples assume synchronous usage; where async variants exist, use them similarly with async/await.

Main classes

• WodSftpClient — primary client for connecting, authenticating, and performing file operations.
• WodSftpSession — represents a session/connection handle (returned or exposed by client).
• WodSftpFile — represents a remote file (metadata and read/write streams).
• WodSftpDirectory — directory operations and listings.
• WodSftpTransferProgress — progress info passed to callbacks/events.
• WodSftpException — component-specific exception type with error codes.

Key properties (WodSftpClient)

• Host (string) — remote server hostname or IP.
• Port (int) — SSH/SFTP port (default 22).
• Username (string) — username for authentication.
• Password (string) — password credential (if using password auth).
• PrivateKey (string or byte[]) — path or content for private key auth.
• Timeout (int) — connection/operation timeout in milliseconds.
• KeepAliveInterval (int) — seconds between keepalive packets.
• TransferChunkSize (int) — buffer size for uploads/downloads.
• EnableCompression (bool) — whether to request SSH compression.
• LastError (WodSftpException or string) — last error information (read-only).
• IsConnected (bool) — whether a session is active (read-only).

Key methods (WodSftpClient)

• Connect/Disconnect

  • Connect(): void — establish an SFTP connection using configured credentials.
  • Connect(timeoutMs: int): void — connect with explicit timeout.
  • Disconnect(): void — close connection and release resources.

• Authentication

  • AuthenticateWithPassword(username: string, password: string): bool — authenticate using password.
  • AuthenticateWithPrivateKey(username: string, privateKeyPath: string, passphrase?: string): bool — key-based auth.
  • AuthenticateAgent(): bool — use SSH agent (if supported).

• File operations

  • UploadFile(localPath: string, remotePath: string): void — upload file synchronously.
  • DownloadFile(remotePath: string, localPath: string): void — download file synchronously.
  • OpenRead(remotePath: string): Stream — open remote file for reading.
  • OpenWrite(remotePath: string, overwrite: bool = true): Stream — open remote file for writing.
  • DeleteFile(remotePath: string): void — remove remote file.
  • RenameFile(remotePath: string, newRemotePath: string): void — rename/move file.

• Directory operations

  • CreateDirectory(remotePath: string, recursive: bool = false): void — create directory.
  • DeleteDirectory(remotePath: string, recursive: bool = false): void — delete directory.
  • ListDirectory(remotePath: string): IEnumerable — list entries with metadata.
  • ChangeDirectory(remotePath: string): void — set current remote working directory.
  • GetWorkingDirectory(): string — current directory.

• Metadata & permissions

  • GetAttributes(remotePath: string): FileAttributes/struct — size, timestamps, permissions.
  • SetAttributes(remotePath: string, attributes): void — set permissions/timestamps.

• Transfer control & utilities

  • ResumeUpload(localPath: string, remotePath: string, offset: long): void — resume an upload.
  • ResumeDownload(remotePath: string, localPath: string, offset: long): void — resume a download.
  • ComputeRemoteChecksum(remotePath: string, algorithm: string = “md5”): string — get remote checksum if supported.
  • Exists(remotePath: string): bool — check file/dir existence.

Async/Task-based counterparts

For all long-running operations (connect, upload, download, list), async Task/Task variants typically exist:

• ConnectAsync(), UploadFileAsync(…), DownloadFileAsync(…), ListDirectoryAsync(…), etc. Always prefer async variants in UI or high-concurrency apps.

Events and callbacks

• OnConnected (event) — raised after a successful connection. Signature: (sender, EventArgs).
• OnDisconnected (event) — raised on disconnect (clean or error).
• OnAuthenticationPrompt (event) — fired when a server requests additional auth info (keyboard-interactive). Handler can supply responses.
• OnProgress (event) — periodic transfer progress. Signature: (sender, WodSftpTransferProgress). WodSftpTransferProgress typically includes bytesTransferred, totalBytes, percentage, speedBps, elapsed.
• OnTransferComplete (event) — fired when an upload/download finishes successfully.
• OnTransferFailed (event) — fired when a transfer fails; provides exception and context.
• OnHostKeyMismatch (event) — when host key differs from known; handler can accept/reject and optionally update known-hosts.
• OnLogMessage (event) — debug/info logs from the component; useful for diagnostics.

Error handling

• Methods throw WodSftpException on protocol/auth/IO failures. Inspect properties: Code (int), Message (string), InnerException.
• Use LastError for non-throwing APIs that return status codes.
• Common errors: authentication failure, connection timeout, permission denied, file not found, insufficient space, host key mismatch.

Typical usage patterns (concise)

1. Create client and set properties.
2. Connect() or ConnectAsync().
3. Authenticate (password/key/agent).
4. Perform operations (UploadFile/DownloadFile/ListDirectory). Subscribe to OnProgress for UI updates.
5. Disconnect() in finally block or using pattern.

Example (sync):

csharp
Copy CodeCopied
var client = new WodSftpClient {
Host = “sftp.example.com”,
  Port = 22,
  Username = “user”,
  Timeout = 30000
};
client.Connect();
client.AuthenticateWithPrivateKey(“user”, @“C:\keys\idrsa”, “passphrase”);
client.UploadFile(@“C:\local\file.txt”, ”/remote/file.txt”);
client.Disconnect();

csharp
 ffON2NH02oMAcqyoh2UU MQCbz04ET5EljRmK3YpQ CPXAhl7VTkj2dHDyAYAf” data-copycode=“true” role=“button” aria-label=“Copy Code”>Copy CodeCopied
await client.ConnectAsync();
await client.AuthenticateWithPasswordAsync(“user”,“password”);
await client.UploadFileAsync(@“C:\local\file.txt”,”/remote/file.txt”);
await client.DisconnectAsync();