Skip to content
Documentation

Migrating .NET API Clients from 3.x to 4.x

The .NET API was formerly known as the HAKOM Framework. This name was changed starting with version 4.0, to reflect that these libraries are designed exclusively for Microsoft’s .NET ecosystem.

Because version 4.0 was written from the ground up, applications that use classes and functions from the legacy HAKOM Framework also need to be completely rewritten. However, the differences are well worth the effort:

Clear Separation of API and Implementation

Section titled “Clear Separation of API and Implementation”

The legacy HAKOM Framework often did not make it clear which types are part of the API, and which types are implementation details for our internal use only. This led to many client applications using types and methods they were not supposed to. When these internal types were modified in order to add features, client applications ended up breaking.

Starting with version 4.0 concrete implementations will be hidden from the API user (i.e. marked as internal). This

  • makes it clear what API consumers should and shouldn’t use.
  • provides more flexibility for adding/modifying implementation details without breaking client applications.

Inversion of Control and Dependency Injection

Section titled “Inversion of Control and Dependency Injection”

When referencing one of the NuGet packages, very few types can be “just instantiated”. This is on purpose. Except for a few abstract classes, extension methods and custom exceptions, the PowerTSM API consists almost exclusively of interfaces.

This is deliberate. One core idea behind the redesign in 4.0 was to make extensibility much easier. By making sure client applications only deal with interfaces, the API can

  • make different implementations of the same interface available, allowing different applications to use different preferences
  • allow client applications to implement these interfaces and thus modify the behavior of individual parts of the PowerTSM system without waiting for a feature request to be evaluated and implemented.

Working with time series almost always involves interacting with services, databases, or files. This means that application logic spends much of its time idle, waiting for HTTP requests, database queries, and disk I/O. The latest version of the API reflects that, and anything that interacts with external data is written as asynchronous functions returning a .NET Task.

This enables applications that stay responsive and use CPU cycles as efficiently as possible.

The reality is that things can and will go wrong. Databases become overloaded, networks go down, services crash, and files become corrupted.

The API is designed to handle failure gracefully rather than leaving calling code to deal with unexpected exceptions.

To this end, whenever failures can be anticipated in a method, this is acknowledged by returning a Result<> type instead of raw data. This enables efficient failure checking without having to wrap entire call sites in try-catch blocks.

Custom Exception types are also provided for all anticipated errors (derived from HAKOM.ErrorHandling.Core.Net.Api.HakomException), with the most meaningful error messages possible and additional data related to the error as properties on the exception instance.

To speed up debugging and analysis, all exceptions come with a standardized code that is also added as a prefix to the exception message. This makes it easier to categorize error occurrences and find documentation about possible causes and remedies.

The configuration of PowerTSM functionality has been completely overhauled to provide more flexibility.

While the legacy HAKOM Framework required a specific XML file in a specific location, the following configuration formats are now supported out of the box:

  • XML files
  • JSON files
  • Environment variables

Configuration data can also be linked and imported from one source into another, allowing specific configuration to be scoped to specific users, environments, etc.

For cases where that is still not flexible enough, alternative configuration sources can be added in code.

© 2026 Volue.Version v0.6.38017 November 2026