Docs

IPWorks 2022 .NET Edition

Version 22.0 [Build 8171]

Async Functionality

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.

Cross-Platform Development

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.

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

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.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks 2022 .NET Edition - Version 22.0 [Build 8171]