TcHmiSrv.Core.Tools.DynamicSymbols Namespace

Classes

Remarks

This implementation replaces the TcHmiSrv.DynamicSymbols.TcHmiSchemaGenerator class.
Dynamic symbols are exposed through an instance of the DynamicSymbolsProvider class. It represents a collection of symbols provided by a TwinCAT HMI server extension.
The DynamicSymbolsProvider class implements the IDictionaryTKey, TValue interface, which makes it easy to add new symbols with DynamicSymbolsProvider.Add(string, Symbol) and remove existing symbols with DynamicSymbolsProvider.Remove(string) at runtime of the TwinCAT HMI server extension.
There are also many other methods to read and modify the contents of a DynamicSymbolsProvider. Just take a look at its documentation to explore them all.

When adding a new symbol to the DynamicSymbolsProvider using DynamicSymbolsProvider.Add(string, Symbol), DynamicSymbolsProvider.AddOrUpdate(string, Symbol) or the IDictionaryTKey, TValue indexer, you have to provide a String and an instance of a type derived from the abstract Symbol class:

• key String
  Represents the name of the symbol to add. This String must be an unique key, just like every symbol offered by a TwinCAT HMI server extension is unique. The name of the symbol is addressed by the Command.Mapping property.
• Symbol symbol
  Represents the symbol to add, including its schema and value:
• The schema of the symbol must be constant and can be specified in the constructor when initializing a new instance of the Symbol class. Schemes of the readValue and writeValue are represented by instances of the JsonSchemaValue class, whereas function, readOnly and doc can be specified directly by an instance of the corresponding type. JsonSchemaValues can be created either by a manually constructed instance of the Value class containing a valid JSON schema, or by an automatically generated JSchema . The TcHmiJSchemaGenerator is also able to create a JsonSchemaValue for a specified Type by calling TcHmiJSchemaGenerator.Generate(Type) .
• The value of the symbol is represented by the abstract Symbol.Read(Queue{string}, Context) and Symbol.Write(Queue{string}, Value, Context) methods, which allow to read or write the value of the symbol itself or any of its sub-elements.
  The value to be read or written is wrapped in an instance of the Value class, because it can store values of all types supported by the TwinCAT HMI server.
  To access a sub-element of the current value of the symbol, a QueueT containing the path to the sub-element is passed to the Symbol.Read(Queue{string}, Context) and Symbol.Write(Queue{string}, Value, Context) methods to determine the sub-element to be read or written. The QueueT is normally created from the Command.Path property. Call Queue{T}.Dequeue to get the name of the next sub-element until Queue{T}.Count== 0 is true and then read or write the current element. You can use a ResolveHandler from the TcHmiSrv.Core.Tools.Resolving namespace to read or write sub-elements of almost any .NET type.
  Since TcHmiSrvExtNet.Core version 2.0.0.0 reading a sub-element of the current value of the symbol can be done automatically by the TwinCAT HMI extension container according to the Path. To do this, leave the QueueT untouched and just return the root value of the symbol when Symbol.Read(Queue{string}, Context) is called.
  There are also the SymbolWithValue and SymbolWithDirectValue classes, which have already implemented Symbol.Read(Queue{string}, Context) and Symbol.Write(Queue{string}, Value, Context) by using a RecursiveResolveHandlerT with the RecursiveValueResolver.DefaultResolver to read and write the SymbolWithValue.Value property.

Now, how are the dynamic symbols provided by your TwinCAT HMI server extension with DynamicSymbolsProvider ?
First of all, dynamic symbols are provided by two function symbols that the TwinCAT HMI Server calls for each TwinCAT HMI server extension that implements them. Therefore, you have to add the following lines to the "symbols" property in the Config.json of your TwinCAT HMI server extension:

C#

"ListSymbols": {
  "readValue": {
    "function": true
  }
},
"GetSchema": {
  "readValue": {
    "function": true
  }
}

Which information does each of the above symbols provide? Let's take a quick look at them:

• ListSymbols
  Lists the dynamic symbols of a TwinCAT HMI server extension with their names and schemes. If the schemes contain definitions, they're also listed here.
• GetSchema
  Gets the schema of a specified symbol or sub-symbol. The path of the symbol or sub-symbol whose schema should be retrieved is specified as a String in the Command.WriteValue property.

After declaring the required symbols ListSymbols and GetSchema by adding them to the Config.json of your TwinCAT HMI server extension, they still need to be defined by implementing them. But don't worry: You don't have to do this on your own!
The Symbol class that was mentioned above already contains all the necessary information that must be returned for the above symbols. Therefore, you only have to pass the CommandGroup specified by the OnRequestEventArgs.Commands property of the RequestListener.OnRequest event handler to the DynamicSymbolsProvider.HandleCommands(CommandGroup) method as in the following piece of code where this.provider represents the instance of the DynamicSymbolsProvider class:

C#

foreach (Command command in this.provider.HandleCommands(e.Commands))
{
    // Get the mapping from the current command
    string mapping = command.Mapping;

    try
    {
    // Use the mapping to check which command is requested
    switch (mapping)
    {
        // Handle commands for non-dynamic symbols here
        ...
    }
    }
    catch
    {
    // Handle exceptions for non-dynamic symbols here
    ...
    }
}

This adds the appropriate information to the Command.ReadValue property of the ListSymbols and GetSchemaCommands.
Furthermore, DynamicSymbolsProvider.HandleCommands(CommandGroup) also handles Commands for reading and writing dynamic symbols by calling the Symbol.Read(Queue{string}, Context) and Symbol.Write(Queue{string}, Value, Context) methods mentioned above.
Non-dynamic symbols and symbols other than ListSymbols and GetSchema included in the Config.json of your TwinCAT HMI server extension cannot be handled by DynamicSymbolsProvider.HandleCommands(CommandGroup) . To not ignore them, unhandled Commands are returned as an IEnumerableT so that you can handle them normally in your TwinCAT HMI server extension.

NOTE:
In previous versions of the TwinCAT HMI Server, the symbol GetDefinitions was also required to provide dynamic symbols. Although it's not required anymore, the method DynamicSymbolsProvider.HandleCommands(CommandGroup) still handles this symbol for backward compatibility reasons.

Copyright © Beckhoff Automation GmbH & Co. KG