Xsbt header definition and Xsbt mapping rules
Xsbt header definition and Xsbt mapping rules
Xsbt header is used to obtain information about the length and ID of the incoming telegram. The mapping rules are used to define the telegram fields.
Table of Contents
Description of Xsbt files
Xsbt files are xml-based files created by the ProconTEL 3 tool Developer Studio, which creates them based on a given Excel sheet with telegrams definition. They contain telegram definitions for encoding and decoding of a byte stream. In most cases there is an xsbt header file that contains a header structure that precedes each telegram message.
Header definition file
The header definition file contains structures that are required to read the received data correctly. The most important fields in this file are the length field and the ID field . Based on this file, the TelegramHeaderDefinition structure can be created. This structure will be used later in modules defined as Producer. The properties of TelegramHeaderDefinition are described in the following table:
| Field Name | Description |
|---|---|
| LengthFieldOffset | Offset in bytes specifying the position of the field describing the length of the message |
| LengthFieldSize | Size in bytes of the message length field |
| IdFieldOffset | Offset in bytes specifying the position of the field describing the ID of the message |
| IdFieldSize | Size in bytes of the message ID field |
Example view of a Xsbt Header file:
<?xml version="1.0" encoding="utf-8"?>
<Telegram name="MyHeaderType" ID="" bytes="6" IsHeaderType="True" ContainsHeaderType="True" xsi:noNamespaceSchemaLocation="http://www.macrix.eu/ProconTel/BinaryXmlTranslationSchema.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<element name="MessageLength" type="Short" length="2" offset="0" HeaderHint="Length" comment="" />
<element name="MessageId" type="Short" length="2" offset="2" HeaderHint="ID" comment="" />
<element name="MessageCount" type="Short" length="2" offset="4" HeaderHint="MessageCounter" comment="" />
</Telegram>
Example view of a telegram that contains a header as the first element:
<?xml version="1.0" encoding="utf-8"?>
<Telegram name="ExampleTelegram" ID="10" Comment="" bytes="14" ContainsHeaderType="True" xsi:noNamespaceSchemaLocation="http://www.macrix.eu/ProconTel/BinaryXmlTranslationSchema.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<element name="HEAD" type="MyHeaderType" length="6" offset="0" count="1" comment="Header">
<element name="MessageLength" type="Short" length="2" offset="0" count="1" comment="" />
<element name="MessageId" type="Short" length="2" offset="2" count="1" comment="" />
<element name="MessageCount" type="Short" length="2" offset="4" count="1" comment="" />
</element>
<element name="FirstField" type="int" length="4" offset="6" count="1" comment="[#]" />
<element name="SecondField" type="int" length="4" offset="10" count="1" comment="[#]" />
</Telegram>
Definition
Namespace: ProconTel.Components.Mapping.Binary.Xsbt
Assembly: ProconTel.Components.Mapping.Binary.dll
Module Installation
Xsbt files handling is a part of Mapping module. To install a Mapping module into project, Nuget Package Manager Console can be used:
Install-Package ProconTel.Components.Communication.Mapping.Binary -ProjectName <ProjectName>
Nuget package can be found in the repository: https://nexus.macrix.eu/repository/pct2022/
Available Pipeline extension methods
There are two extension methods associated with Xsbt files. One that can be used to load header definition and the second one to load mapping rules for telegrams.
UseXsbtHeaderDefinition
This extension method allows loading Xsbt header definition file to fill the TelegramHeaderDefinition structure that is used by other pipeline components.
public static TcpModuleTypeSyntax UseXsbtHeaderDefinition(this TcpConnectionSyntax tcpConnectionSyntax, Action<XsbtHeaderConfiguration> configuration)
The method takes as an argument a XsbtHeaderConfiguration that has following structure
public class XsbtHeaderConfiguration
{
public string? XsbtHeaderDefinitionPath;
public string? LengthFieldName;
public string? IdFieldName;
}
The user must pass three properties to read the header file correctly:
- XsbtHeaderDefinitionPath is a path to the header definition file,
- LengthFieldName, which is the name of a field where the telegram length is stored
- IdFieldName which is the name of a field where the telegram ID is stored.
UseXsbtRules
This extension method allows loading all Xsbt files located in the specified path. All Xsbt files are converted into XDocument objects from which the field structures are created. These field structures can later be accessed by mappers to correctly map the input data to the output data.
public static PipelineBootstrapper UseXsbtRules<TSource, TDestination>(this BinaryMapperRegistrationSyntax<TSource, TDestination> registrationSyntax, Action<XsbtReaderConfiguration> configuration)
The method takes as an argument a XsbtReaderConfiguration that has following structure
public class XsbtReaderConfiguration
{
internal BinaryStreamHandlerType BinaryStreamHandlerType { get; set; } = BinaryStreamHandlerType.ByteArray;
public string? XsbtFolderPath { get; set; }
}
The user can specify the handler type that will be used to read the configuration from Xsbt file. By default the Xsbt file will be read as for simple byte array telegram. User also must pass an XsbtFolderPath, which is a path containing all the xsbt files with mapping rules definitions.
UseXsbtTelegramDefinitions
This extension method is loading all Xsbt files located in specified path similar to UseXsbtRules extension method. Additionally it checks for all validations definitions in passed files which will be used in validation service during telegram handling.
public static TcpConnectionSyntax UseXsbtTelegramDefinitions(this TcpConnectionSyntax tcpConnectionSyntax, Action<XsbtReaderConfiguration> configuration)
Here again the method takes as an argument a XsbtReaderConfiguration which structure is explained above.
Example of usage in code
The following example shows how to define an Xsbt header definition file and how to pass Xsbt mapping rules. All option parameters required by the Xsbt header definition or Xsbt rules can be passed in the appsettings.json file so that they can be easily modified in the ProconTEL app configuration.
builder.Services.AddPipeline(flow =>
flow.OpenTcpPort(55400).UseXsbtHeaderDefinition(opts =>
{
opts.XsbtHeaderDefinitionPath = builder.Configuration["Xsbt:HeaderDefinitionPath"];
opts.LengthFieldName = builder.Configuration["Xsbt:HeaderLengthFieldName"];
opts.IdFieldName = builder.Configuration["Xsbt:HeaderIdFieldName"];
})
.MapBinaryData<MyObject>().UseXsbtRules(opts => opts.XsbtFolderPath = builder.Configuration["Xsbt:XsbtsFolderPath"])
.HandleData<MyObject>().With<MyObjectHandler>());
Where Xsbt appsettings section will look like:
"Xsbt": {
"HeaderDefinitionPath": "D:\\PCT4\\telegrams\\deploy\\MyHeaderType.xsbt.xml",
"HeaderLengthFieldName": "MessageLength",
"HeaderIdFieldName": "MessageId",
"XsbtsFolderPath": "D:\\PCT4\\telegrams\\deploy"
}