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.

Contents

Overview

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.

New Features

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
  • Installation changes for a better developer experience
  • Updated documentation for improved navigation and searching
  • HTTP/3 Support
  • Support for OCSP when establishing TLS connections
  • Improved certificate handling across the board for a consistent experience on different platforms
  • Support for Relaxed JSON
  • Proxy PAC URL support
  • New TFTPServer component
  • Update IPv6 logic for a better experience when falling back to IPv4
  • Improvements in Plain C interface
  • Swift useability improvements
  • FMX Support

.NET Async Functionality

Version 2022 introduces a new async version of the API 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:

Library Supported Runtimes Comments
lib\nsoftware.IPWorks.dll .NET Framework 4.0 and up
.NET Core 3.0 and up
.NET 5 and up
This is the default library which maintains a familiar API in line with previous versions of the product. Support for asynchronous programming patterns (async/await) is exposed in a separate nsoftware.async.IPWorks namespace.
lib\netstandard2.0\nsoftware.IPWorks.dll .NET Standard 2.0 and up The .NET Standard library provides cross-platform support while maintaining the same API as the default library in lib.
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

An async version of the API designed to support asynchronous programming (async/await) is available in the nsoftware.async.IPWorks namespace. Both the default (sync) and the async APIs are present in the same library located in the installation directory at lib\nsoftware.IPWorks.dll.

The async version of the API is designed to support asynchronous programming (async/await) for all operations. In addition, the async API delivers performance improvements for these operations compared to the default version of the API. In Visual Studio's intellisense you will see methods which are awaitable and return a System.Threading.Tasks.Task object.

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.

All versions of the API use non-blocking sockets internally, the async functionality provided in this version of the API is related only to the .NET asynchronous programming model.

Cross-Platform Development

The async API can be used 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 async demos included with the toolkit for more detailed examples.

Error Handling

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 API. 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.

InvokeThrough

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.

Concurrency Notes

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.

Upgrade Guide

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.

InvokeThrough Property

The InvokeThrough property in version 2022 is of type System.Threading.SynchronizationContext. In previous versions the InvokeThrough property was of type System.Windows.Forms.Control.

The InvokeThrough property is designed to be used in Windows Forms applications and allows for events to be fired from the main thread so that code within the events can directly update UI elements on the form without performing a cross-thread operation. To use InvokeThrough in version 2022 in a Windows Forms application code like below may be used:

component.InvokeThrough = WindowsFormsSynchronizationContext.Current;

Deprecated Properties

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:

C++ Edition Updates

C++ Editions have been updated across the board to provide a more consistent and simpler development experience.

Qt Support

All Qt Editions have been removed, and Qt support is now included as part of the C++ editions. Qt is supported on all platforms including Windows, Linux, and macOS. For more details, see the article Getting Started with Qt.

Removal of OpenSSL Dependencies in Linux

The C++ Edition libraries for Linux have been updated to use the internal implementation of SSL/TLS and other cryptographic functions. OpenSSL is no longer a dependency when working on Linux and the linker options -lssl -lcrypto are not needed.

To enable OpenSSL support within the toolkit the obfuscated source code can be compiled with the -D ENABLE_OPENSSL option. For instance a makefile may look like:

mytarget: ./src/ipworks.o
        g++ -D UNIX -o myapp ./src/ipworks.o myapp.cpp -I./include/ -lz -ldl -lssl -lcrypto

./src/ipworks.o:
        g++ -c -fno-exceptions -fno-rtti -fPIC -D ENABLE_OPENSSL -o ./src/ipworks.o ./src/ipworks.cpp

When enabled, the linker options for the project using the library must include -lssl -lcrypto. Note that components must still be configured to use the OpenSSL implementation by setting the SSLProvider property to 1 (Platform).

API Changes

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 support@nsoftware.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 kb@nsoftware.com.