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 TcHmiSrv.Core.Listeners.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 TcHmiSrv.Core.Listeners.IListener interface or use TwinCAT HMI specific event data types that inherit from the System.EventArgs class.
  4. The TcHmiSrv.Management.ExtensionTypeAttribute class was replaced by TcHmiSrv.Core.Tools.TypeAttribute.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 TcHmiSrv.Core.Listeners.IListener and returned an TcHmiSrv.ErrorValue or an instance of the TcHmiSrv.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 TcHmiSrv.Core.Listeners.IListener and return an TcHmiSrv.ErrorValue or an instance of the TcHmiSrv.ResultPair class to void.
  2. Throw a TcHmiSrv.Core.General.TcHmiException with the appropriate information in your TwinCAT HMI server extension project instead of returning an TcHmiSrv.ErrorValue or an instance of the TcHmiSrv.ResultPair class that indicates an error.
  3. If you don't return an TcHmiSrv.ErrorValue or an instance of the TcHmiSrv.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 TcHmiSrv.Management.IExtension interface or TcHmiSrv.Management.ExtensionWithPath abstract base class from the main type of your TwinCAT HMI server extension if it inherits from them.
  2. Implement TcHmiSrv.Core.Tools.Management.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 TcHmiSrv.Core.Listeners.ConfigListener.
    Use the TcHmiSrv.Core.Tools.Settings.ConfigListenerSettings class from the TcHmiSrvExtNet.Tools.Settings.dll to create a TcHmiSrv.Core.Value that represents the settings for the TcHmiSrv.Core.Listeners.ConfigListener class and pass them to the ITcHmiSrvExtHost.RegisterListener(Context, IListener, Value) method.
  5. An instance of the TcHmiSrv.Core.ITcHmiSrvExtHost class is provided by the TcHmiApplication.Host property which replaces the first parameter of the previous Init(ITcHmiSrvExtHost, Context) method.
  6. An instance of the TcHmiSrv.Core.Context class is provided by the TcHmiApplication.Context 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 TcHmiSrv.Core.Context because the TcHmiApplication.Context property already returns a deep copy of it.
  7. The path of your TwinCAT HMI server extension is provided by the TcHmiApplication.Path 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 TcHmiSrv.Core.General.TcHmiLogger class has now been added.
Follow these steps to replace the custom Log class in your TwinCAT HMI server extension project with the TcHmiSrv.Core.General.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 TcHmiLogger.Send and TcHmiLogger.Localize methods.
    Note that the order of the parameters when sending a TcHmiSrv.Core.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 TcHmiSrv.Core.CommandGroup and TcHmiSrv.Core.Value classes have changed to implement the System.Collections.Generic.IList.T. and / or System.Collections.Generic.IDictionary.TKey, 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 TcHmiSrv.CommandVectorIterator, TcHmiSrv.ValueVectorIterator and TcHmiSrv.ValueIterator classes were removed because they were considered unsafe when the underlying collection was modified.
To access TcHmiSrv.Core.Commands in a TcHmiSrv.Core.CommandGroup and TcHmiSrv.Core.Values in a TcHmiSrv.Core.Value, use the methods and indexers provided by the implementation of the System.Collections.Generic.IList.T. and System.Collections.Generic.IDictionary.TKey, TValue. interfaces instead.

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

The implementation of TcHmiSrvExtNet.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