Version 2022 Updates
The latest version of our development libraries have been updated and improved with a focus on modern programming environments and design patterns. This guide is intended to highlight some of the key updates and changes.
Visit the Beta Downloads page to download the latest version.
- New Features
- .NET Async Functionality
- Upgrade Guide
The latest version of our development libraries have been updated and improved with a focus on modern programming environments and design patterns. This guide is intended to highlight some of the key updates and changes, as well as provide information about upgrading from previous versions.
Visit the Beta Downloads page to download the latest version.
The core IPWorks toolkit has been updated with new features which apply to many other toolkits. Below is a list of some of the major new features present in version 2022 products.
.NET Async Functionality
Version 2022 introduces a new async version of the library designed to support asynchronous programming (async/await) for all operations. As a result, the .NET Edition includes several libraries (.dll files) which are supported in different environments. The following libraries are present in the lib directory after installation:
|lib\nsoftware.IPWorks.dll||.NET Framework 4.0 and up||This is the default library which maintains a familiar API in line with previous versions of the product.|
|lib\nsoftware.async.IPWorks.dll||.NET Framework 4.5 and up|
.NET Core 3.0 and up
.NET 5 and up
|The async library supports asynchronous programming patterns. |
|lib\netstandard2.0\nsoftware.IPWorks.dll||.NET Standard 2.0 and up|
|lib\net20\nsoftware.IPWorks.dll||.NET Framework 2.0 and up||This library targets .NET Framework 2.0 and is maintained for legacy projects.|
Asynchronous Programming Support
The async version of the library is designed to support asynchronous programming (async/await) for all operations. In addition, the async library delivers performance improvements for these operations compared to the default version of the library. All versions of the library use non-blocking sockets internally, the async functionality provided in this version of the library is related only to the .NET asynchronous programming model.
The async/await pattern provides a simple way to write sequential code that is easy to understand but also takes advantage of the inherent benefits of asynchronous programming. A common example of this is awaiting an asynchronous task which will wait for the operation to complete but also ensure the UI of an application is responsive and does not appear frozen.
The async version of the library is located in the installation directory at lib\async\nsoftware.async.IPworks.dll. In Visual Studio's intellisense you will see methods which are awaitable and return a System.Threading.Tasks.Task object.
The async library is the recommended version for cross-platform development and supports the following runtime environments:
- .NET 5 and up
- .NET Framework 4.5 and up
- .NET Core 3.0 and up
Refer to the cross-platform demos included with the toolkit for more detailed examples.
Exceptions can be handled using try/catch when awaiting a method. The behavior when using await is the same as when handling exceptions in the synchronous version of the library. There are no special requirements and the exception will contain the same Code and Message property values as the other versions of this library.
If the await keyword is not used, then the exception can be obtained from the task's Exception.InnerException property.
The InvokeThrough property is an optional property which specifies a SynchronizationContext to be used when firing events. When set, the component will fire events within the specified context. A common use case is updating Windows Forms UI elements from within an event of the component. In order to ensure that the UI update does not result in an invalid cross-thread operation set InvokeThrough to a valid value. For instance:
component.InvokeThrough = WindowsFormsSynchronizationContext.Current;
This property is applicable in any project type and may be set to any valid SynchronizationContext such as System.Threading.SynchronizationContext.Current.
The default value is null and no synchronization context will be used.
Note: Use of this property can impact performance and should only be used when necessary.
While the asynchronous methods of the components do return a Task object only one operation can be in progress at any given time. There is no locking mechanism and it is generally considered to be dangerous to create two active tasks which use the same component instance. If multiple concurrent operations are required then multiple component instances should be used.
In most cases upgrading from a previous version is as simple as referencing the updated versions of the library. Every effort has been made to minimize the number of breaking changs to ensure a simple upgrade process. The sections below details some aspects which may be of help while upgrading your project.
Default Installation Location
The installation location in version 2022 defaults to the %UserProfile%\Documents location on the system. In previous versions the installation defaults to the Program Files folder. By installing to the user's Documents folder elevated permission is not needed when building and running the included sample projects.
In version 2022 several properties have been marked as deprecated and have been replaced by corresponding methods. These properties perform a blocking action when set or queried and will be retired in future versions in favor of methods which perform the same functionality. This delivers a more organized and predictable development experience.
Deprecated properties will be maintained through the lifetime of the 2022 version and exist for backwards compatibility. Please consider updating code using these properties to the new corresponding methods.
Properties which have been deperecated will be marked with a * in the table of contents in the documentation and the documentation will provide details about an upgrade path. For instance the FileExists property of the FTP component includes a notice:
In most cases upgrading is seamless and requires no code changes, as efforts have been made to maintain backwards compatibility. However, the latest release includes several API changes that may require code changes. The articles linked below detail major changes between the previous and latest release.
Upgrading to the latest version is designed to be a quick process and involve only minimal code changes while offering additional functionality and options for new and existing users. Please contact us at email@example.com with any questions or comments.
We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at firstname.lastname@example.org.