Transferring Files with the .NET SDK
The .NET SDK can support file transfer to and from the ThingWorx Platform. File transfers are performed over the WebSocket connection maintained with the platform, so there is no need for the client application to open another connection.
 |
For general information about file transfers between Edge SDKs and ThingWorx Platform, refer to File Transfers.
|
To support file transfers in your client application, you must use the FileTransferVirtualThing class to enable the functionality and define the directories available for file operations. A virtual directory maps a unique name to an absolute path of a directory in the file system. All subdirectories of the specified directory are exposed to the ThingWorx Platform. You can define multiple virtual directories. The directories do not need to be contiguous.
For more information, click the title of a section below to display its content. Click the title again to hide the content:
.NET SDK: FileTransferVirtualThing Class
The .NET SDK has full support for all the remote directory/file browsing capabilities of ThingWorx Platform, as well as bidirectional file transfer. To use the directory browsing and file transfer capabilities of this SDK, you must:
• Sub-class the FileTransferVirtualThing class.
• Define the virtual directories.
Virtual Directories
To enhance performance and security, virtual directories allow you to expose only a subset of a the entire file system of a device to the ThingWorx Platform for browsing and file transfer. To register a virtual directory, you must map a unique name to an absolute path for a directory in your file system. Multiple virtual directories can be defined, and they do not need to be contiguous. Also, you may register for the FileTransferStateChanged event, which fires whenever a file transfer event occurs.
 | All subdirectories of a directory you specify for the virtual directory are exposed to the ThingWorx platform. |
ScmThing Extends the FileTransferVirtualThing
As of v.1.0.1 of the SCM Edge Extension for .NET and v.5.8.2 of the .NET SDK, the ScmThing extends the FileTransferVirtualThing, allowing file transfers to and from the SCM asset as well as SCM deployments. For the acceptable constructors for the SCMThing, refer to Setting Up SCM in the section for the SCM Edge Extension for .NET in this help center.
In addition, an identifier can be null for any constructor. This change occurred in the .NET SDK itself.
 | You cannot add virtual directories as part of ScmThing construction as you can for FileTransferVirtualThing because the virtual directories are overwritten as a result of the setup sequence. To add your own virtual directories, use AddVirtualDirectory() after the construction of the SCMThing. |
Methods of the FileTransferVirtualThing Class
The following methods are available on the FileTransferVirtualThing class:
• AddVirtualDirectory — Adds a virtual directory to the FileManager. A named virtual directory is associated with a specific Thing and has a specific path in the underlying file system. More than one virtual directory can be assigned to a single Thing. This method takes the following properties:
◦ dirName — Name to apply to this virtual directory.
◦ path — The absolute path to the underlying directory in the file system.
• BindVirtualDirectories — Registers all virtual directories associated with this FileTransferVirtualThing with the FileManager. Virtual directories are automatically registered with the FileManager during the FileTransferVirtualThing constructor. However, if the FileManager is shut down and restarted, each FileTransferVirtualThing will need to re-register its virtual directories; this method facilitates that re-registration.
• CheckStalledTransfers — Checks for any transfers that have started and stopped without completing, and deletes them.
• FileTransferStateChanged — Event that fires when a file transfer completed, successfully or not.
• GetFile — Retrieves a file from the ThingWorx Platform. This method takes the following properties:
◦ sourceRepo — The name of the entity from which to retrieve the file.
◦ sourcePath — The path to the file.
◦ sourceFile — Name of the file.
◦ targetPath — The local VIRTUAL path of the resulting file (not including the file name).
◦ targetFile — Name of the resulting file in the target directory.
◦ timeout — Timeout, in seconds, for the transfer. A zero will use the default timeout of the system.
◦ async — If true, return immediately and call a callback function when the transfer is complete. If false, block until the transfer is complete. Note that the file callback function will be called in either case.
• InitializeFileTransferManager — Initializes the FileTransferManager. This method is called automatically during the constructor of FileTransferVirtualThing. However, you may need to invoke this method to restart the File Transfer subsystem after a shutdown. This method takes the following property:
◦ configInfo — Specifies the information necessary to initialize the File Manager.
• ListVirtualDirs — Returns a list of virtual directories from the FileTransferManager.
• RemoveVirtualDirectory — Removes a virtual directory from the FileTransferManager. This method takes the following property:
◦ dirName — Name of the virtual directory to remove.
• SendFile — Sends a file to the ThingWorx Platform. This method takes the following properties:
◦ sourcePath — The VIRTUAL path to the file to send (not including the file name).
◦ sourceFile — Name of the file to send.
◦ targetRepo — Target repository of the file.
◦ targetPath — Path of the resulting file in the target repository (not including the file name).
◦ targetFile — Name of the resulting file in the target directory.
◦ timeout — Timeout, in seconds, for the transfer. A zero will use the default timeout of the system.
◦ async — If true, return immediately and call a callback function when the transfer is complete. If false, block until the transfer is complete. Note that the file callback function will be called in any case.
• ShutdownFileTransferManager — Shuts down the FileTransferManager.
Additional Properties for a File Transfer
You can also set the following properties for a file transfer:
• FileTransferInfo.BlockSize — The number of bytes in each block of a file to be transferred. Refer to Best Practices for Transferring Large Files below.
• FileTransferInfo.MaxFileSize — The largest number of bytes in a file to be transferred.
• FileTransferInfo.MD5BlockSize — The number of bytes that an MD5 buffer can contain. The number should be a multiple of 64. It is not related to the FileTransferInfo.BlockSize .
• FileTransferInfo.Timeout — The number of milliseconds to wait for a stalled transfer to continue before timing out the transfer. For best results when transferring large files, set this value to 0.
| | When a file transfer times out, the repository is left with a *.part incomplete file. This behavior is expected. The *.part files are kept in the staging directory in the event that the file transfer is resumed. This allows the Edge to detect the partial transfer and resume the transfer from the last successful packet, eliminating the need to resend already received bytes after the transfer resumes. |
• FileTransferInfo.StagingDir— The directory to be used for collecting the bytes (or blocks of bytes) received during a file transfer.
Best Practices for Transferring Large Files
When transferring large files, following these best practices is critical to ensuring optimal performance:
1. Set the FileTransferInfo.BlockSize property to 1MB (1,024,000 bytes) for maximum bit rate on average. The correct setting of this property is essential to improving file transfer performance.
2. File transfer times depend on Internet bandwidth, which varies and increases in load at certain times of the day. Choose a time of day when network traffic is low to transfer large files from edge devices to a ThingWorx Platform. When possible, improve the quality of your network. Testing has shown that results vary by time of day and the network being used. When network performance degrades, the performance of large file transfers can be negatively affected very quickly.
3. Removing any socket read timeouts also increases performance. Make sure to set the FileTransferInfo.Timeout and the SocketReadTimeout to zero (0).
4. Make sure that the LogLevel is not set to TRACE. A level of ERROR is recommended.
5. Set up the File Transfer Subsystem (FTSS) on your ThingWorx Platform as shown in the following screen shot. These settings have been tested and shown to be optimal when transferring large files:
| | The lower of the two block size values, namely for the SDK and the FTSS of the ThingWorx Platform, is used at runtime. The platform is hard-coded with a maximum block size of 1MB. To be safe, set both the FTSS and SDK block sizes to 1MB. The platform FTSS configuration table currently defaults to 128,000. |