Version 2.0.0.0

TcHmiSrvExtNet.Core version 2.0.0.0 was released on September 21, 2022.

New features (breaking changes) in this release

The following references were updated:
ReferenceOld versionNew versionNewtonsoft.Json12.0.313.0.1Newtonsoft.Json.Schema3.0.133.0.14System.Text.Json5.0.06.0.5
Reference Microsoft.VisualStudio.Threading version 17.2.32 was added.
The following methods now return an ErrorValue to indicate whether the operation succeeded:

The following methods were added to allow specifying for which domain an IListener should be registered without having to change the Context:

Indexers ValueItemString and ValueItemInt32 throw a InvalidOperationException when trying to set a value if ValueIsMapOrStruct respectively ValueIsVector is false.
A setter was added to property BeforeChangeEventArgsValue to allow TwinCAT HMI server extensions to change the Value written into the configuration.
Property CommandSubsymbolHandled was added to control the handling of subsymbols. Subsymbols are automatically resolved according to the property CommandPath. Therefore, after returning from the event handlers of the RequestListenerOnRequest and RequestListenerOnRequestAsync events, the property CommandReadValue is read from each Command where CommandSubsymbolHandled is false, resolved using the property CommandPath and the Value of the subsymbol is assigned to the property CommandReadValue again.
TwinCAT HMI server extensions that previously used the property CommandPath to resolve subsymbols must not do this anymore. Instead, they must assign the entire Value to the property CommandReadValue. TwinCAT HMI server extensions that should continue to resolve subsymbols on their own must now set the property CommandSubsymbolHandled to true to disable automatic resolution of subsymbols by the TwinCAT HMI extension container.
If the property CommandReadValue is not null, but cannot be resolved by the property CommandPath after returning from the event handlers of the RequestListenerOnRequest or RequestListenerOnRequestAsync events, an appropriate exception is thrown.

These changes also affect instances of the DynamicSymbolsProvider class when reading or writing Symbols. The property CommandSubsymbolHandled is set to true if there are no elements in the instance of the QueueT class after returning from the appropriate SymbolRead(QueueString) or SymbolWrite(QueueString, Value) method. Otherwise, the property CommandSubsymbolHandled is set to false.
Properties Symbol.Function, Symbol.ReadOnly and Symbol.Doc were replaced with property SymbolAttributes. The constructor parameters function, readOnly and doc of classes Symbol, SymbolWithValue and SymbolWithDirectValue were also replaced with attributes and thus superfluous constructors were removed.
Class DynamicSymbolsProvider now implements the IDisposable interface.
Class AsyncSymbol was added to read and write dynamic symbols asynchronously.
Methods DynamicSymbolsProviderHandleCommands(CommandGroup, Context) and DynamicSymbolsProviderHandleCommandsAsync(CommandGroup, Context) were added to handle a CommandGroup under the specified Context synchronously or asynchronously.
Therefore, the following methods have been removed and replaced with new equivalent methods that have an additional context parameter and are asynchronous where applicable:

DynamicSymbolsProviderHandleCommand(Command) was replaced by DynamicSymbolsProviderHandleCommandAsync(Command, Context).
DynamicSymbolsProviderHandleException(Command, Exception) was replaced by DynamicSymbolsProviderHandleExceptionAsync(Command, Context, Exception).
SymbolRead(QueueString) was replaced by SymbolRead(QueueString, Context).
SymbolWrite(QueueString, Value) was replaced by SymbolWrite(QueueString, Value, Context).
SymbolWithValueRead(QueueString) was replaced by SymbolWithValueRead(QueueString, Context).
SymbolWithValueWrite(QueueString, Value) was replaced by SymbolWithValueWrite(QueueString, Value, Context).

The following types, properties and property accessors, that are marked with the ObsoleteAttribute in the prior version of this API were removed:

It is not possible anymore to register listeners that inherit from the IListener interface under domains other than the domain of the registering TwinCAT HMI server extension or TcHmiSrv.
This restriction is necessary because when unloading a TwinCAT HMI server extension all listeners registered under this domain are unregistered without notifying the TwinCAT HMI server extension that registered the listeners. When the TwinCAT HMI server extension is reloaded, the listeners are not automatically re-registered, which can lead to unexpected behavior in the TwinCAT HMI server extension that registered the listeners, since its event handlers are not called anymore.
For consistency reasons, instances of class ConfigListener are now also automatically registered and unregistered when the first event handler is added or the last event handler is removed. The default settings for automatic registration are ConfigListenerSettingsDefault.
To prevent automatic registration set TcHmiApplicationAutoRegisterListeners to false before adding event handlers.

Other Resources

Version History