How to migrate

This guide describes how to migrate a TwinCAT HMI server extension project from the former TwinCAT HMI server extension API TcHmiSrvExtNet to TcHmiSrvExtNet.Core.

1. Migrate assembly references

These steps migrate the assembly references in your TwinCAT HMI server extension project from version 1.10 to 1.12.
For example, this changes the reference to TcHmiSrvExtNet.dll to TcHmiSrvExtNet.Core.dll.
To migrate all assembly references in your TwinCAT HMI server extension project, follow these steps:

  1. Right-click on the TwinCAT HMI server extension project in the solution explorer.
  2. Click on Migrate References (1.12).

2. Adjust types and namespaces

Your TwinCAT HMI server extension project will now complain about missing types and namespaces that cannot be found.
This is because the newly references assemblies use different namespaces than the old assemblies to clearly distinguish the types.
Follow these steps to tell your TwinCAT HMI server extension project where the missing types and namespaces are:

  1. Replace all occurrences of using TcHmiSrv; with using TcHmiSrv.Core;.
    If you directly refer to the TcHmiSrv namespace in your TwinCAT HMI server extension project (for example: TcHmiSrv.ValueType), replace it with TcHmiSrv.Core.
    This will fix most of the missing types errors in your TwinCAT HMI server extension project.
  2. Remove TcHmiSrv from all listener types that inherit from the IListener interface.
    For example: TcHmiSrvRequestListener -> RequestListener
  3. Add using TcHmiSrv.Core.Listeners; to all C# source files of your TwinCAT HMI server extension project that use listener types that inherit from the IListener interface or use TwinCAT HMI specific event data types that inherit from the EventArgs class.
  4. The ExtensionTypeAttribute class was replaced by ServerExtensionTypeAttribute.
    If you want to use this attribute in your TwinCAT HMI server extension project add a reference to TcHmiSrvExtNet.Tools.TypeAttribute.dll.
  5. If you use TcHmiSrv.DynamicSymbols in your TwinCAT HMI server extension project, replace all occurrences with TcHmiSrv.Tools.DynamicSymbols.
  6. If you use TcHmiSrv.Management in your TwinCAT HMI server extension project, replace all occurrences with TcHmiSrv.Tools.Management.

3. Rename enum constants

As already mentioned in the API Differences, the prefixes have been removed from all enum constants in the TcHmiSrv.Core namespace.

Rename the enum constants in your TwinCAT HMI server extension project to the correct definitions by removing the prefixes.
For example: Severity.Severity_Info -> Severity.Info

4. Change event handler signatures

Event handlers associated with events of listener types that inherit from the IListener and returned an ErrorValue or an instance of the ResultPair class must not return them any more:

  1. Change the return type of event handlers associated with events of listener types that inherit from the IListener and return an ErrorValue or an instance of the ResultPair class to void.
  2. Throw a TcHmiException with the appropriate information in your TwinCAT HMI server extension project instead of returning an ErrorValue or an instance of the ResultPair class that indicates an error.
  3. If you don't return an ErrorValue or an instance of the ResultPair class that indicates an error, you can omit the entire return statement or replace it with an empty return statement depending on the following code in your TwinCAT HMI server extension project.

5. Adjust the initialization method

The signature of the method that initializes your TwinCAT HMI server extension has changed.
Follow these steps to adopt the new signature in your TwinCAT HMI server extension project:

  1. Remove the IExtension interface or ExtensionWithPath abstract base class from the main type of your TwinCAT HMI server extension if it inherits from them.
  2. Implement IServerExtension in the main type of your TwinCAT HMI server extension by removing the parameters from the existing Init(ITcHmiSrvExtHost, Context) method and remove the override modifier if specified.
  3. Do not explicitly register listeners that don't need any settings.
    Listeners that don't need any settings are automatically registered when you add an event handler to one of the events of the listener.
  4. The only listener that currently needs settings is the ConfigListener.
    Use the ConfigListenerSettings class from the TcHmiSrvExtNet.Tools.Settings.dll to create a Value that represents the settings for the ConfigListener class and pass them to the ITcHmiSrvExtHostRegisterListener(Context, IListener, Value) method.
  5. An instance of the ITcHmiSrvExtHost class is provided by the TcHmiApplicationHost property which replaces the first parameter of the previous Init(ITcHmiSrvExtHost, Context) method.
  6. An instance of the Context class is provided by the TcHmiApplicationContext property which replaces the second parameter of the previous Init(ITcHmiSrvExtHost, Context) method.
    You don't need to make a deep copy of the administrator Context because the TcHmiApplicationContext property already returns a deep copy of it.
  7. The path of your TwinCAT HMI server extension is provided by the TcHmiApplicationPath property.

6. Replace the logger

Most TwinCAT HMI server extensions use a custom Log class to send messages to the TwinCAT HMI server and localize text.
A default implementation of this Log class was shipped with the TwinCAT HMI server extension templates.
Since it is a very commom scenario to send messages to the TwinCAT HMI server and localize text, the TcHmiLogger class has now been added.
Follow these steps to replace the custom Log class in your TwinCAT HMI server extension project with the TcHmiLogger class:

  1. Remove the C# source file Log.cs from your TwinCAT HMI server extension project.
  2. Remove all occurrences of the Log class from your TwinCAT HMI server extension project.
  3. Replace the invoked Send and Localize methods with the appropriate TcHmiLoggerSend and TcHmiLoggerLocalize methods.
    Note that the order of the parameters when sending a Message has changed to support specifying multiple params string[] parameters more easily.

7. Migrate methods

Unlike most properties, many method names and signatures of the CommandGroup and Value classes have changed to implement the IListT and / or IDictionaryTKey, TValue interfaces.
If you're using such methods in your TwinCAT HMI server extension project, take a look at the API Differences to see how they can be replaced.

8. Replace iterators

The CommandVectorIterator, ValueVectorIterator and ValueIterator classes were removed because they were considered unsafe when the underlying collection was modified.
To access Commands in a CommandGroup and Values in a Value, use the methods and indexers provided by the implementation of the IListT and IDictionaryTKey, TValue interfaces instead.

9. Adjustments for dynamic symbols (only required if you used TcHmiSrvExtNet.DynamicSymbols)

The implementation of DynamicSymbols was completely replaced by Newtonsoft.Json and Newtonsoft.Json.Schema as well as the TcHmiSrv.Core.Tools.Json, TcHmiSrv.Core.Tools.DynamicSymbols and TcHmiSrv.Core.Tools.Resolving namespaces.
There is no one-to-one guide, as with the other sections, for the necessary adjustments for dynamic symbols, because these may have been implemented very differently depending on the TwinCAT HMI server extension.
Instead, the new concept for implementing dynamic symbols in TwinCAT HMI server extensions using the current API will be shown here. A good starting point for this is the documentation of the TcHmiSrv.Core.Tools.DynamicSymbols namespace, which explains the basic concepts for providing dynamic symbols in TwinCAT HMI server extensions.

Other Resources

API Differences Version 1.10.1018.48

Copyright © Beckhoff Automation GmbH & Co. KG