Version 2024 Upgrade Guide

Upgrading from a previous version is usually as simple as referencing the updated library versions. We have minimized breaking changes to ensure a straightforward upgrade process. The sections below offer helpful details for upgrading your project.

Download Products

This guide discusses changes to the 2024 version with technical details. For a more general overview, read the Version 2024 Overview.

Class and Namespace Capitalization
Exception Classes
Removal of Deprecated Properties
Included .NET Platforms
Delphi Event Signatures
API Changes

Upgrade Guide

Class and Namespace Capitalization

Class names have been capitalized in a standard way. In many editions no changes are required. Only affected editions have been listed. Please see below for details about the impact to each edition.

.NET

Component class names have been renamed to use a standard capitalization. For instance Http and Htmlmailer have been renamed to HTTP and HTMLMailer. This change also applies to enum types that contain the component name. For instance HttpAuthSchemes has been renamed to HTTPAuthSchemes.

Java

Component class names have been renamed to use a standard capitalization. For instance Http and Htmlmailer classes have been renamed to HTTP and HTMLMailer.

Swift

Enum types that contain the component name have been renamed to use a standard capitalization. For instance HttpAuthSchemes has been renamed to HTTPAuthSchemes.

JavaScript

Enum types that contain the component name have been renamed to use a standard capitalization. For instance HttpAuthSchemes has been renamed to HTTPAuthSchemes.

Exception Classes

In editions such as .NET where exception objects are instances of a class defined by the library, the exception classes have been consolidated to a single type. Previously exception classes existed for both individual components and the toolkit as a whole. The individual component exception classes have been removed across the board to simplify exception handling.

In addition, a new Source property has been added to all exception classes which reports the name of the component from which the exception was thrown.

The component specific exception classes such as IPWorksHttpException have been removed. Update code to use IPWorksException. For instance:


catch (IPWorksException ex) {
  Console.WriteLine(ex.Message);
  Console.WriteLine(ex.Code);
  Console.WriteLine(ex.Source); //Outputs "HTTP"
}

Java editions did not previously make use of component specific exceptions. However, the Source property is now available. For instance:


catch (ipworks.IPWorksException ex) {
  System.out.println(ex.getMessage());
  System.out.println(ex.getCode());
  System.out.println(ex.getSource());
}

Component specific exception classes such as EipwHTTP have been removed. Update code to use EIPWorks. For instance:


except on E:EIPWorks do begin
  ShowMessage(E.Message);
  ShowMessage(E.Code);
  ShowMessage(E.Source);  //Outputs "HTTP"
end;

C++ Builder editions did not previously make use of component specific exceptions. However, the Source property is now available. For instance:


catch(EIPWCore &ex) {
  ShowMessage(ex.Message);
  ShowMessage(ex.Code);
  ShowMessage(ex.Source); //Outputs "HTTP"
}

Component specific exception classes such as IPWorksHttpError have been removed. Update code to use IPWorksError. For instance:


except IPWorksError as e:
  print(e.message)
  print(e.code)
  print(e.source)

PHP is not affected by this change. Exceptions thrown by the component are of the standard Exception type. For instance:


catch (Exception $ex)
{
  echo $ex->getMessage();
}

Component specific exception classes such as HTTPError have been removed. Update code to use IPWorksError. For instance:


catch IPWorksError.Error(let errorCode, let errorMessage, let source)
{
  print(errorCode)
  print(errorMessage)
  print(source)  //Outputs "HTTP"
}

JavaScript did not previously make use of component specific exceptions. However, the Source property is now available. For instance:


await http.post(url).catch((err) => {
  console.log(err.message);
  console.log(err.code);
  console.log(err.source);
});

C++ does not use exception objects, instead error handling is performed by checking the return code of methods, or by calling the component.GetLastError() and component.GetLastErrorCode() methods.


if (http.GetLastErrorCode()) {
  printf("[%i] %s\n", http.GetLastErrorCode(), http.GetLastError());
}

Removal of Deprecated Properties

Properties which were deprecated in version 2022 have been removed in version 2024. In most cases the deprecated property has been replaced by a corresponding method that performs the same functionality.

Included .NET Platforms

In version 2024 the lib\net40 directory contains a .NET 4.0 library suitable for Windows development and includes design-time support for Visual Studio. The lib\net6.0 directory contains a .NET 6.0 library designed for cross-platform support and includes both the traditional component API as well as a separate nsoftware.async namespace for use with asynchronous programming patterns (async/await). Please refer to the Async Support article for additional details.

The .NET Framework 2.0 and .NET Standard 2.0 libraries are no longer included by default, but are available on demand for legacy projects.

Delphi Event Signatures

Event parameters that are of type string or TBytes are now always marked as const. As a result any event declarations in code may need to be updated to match the current event signature. For instance: //2024 uses "const" for all string and TBytes params //In this example the CertEncoded and CertEncodedB params are defined as "const" procedure TForm1.TCPClient1SSLServerAuthentication(Sender: TObject; const CertEncoded: string; const CertEncodedB: TBytes; const CertSubject, CertIssuer, Status: string; var Accept: Boolean); //Previous versions did not use "const" //In this example the CertEncoded and CertEncodedB params are NOT defined as "const" procedure TForm1.TCPClient1SSLServerAuthentication(Sender: TObject; CertEncoded: string; CertEncodedB: TBytes; const CertSubject, CertIssuer, Status: string; var Accept: Boolean);

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.