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.
Using Custom Flags
Section titled “Using Custom Flags”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:
CsvStorageProvider
Section titled “CsvStorageProvider”- Configured by
ContainerExtensions.UseStorageProvider<TStorageProvider>(this IContainer container, params string[] providerNames)-
Extends
abstract class StorageProvider -
Implements
interface IRequiresConfigurationinterface IStorageProvider(throughStorageProvider)
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#.
CsvTimeSeriesDataStoreConfiguration
Section titled “CsvTimeSeriesDataStoreConfiguration”- Configured by
ContainerExtensions.UseTimeSeriesDataStore<CsvStorageProvider, CsvTimeSeriesDataStoreConfiguration>()-
Implements
ITimeSeriesDataStoreConfiguration
This class is simply a placeholder for the name of the data store.
Writing Data
Section titled “Writing Data”TimeSeriesDataCsvStorageWriter
Section titled “TimeSeriesDataCsvStorageWriter”- 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.
Reading Data
Section titled “Reading Data”TimeSeriesDataCsvStorageReader
Section titled “TimeSeriesDataCsvStorageReader”- 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.
Configuration Operations
Section titled “Configuration Operations”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.
CsvRepositoryInformationStore
Section titled “CsvRepositoryInformationStore”- 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"});- Name: A name for the custom registration. It is used for logging and identification.
- Assembly: The assembly in which the method is located.
- RegistrationMethod: The name of the method to call for registration.
- 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 operationsStringArithmeticOperations: 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.