Skip to content
Documentation

Example 3: Advanced Features

These following examples demonstrate more complicated use cases of the PowerTSM .NET API. They customize different aspects of the framework which enables the user to work with any type of data they wish. These customizations include:

  • Flags: Configures custom flags to accommodate any type of data property
  • Storage Provider: Defines a new environment where data can be saved aside from a SQL Database
  • Value Types: Specifies a new data type with which the API can then perform operations.

Instead of just calling ITsm.Create() you can add a function to perform additional configuration. This can be done by passing a lambda expression that calls UseCustomFlag(value, priority, name) as done in the example. The second parameter true is passed to make sure all other defaults are still configured.

Additionally the example demonstrates simple operations with custom flags, which should be pretty much self explanatory.

Using a Custom Time Series Data Storage Registered Through Container Extension

Section titled “Using a Custom Time Series Data Storage Registered Through Container Extension”

The .NET API comes with three default storage providers: Oracle, Microsoft SQL Server and PostgreSQL. To add custom storage providers, a series of C# classes have to be defined and later configured in the creation of the ITsm object. The example demonstrates this in the form of a csv storage provider. The goal is to write the time series data in this data format and save the file as a csv table.

The configuration is done within the ITsm.Create() function by a lambda operation which relies heavily on dependency injection. In this case, it calls the method UseCustomDataStore() which in turn runs a series of operations that set the correct behavior for the ITsm object:

var tsm = ITsm.Create((container) =>
{
container.UseCustomDataStore();
}, true);

These are the classes needed to implement a functioning csv storage provider:

  • Configured by
ContainerExtensions.UseStorageProvider<TStorageProvider>(this IContainer container, params string[] providerNames)
  • Extends abstract class StorageProvider

  • Implements

    • interface IRequiresConfiguration
    • interface IStorageProvider (through StorageProvider)
Required overrides
StorageProvider.ApplyProviderSettings(IReadOnlyDictionary<string, string> settings)

This class serves as the access point to the csv file and particularly its settings. The ApplyProviderSettings() method fetches the settings out of the HAKOM.xml file and sets them as attributes. These are relevant for operations in the csv data format. They include:

  • the root directory in which the csv file is located
  • the separation character
  • the encoding
  • the number of lines that should be skipped when reading and writing data

The remaining methods perform the low level changes on the csv file. These are C# System.IO operations which are not specific to the .NET API. Their responsibilities are:

  • Open and close a stream pointing to the csv file (OpenWritingStream(), CloseWritingStream())
  • Write a single line into the stream (Write())
  • Read all data with filters(ReadAll())
  • Delete specific data (DeleteData())
  • Delete File (DeleteFile())

This class is not even restricted to time series. It is just a general implementation of csv operations in C#.

  • Configured by
ContainerExtensions.UseTimeSeriesDataStore<CsvStorageProvider, CsvTimeSeriesDataStoreConfiguration>()
  • Implements

    • ITimeSeriesDataStoreConfiguration

This class is simply a placeholder for the name of the data store.

  • Configured by
ContainerExtensions.UseTimeSeriesDataStorageWriter<TStorageProvider, TConfiguration, TTimeSeriesDataStorageWriter>(this IContainer container)
  • Implements

    • ITimeSeriesDataStorageWriter<,>
    • IRequiresConfiguration
Required overrides
Task<ITimeSeriesDataCollectionStorageWriter<TValue>> BeginWritingCollection<TValue>(DateTimeOffset historicDateTime, CancellationToken cancellationToken = default) where TValue : IComparable<TValue>, IEquatable<TValue>;
Task Configure(TStorageProvider storageProvider, ITimeSeriesReference timeSeriesReference, ITsmRepositoryInformation repositoryInformation, TConfiguration configuration, CancellationToken cancellationToken = default);
Task Delete(Period deletionPeriod, CancellationToken cancellationToken = default);
Task Delete(CancellationToken cancellationToken = default);
Task Delete(TConfiguration configuration, CancellationToken cancellationToken = default);
Task<bool> SupportsValueType<TValue>(CancellationToken cancellationToken = default) where TValue : IComparable<TValue>, IEquatable<TValue>;
Task<bool> SupportsValueType(Type type, CancellationToken cancellationToken = default);
Task WriteAuditLog(IAuditLogEntry auditLogEntry, CancellationToken cancellationToken = default);

This class implements a more abstract part of the csv write operations. Its main concern is orchestrating the CsvStorageProvider class to perform the actual writes. It puts the csv operations into the context of time series. For example the Delete() method deletes data in a given a time period by calling DeleteData() on the storage provider. It performs write singular write operations where no collection is necessary such as deleting data in a time period. Write operations where a data collection is used are delegated to the TimeSeriesDataCollectionCsvStorageStreamWriter.

The BeginWrite() method could be used to write a single data point to a time series but is not implemented here. The BeginWritingCollection<>() uses a TimeSeriesDataCollectionCsvStorageStreamWriter and calls BeginWrite() there, to write the whole collection.

Apart from that it also takes care of the persistence of time series objects and configures their metadata.

A concrete description of what each method is supposed to implement can be found in the XML documentation comments in the ITimeSeriesDataStorageWriter interface.

TimeSeriesDataCollectionCsvStorageStreamWriter<TValue>

Section titled “TimeSeriesDataCollectionCsvStorageStreamWriter<TValue>”
  • Configured by
ContainerExtensions.UseTimeSeriesDataCollectionStorageWriter<TValue, TStorageProvider, TTimeSeriesDataCollectionStorageWriter>(this IContainer container)
  • Implements

    • ITimeSeriesDataCollectionStorageWriter<TValue>
    • IRequiresConfiguration
Required overrides
void Configure(ITimeSeriesReference timeSeriesReference, ITsmRepositoryInformation repositoryInformation, ITimeSeriesDataStoreConfiguration configuration, DateTimeOffset historicDateTime);
Task Flush(CancellationToken cancellationToken = default);
Task<Result> TryFlush(CancellationToken cancellationToken = default);
Task Write(IAsyncEnumerable<ITimeSeriesData<TValue>> collection, CancellationToken cancellationToken = default);
Task WriteWithHistoricData(ITimeSeriesData<TValue> data, CancellationToken cancellationToken = default);
  • Type Parameter

    • TValue: placeholder for the type of the stored data points.

This class is handled by the TimeSeriesDataCsvStorageWriter. It provides the Write() and methods for data collections and buffer management via the methods TryFlush(), Dispose() and DisposeAsync() for resource management.

Sequence diagram of writing a data collection to the CSV storage provider: the container configures the storage writer, stream writer and CSV storage provider, then the time series data store writes each item through a stream writer and flushes and disposes it

  • Configured by
ContainerExtensions.UseTimeSeriesDataStorageReader<TStorageProvider, TConfiguration, TTimeSeriesDataStorageReader>(this IContainer container)
  • Implements

    • ITimeSeriesDataStorageReader<,>
    • IRequiresConfiguration
Required overrides
Task Configure(TStorageProvider storageProvider, ITimeSeriesReference timeSeriesReference, ITsmRepositoryInformation repositoryInformation, TConfiguration configuration, CancellationToken cancellationToken = default);
Task<ITimeSeriesData<TValue>?> GetNextData<TValue>(DateTimeOffset dateTime, CancellationToken cancellationToken = default) where TValue : IComparable<TValue>, IEquatable<TValue>;
Task<ITimeSeriesData<TValue>?> GetPreviousData<TValue>(DateTimeOffset dateTime, CancellationToken cancellationToken = default) where TValue : IComparable<TValue>, IEquatable<TValue>;
IAsyncEnumerable<ITimeSeriesData<TValue>> Read<TValue>(Period period, CancellationToken cancellationToken = default) where TValue : IEquatable<TValue>, IComparable<TValue>;
IAsyncEnumerable<IAuditLogEntry> ReadAuditLogs(DateTimeOffset historicDateTime, Period period, CancellationToken cancellationToken = default);
IAsyncEnumerable<ITimeSeriesData<TValue>> ReadHistoricData<TValue>(DateTimeOffset historicDateTime, Period period, CancellationToken cancellationToken = default) where TValue : IEquatable<TValue>, IComparable<TValue>;
Task<bool> SupportsValueType<TValue>(CancellationToken cancellationToken = default) where TValue : IComparable<TValue>, IEquatable<TValue>;
Task<bool> SupportsValueType(Type type, CancellationToken cancellationToken = default)
Task<Result<ITimeSeriesData<TValue>?>> TryGetNextData<TValue>(DateTimeOffset dateTime, CancellationToken cancellationToken = default) where TValue : IComparable<TValue>, IEquatable<TValue>;
Task<Result<ITimeSeriesData<TValue>?>> TryGetPreviousData<TValue>(DateTimeOffset dateTime, CancellationToken cancellationToken = default) where TValue : IComparable<TValue>, IEquatable<TValue>;
IAsyncEnumerable<Result<ITimeSeriesData<TValue>>> TryRead<TValue>(Period period, CancellationToken cancellationToken = default) where TValue : IEquatable<TValue>, IComparable<TValue>;
IAsyncEnumerable<Result<IAuditLogEntry>> TryReadAuditLogs(DateTimeOffset historicDateTime, Period period, CancellationToken cancellationToken = default);
IAsyncEnumerable<Result<ITimeSeriesData<TValue>>> TryReadHistoricData<TValue>(DateTimeOffset historicDateTime, Period period, CancellationToken cancellationToken = default) where TValue : IEquatable<TValue>, IComparable<TValue>;

This class is the reading counterpart of the TimeSeriesDataCsvStorageWriter and fills a similar role. It manages the CsvStorageProvider read operations. As opposed to writing operations, there is no dedicated class for streams, as the data is not buffered when reading.

Sequence diagram of reading data from the CSV storage provider: the time series data store calls the CSV storage reader, which loads its configuration and reads all CSV lines through a stream reader, parsing each line into time series data

TimeSeriesDataCsvStorageConfigurationReader

Section titled “TimeSeriesDataCsvStorageConfigurationReader”
  • Configured by
ContainerExtensions.UseTimeSeriesDataStorageConfigurationReader<TStorageProvider, TConfiguration, TTimeSeriesDataStorageConfigurationReader>(this IContainer container)
  • Implements

    • ITimeSeriesDataStorageConfigurationReader<,>
    • IRequiresConfiguration
Required overrides
Task Configure(TStorageProvider storageProvider, ITimeSeriesReference timeSeriesReference);
Task<TConfiguration?> LoadConfiguration(CancellationToken cancellationToken = default);
IAsyncEnumerable<TConfiguration> LoadConfigurations(CancellationToken cancellationToken = default);
IAsyncEnumerable<Result<TConfiguration>> TryLoadConfigurations(CancellationToken cancellationToken = default);

This class uses the CsvTimeSeriesDataStoreConfigurationFactory to derive the filename of the csv to any given time series. In this case empty spaces get replaced with underscores and “.csv” is appended. In a more complicated setting, the configuration might be read from a file or fetched from a database.

TimeSeriesDataCsvStorageConfigurationWriter

Section titled “TimeSeriesDataCsvStorageConfigurationWriter”
  • Configured by
ContainerExtensions.UseTimeSeriesDataStorageConfigurationWriter<CsvStorageProvider, CsvTimeSeriesDataStoreConfiguration, TimeSeriesDataCsvStorageConfigurationWriter>()
  • Implements

    • ITimeSeriesDataStorageConfigurationWriter<,>
    • IRequiresConfiguration
Required overrides
void Configure(TStorageProvider storageProvider, ITimeSeriesReference timeSeries);
Task SaveConfiguration(TConfiguration configuration, CancellationToken cancellationToken = default);
Task<Result> TrySaveConfiguration(TConfiguration config, CancellationToken cancellationToken = default);

This class is pretty much useless in the example setting. Its purpose is to perform changes to a configuration file.

CsvTimeSeriesDataStoreConfigurationFactory

Section titled “CsvTimeSeriesDataStoreConfigurationFactory”
  • Configured by
ContainerExtensions.Use<ITimeSeriesDataStoreConfigurationFactory, CsvTimeSeriesDataStoreConfigurationFactory>()
  • Implements

    • ITimeSeriesDataStoreConfigurationFactory

This class is used by TimeSeriesDataCsvStorageConfigurationReader to create the .csv filename of a given time series.

  • Configured by
ContainerExtensions.UseTsmRepositoryInformationStore<CsvStorageProvider, CsvRepositoryInformationStore>();
  • Implements

    • IRepositoryInformationStore<>
    • IRequiresConfiguration
Required overrides
Task<TRepositoryInformation> Load(CancellationToken cancellationToken = default);
Task<Result<TRepositoryInformation>> TryLoad(CancellationToken cancellationToken = default);

This class provides access to the repository information like its name, time base and version. In this simple example these values are basically hardcoded but could, in a different setting, be fetched from a database.

Using a Custom Time Series Data Storage Registered Through Configuration

Section titled “Using a Custom Time Series Data Storage Registered Through Configuration”

This demonstration achieves the exact same result as the one before, just through different means. Instead of calling the container.UseCustomDataStore() method directly, it uses a configuration dictionary that points to the extension method that should be called.

builder.AddInMemoryCollection(new Dictionary<string, string?>() {
["DependencyInjection:CustomRegistrations:CustomRegistration:Custom_Data_Store:Name"] = "Custom_Data_Store",
["DependencyInjection:CustomRegistrations:CustomRegistration:Custom_Data_Store:Assembly"] = "3_Advanced_Features.dll",
["DependencyInjection:CustomRegistrations:CustomRegistration:Custom_Data_Store:RegistrationMethod"] = "UseCustomDataStore",
["DependencyInjection:CustomRegistrations:CustomRegistration:Custom_Data_Store:ClassName"] = "Advanced_Features.UsingACustomTimeSeriesDataStorage.ContainerExtensions"
});
  1. Name: A name for the custom registration. It is used for logging and identification.
  2. Assembly: The assembly in which the method is located.
  3. RegistrationMethod: The name of the method to call for registration.
  4. ClassName: The name of the class that contains the registration method.

After that, .UseConfiguration() has to be called on the container and true has to be passed as a second parameter on the ITsm.Create() method call. After that the usage of the custom configuration and classes that need to be created is exactly the same an in the example above.

The same registration can be expressed in HAKOM.xml instead of an in-memory dictionary. Note that Name is set as an attribute on the <CustomRegistration> element, not as its own nested tag:

<HAKOM>
<DependencyInjection>
<CustomRegistrations>
<CustomRegistration Name="Custom_Data_Store">
<Assembly>3_Advanced_Features.dll</Assembly>
<RegistrationMethod>UseCustomDataStore</RegistrationMethod>
<ClassName>Advanced_Features.UsingACustomTimeSeriesDataStorage.ContainerExtensions</ClassName>
</CustomRegistration>
</CustomRegistrations>
</DependencyInjection>
</HAKOM>

See Dependency Injection Configuration for the full configuration reference, including the JSON and environment variable equivalents.

Using a Custom Time Series Data Value Type

Section titled “Using a Custom Time Series Data Value Type”

This example demonstrates how to implement a custom data store system that works with non-standard value types. Specifically string values instead of the default double. The main addition in the ITsm.Create() container operation is this reference to the definition of the arithmetic operations:

.UseWithParameter<Type, IArithmeticOperations, StringArithmeticOperations>(
(arithmeticOperationsGenericImplementationType) => arithmeticOperationsGenericImplementationType == typeof(string),
(arithmeticOperations, arithmeticOperationsGenericImplementationType) => { return; }
)
.UseDefaultDataTransformer<string>();

Type parameters:

  • Type: The type to check against (the generic type parameter of time series data)
  • IArithmeticOperations: The interface that defines arithmetic operations
  • StringArithmeticOperations: The concrete implementation that will handle string arithmetic

The method takes two parameters:

Func<TParameter, bool> parameterMatcher, Action<TService, TParameter>?

The first one is a function that gets configured to match the type of an encountered data value against String. When performing arithmetic operations on data values, its type gets compared to all configured operation classes. When one returns true (as this one would for a String) its corresponding operations class gets used (here StringArithmeticOperations.

The second parameter is an Action which provides the opportunity to run code on the created StringArithmeticOperations class. This can be used for configuration that should not be in the constructor, logging etc.

The class StringArithmeticOperations implements the specific behavior of arithmetic operations for the desired data type. In the example they are not implemented and serve as placeholders.

The responsibilities of each class largely stay the same as in the above examples. Of course the implementations of the methods needs to be different to account for the different data types.

© 2026 Volue.Version v0.6.38017 November 2026