< PreviousField Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100 , Ed. 1.2.0, 27 Jun 2019 Page 9 of 23 FDI Client Process .NET CLR Surrogate Process «library» UIP Interface Proxy «library» UIP Interface Stub «executable» UIP Figure 2 – .NET surrogate process How to identify the .NET target platform of a UIP The .NET target platform CLR version information for which a certain Assembly is compiled can be extracted by means of .NET Framework library functions (see Figure 3). Figure 3 – Identification of Run-time Version NOTE The Visual Studio 1 2008 and 2010 IDE allow developers to select the .NET Framework target. The selection of a .NET Framework target older than the base for the current Visual Studio IDE automatically creates a configuration file listed as “app.config” within the solution explorer. This file only reflects the current complier setting. The compiler does not read that file. 4.6 UIP Deployment The general UIP installation rules are outlined in FCG TS62769-2. The UIP executable shall not be registered within the Global Assembly Cache. The “strong-name” rule ensures that related Assemblies of different versions of the UIP can coexist during runtime. The FDI Client implementation ensures that UIP deployment works independently from current user credentials. (See the NOTE below.) NOTE Certain operating system managed folders require specific access rights, for example, modifications in folder “Program Files” require “Administrator” rights. The Windows operating system provides several means to allow an application running with restricted user rights, to execute actions with administrator privileges transparent to the user, for example, special restriction handling for identified directories, services with administration rights, executables that are configured to automatically run with administration rights. The alternative is to copy UIP executables into folders writeable for “normal” users. 1 Visual Studio is the trade name of Microsoft Corporation. This information is given for the convenience of users of this part of FCG TS62769 and does not constitute an endorsement by IEC of the trademark holder or any of its products. Compliance does not require use of the trade name. Use of the trade name requires permission of the trade name holder. clrVersion = Assembly.LoadFrom(<Assembly Path>).ImageRuntimeVersion; Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100, Ed. 1.2.0, 27 Jun 2019 Page 10 of 23 4.7 UIP Life-cycle General The UIP state machine, outlined in FCG TS62769-2, is composed of the Loaded, Created, Operational, Deactivated and Disposed states. The mechanisms affecting state changes are described in 4.7. After the FDI Client has stored the UIP executable on the FDI Client the FDI Client loads the UIP Assemblies dynamically into the memory and executes the related logic by calling the corresponding FDI specified interface functions. Subclause 4.7 describes rules about how the FDI Client shall activate and deactivate the UIP. UIP Assembly activation steps 4.7.2.1 Load The FDI Client shall load the UIP executables by using the LoadFrom mechanism. The .NET framework provides System.Reflection.Assembly.LoadFrom for this purpose: The LoadFrom mechanism behaves as follows. • LoadFrom loads the Assembly addressed with the file path and also the referenced Assemblies located within same directory. The argument string assemblyFile shall contain the file name of the UIP executable. The file name of the UIP executable represents the StartElementName described in FCG TS62769-4. • If an Assembly is loaded with LoadFrom, and later an Assembly in the “load context” attempts to load the same Assembly by display name, then this load attempt fails. • If an Assembly with the same identity is already loaded (for example, by another UIP), then LoadFrom returns the Assembly that has been loaded before, even if a different file path was specified. Even a different file name does not matter. Only the identity of the Assembly is relevant. • If an Assembly is loaded with LoadFrom, and the probing path includes an Assembly with the same identity (for example, in the Global Assembly Cache or an application directory), then this Assembly is loaded, even if a different file path was specified. • LoadFrom requires the permissions FileIOPermissionAccess.Read and FileIOPermissionAccess.PathDiscovery , or WebPermission , on the specified path. • LoadFrom loads the assembly into the default Application Domain. • If a native Assembly image (generated by ngen.exe) exists for the specified file path, then it is not used. The Assembly cannot be loaded as domain neutral, i.e., the Assembly cannot be shared between Application Domains. This behavior enforces deployment rules as follows. • Rules regarding Assembly dependencies (see 4.7.2.4.2). The FDI Client shall only use LoadFrom . The use of other .NET Assembly loading/object creation means is not allowed. • Rules regarding shared Assemblies (see 4.7.2.4.3). • A pre-compiled processor-specific machine code cannot be used. • The security aspects regarding loading and execution of Assemblies are described in 4.9. 4.7.2.2 Create Creating an instance of the UIP Assembly works using the .net library functions System.Reflection.Assembly.GetTypes and System.Activator.CreateInstance . The FDI type Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100 , Ed. 1.2.0, 27 Jun 2019 Page 11 of 23 library declares a “custom attribute” named UIPActivationClass . This attribute shall only be added to the object implementing the interface IDtmUiFunction that actually implements the UIP start-up function. The attribute UIPActivationClass shall be used once only. The FDI Client can now use System.Reflection services to clearly determine the UIP implemented activation procedure. NOTE 1: Function System.Reflection.Assembly.GetTypes can be used to query the interface IDtmUiFunction. NOTE 2: Function System.Attribute.GetCustomAttributes can be used for reading the additional custom attributes. NOTE 3: The result of function invocation System.Activator.CreateInstance is an object of type IDtmUiFunction. A data type cast is needed. 4.7.2.3 Activate Invocation of function IDtmUiFunction.Init finally activates the UIP for the user. 4.7.2.4 External libraries 4.7.2.4.1 General UIP Assemblies can depend on external libraries (3 rd party libraries) and other Assemblies, for example, specific user control libraries. FDI Clients do not perform installation of UIPs, rather they dynamically load and execute the UIP. To support this usage, as well as the requirement to prevent possible problems of conflicting Assemblies, rules are specified for external libraries. External libraries shall: • be contained within the FDI Package; • not require Microsoft Installer (MSI) installation; • not require entries in the Windows Registry or the Global Assembly Cache; • adhere to the access restrictions described in 4.9.2; • be compatible with the platforms described in FCG TS62769-6. 4.7.2.4.2 Loading of external libraries The FDI Client loads the UIP Assembly, containing the UIP main class implementing interface IDtmUiFunction, by invocation of the .NET framework function LoadFrom . Referenced Assemblies that are stored in the same directory are automatically loaded together with this .NET Assembly. Referenced Assemblies that are stored in other locations (for example, in a sub-directory) have to be loaded explicitly by the UIP itself. The UIP shall load such Assemblies also by invocation of the .NET framework function LoadFrom . Loading Assemblies with other .NET framework methods is not allowed. Usage of external libraries shall not break the self-containment requirement for FDI Packages; all external libraries shall be included in the FDI UIP Package 4.7.2.4.3 Loading of shared external libraries An external library is a shared external library if a related .NET Assembly identity can be used from different UIP executables. The identity of a .NET Assembly matters. Installation path and Assembly filename are not relevant. Usage of shared libraries shall not break the self-containment requirement for FDI Packages. Each of the delivered FDI Packages shall be shipped with all required UIP related libraries. The sharing mechanism comes from the .NET framework implemented optimization mechanism. Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100, Ed. 1.2.0, 27 Jun 2019 Page 12 of 23 If a shared Assembly is used, then the following rules apply. • Any incompatible change to the shared Assembly shall lead to a new identity, for example, different version number. • Shared Assemblies shall not presume to be loaded from a specific installation path, for example, rely on the fact that some files are stored in the same directory or in a sub-directory. • Static variables in shared Assemblies are also shared if the Assembly is loaded into the same Application Domain. Thus static variables shall not have side effects in such scenarios. External shared libraries shall not declare static variables. • Because of the self-containment rule defined for the FDI Package, shared Assemblies shall be deployed with all FDI Packages using a shared Assembly. 4.7.2.5 UIP Constructor invocation Constructor and destructor implementation shall not throw exceptions. The constructor logic shall be limited to instantiate the object in terms of the internal data structure. The destructor logic shall be limited to destroy the object in terms of releasing memory resources. The constructor and the destructor shall not: • Invoke any call-back to the FDI Client. • Invoke any user interaction. UIP Assembly deactivation steps 4.7.3.1 Deactivate For UIP deactivation the FDI Client shall call the interface IDtmUiFunction.BeginClose and IDtmUiFunction.EndClose . On successful execution the UIP shall release all resources and the FDI Client shall delete all references to the UIP instance. The .NET garbage collector finally disposes the UIP runtime object. 4.7.3.2 Dispose A .NET Assembly that is loaded into a process respectively into the related ApplicationDomain is never unloaded, except if the ApplicationDomain itself is destroyed. That means if the FDI Client loads a UIP Assembly into the default ApplicationDomain , then these Assemblies and all dependent Assemblies are never unloaded unless the application is closed. The UIP Assemblies shall be developed with this .NET framework behavior in mind. To reduce the memory consumption the following rules apply. • Minimize the use of static variables, because these increase the memory consumption of the Assembly. • Move UIP functionality that is not always (or rarely) needed to separate Assemblies. These Assemblies are then only automatically or manually loaded when the corresponding code is executed. • Use shared Assemblies whenever possible. • The FDI Client can execute .NET Assemblies in a separate Application Domain in order to have the ability to unload them. Backward compatibility For UIPs built for an older FDI Technology Version the UIP host shall have a binding redirect in place to execute the UIP using the newer FDI Type Library. <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentAssembly> <assemblyIdentity name="Fdi" publicKeyToken="a591af567772af2f" /> Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100 , Ed. 1.2.0, 27 Jun 2019 Page 13 of 23 <bindingRedirect oldVersion="0.0.0.0-1.1.65535.65535" newVersion="1.2.0.0" /> </dependentAssembly> </assemblyBinding> Figure 4 – Example snippet of a UIP host config file for the binding redirect 4.8 Interaction between an FDI Client and a UIP Handling of standard UI elements UIPs shall delegate the presentation and handling of standard UI elements to the FDI Client. The standard UI elements are • UI Actions with standardized semantics (Apply/Close/Online Help), and • specific UI Actions (UI actions, which are specific to one UIP, e.g. Reset, Reconnect). To ensure a consistent user interface interaction across UIPs from different vendors, a UIP may delegate presentation and handling of additional UIP specific actions to the FDI Client. Nonetheless UIPs are allowed to implement non-standard UI actions within their own UI area. The set of standard UI actions and their respective semantics is fixed. However, the availability of these actions may change at any time depending on the internal state of the UIP. The set of additional UIP specific actions and their individual availability is not fixed. A UIP may add, remove, rename, enable or disable the UIP specific actions at any time depending on its requirements. The UIP has to inform the FDI Client whenever the availability of its standard actions or UIP specific actions changes (see events IStandardActions.StandardActionItemSetChanged and IApplicationSpecificActions . ApplicationSpecificActionItemSetChanged). An FDI Client may use dedicated UI elements, e.g. button controls, to provide direct access to the standard actions, as well as indirectly invoke them in the context of user interaction with other FDI Client UI elements. FDI Client shall always show all custom actions exposed by a UIP with dedicated UI elements. Non-blocking service execution 4.8.2.1 FDI Client internal functions The implementation of function BeginOperationName shall copy the content of Argument asyncState into member AsyncState of the returned IAsyncResult object. The productive (time consuming) part of the function named OperationName shall be performed in a different thread. The synchronization with the calling thread is handled via the AsyncWaitHandle object (class WaitHandle ), which is also a member of the IAsyncResult object. When processing of the productive part of the function named OperationName has finished the IAsyncResult objects attribute IsCompleted shall be set to True . If the AsyncCallBack argument value is valid (not equal NULL) the FDI Client notifies the UIP using the callback. The implementation of CancelOperationName uses the argument IAsyncResult to identify the service that has been started with BeginOperationName. If BeginOperationName started an OPCUA service, the FDI Client shall call the OPCUA defined Cancel service. 4.8.2.2 UIP internal functions The management of multiple asynchronous services in parallel shall be managed using the AsyncState object. Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100, Ed. 1.2.0, 27 Jun 2019 Page 14 of 23 The IAsyncResult object returned by BeginOperationName contains the WaitHandle object. The UIP shall perform its own thread synchronization using the WaitHandle object. 4.8.2.3 Non-blocking service execution sequence The following shows the interaction sequence between the FDI Client and the UIP. The thread management mechanisms implemented inside the FDI Client are not shown. The Interaction between an FDI Client and an FDI Server is based on Request/Response pattern. The FDI Client service request matches with the BeginOperationName. The AsyncCallback invocation matches with receiving the Client service response. EndOperationName conveys the response contained results. Implementation of the non-blocking service execution does not require any thread management inside the FDI Client. Figure 5 shows an example of an IAsyncPattern based Asynchronous service execution. UIP2FDIClient2 BeginRead() ReadAsyncResult Service Read processing ReadAsyncCallback EndRead() ReadResult Figure 5 – IAsyncPattern based asynchronous service execution example Blocking service execution The FDI Client provided interfaces allow performing synchronous Information Model access by using the functionality described in 4.8.1 in a way shown in Figure 6. Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100 , Ed. 1.2.0, 27 Jun 2019 Page 15 of 23 UIP1FDIClient1 ReadAsyncResult BeginRead EndRead ReadResult Service Read processing Figure 6 – Blocking service execution example using IAsyncResult based pattern ReadAsyncResult is the object implementing the interface IAsyncResult . Cancel service execution Some services specified for the interface IDeviceModel (see Table 2) support canceling a started service by means of the function CancelOperationName. The following Figure 7 will illustrate the processing sequence based on the Read service example. UIP2FDIClient2 BeginRead ReadAsyncResult CancelRead Service Read processing Cancel CancelRead ReadAsyncCallback EndRead ReadResult Figure 7 – Cancel service processing sequence example Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100, Ed. 1.2.0, 27 Jun 2019 Page 16 of 23 The invocation of CancelRead triggers the FDI Client internal functions needed to cancel the active read operation. The FDI Client may not be able to cancel the operation immediately, but it should do so as soon as possible. Once the operation has been cancelled, the FDI Client notifies the UIP through the ReadAsyncCallback . The UIP shall then call the EndRead function. NOTE A general challenge implementing this pattern is to handle race conditions properly on both sides (UIP2 and FDIClient2). If the FDI Client has forwarded the service execution via an OPC UA service, the actual service execution will run inside the FDI Server. Depending on how the UIP is hosted there may be three independently working processes. Therefore the cancel request (sent by the UIP) may appear right after the FDI Server has already finished the service request. The related response sent by the FDI Server may have arrived at the FDI Client (or not). The FDI Client may invoke the ReadAsyncCallBack while the UIP invokes the CancelRead. ReadAsyncResult is the object implementing the interface IAsyncResult . Threading 4.8.5.1 Implementation rules The UIP shall be able to receive calls in any thread. The UIP shall not block the calls coming from the FDI Client. The UIP shall not use the FDI Client thread to signal back the callback to the FDI Client itself. This is to prevent deadlocks and endless loops. The UIP shall not run synchronous operations as described in 4.8.3 in the user interface thread: The user interface thread of a process shall be dedicated to receive user inputs and perform drawing tasks only. The UIP and FDI Client shall not block the user interface thread. The user interface shall always stay responsive. The user interface thread is shared between the different FDI user interface related objects for user input and drawing operations. If one object blocks this thread in order to perform some processing, this would affect the responsiveness of other user interfaces. The UIP and FDI Client shall not block a BeginOperationName method call: A BeginOperationName method shall only start an asynchronous operation. The caller shall not be blocked. Timeout The interfaces referred in Clause 5 enable asynchronous service execution. The time for the execution of such services depends on performance constraints related to: bus communication, FDI Client/FDI Server performance. The rules listed below target the system interoperability regarding the prevention of “Race Conditions”. The general rule is that the component is allowed to manage timeout handling only for those processes that are completely under the control of that component. The following list shows which elements of the entire system are allowed to implement the timeout detection function. • UIP: The UIP shall not implement timeout detection. • Business Logic: The Business Logic shall not implement timeout detection (FDI Package). • FDI Client: The FDI Client shall implement timeout detection. In case of OPC UA, the related support is built into the OPC UA communication stacks. Timeout detected during operations performed on behalf of the UIP shall be forwarded as negative function result codes. • FDI Server: The FDI Server shall implement timeout detection. In case of OPC UA, the related support is built into the OPC UA communication stacks. • Communication Server: The Communication Server implements timeout detection for the OPC UA connection according to the OPC UA Specification. Related support is built into the OPC UA communication stacks. Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100 , Ed. 1.2.0, 27 Jun 2019 Page 17 of 23 Additionally the Communication Server implements timeout detection limited to the network directly connected to the physical port connected to the Communication Server. Exception handling An important specification goal is to make a clear distinction between software quality problems and anticipated processing states. Therefore, the specification defines two general Exception categories: a) Exceptions that indicate software states or events that have not been anticipated during the software development are considered as software quality issues (Run-time error). b) Exceptions indicating anticipated software operation failures. Examples of software quality issues indicated by exceptions are: • function argument type mismatch; • function argument value range mismatch; • division by zero; • NULL Pointer reference. Examples of anticipated error handling are: • communication problem handling; • general IO data processing; • user input errors. UIPFDI ClientFDI Server .NET Interface OPC UA a b cd e Figure 8 – Exception source According to the FDI Architecture exceptions can occur in different steps of the service processing, see Figure 8: a) passing the request from the UIP to the FDI Client: b) request forwarding inside the FDI Client; c) processing the response from the FDI Server; d) forwarding the response to the UIP; e) response processing inside the UIP. Service processing problems detected inside the FDI Server and beyond are handled through OPC UA defined service results. Regarding the implementation of the IAsyncResult pattern the following rules apply. – Any failure occurring with step a) shall be reported by an exception thrown by the BeginOperationName. – Any failure occurring during steps b) to e) shall be handled by the corresponding component. The execution of the EndOperationName shall then report the failure via an exception. Field Device Integration (FDI) –Part 6-100: Technology Mapping – .NET RELEASED FCG TS62769-6-100, Ed. 1.2.0, 27 Jun 2019 Page 18 of 23 Type safe interfaces The Information Model hosts device variables of different types. The values of such variables are transferred using the class DataValue (FDI Interfaces and Data Types.CHM). The Device Access Services support writing or reading multiple variables within one service. The data type chosen for data transport is DataValue implementing the type safe transport because of the DataValue property Datatype describing the value data type by means of Datatype enumeration. Because the DataValue property Value get/set functions use data type Object to convey the actual value the data receiver (UIP) shall verify the data type before data processing. Globalization and localization UIP localization support can be implemented through resource files (.res(x)) or satellite Assemblies. The FDI Client shall set the locale and country information that shall be used by the UIP by means of the arguments currentRegion and currentCulture that are submitted with the invocation of method Fdi.Dtm.Ui.IDtmUiFunction.Init . The UIP shall not derive locale information via the Thread.CurrentUICulture . The data type for currentRegion is RegionInfo defined in the .NET namespace System.Globalization . The data type for currentCulture is CultureInfo defined in the .NET namespace System.Globalization . WPF Control handling If a UIP implementation is based on WPF UserControl the UIP inherits the interface from the class UserControl , which means there will be more methods attributes and events available for the FDI Client that are not covered by the FDI specification. Vice versa a UIP implements the accessibility function. The related rules on the one hand touch the quality of the UIP product and on the other hand the interoperability. Win Form handling If a UIP implementation is based on Windows Forms the UIP inherits from the class UserControl, which means there will be more methods attributes and events available for the FDI Client that are not covered by the FDI specification. Vice versa a UIP implements the accessibility function. The related rules on the one hand touch the quality of the UIP product and on the other hand the interoperability. The FDI Client shall make thread-safe calls to the Windows.Forms controls. 4.9 Security General The goal of security is to protect a system against threats compromising the system stability, integrity and sensitive data. System wide security begins with the design process, which is out of the standardization scope. From the system perspective security is about controlling access to resources, such as application components, data, and hardware. The .NET framework provides support for constraining access to resources. The system security is based on control over access permissions. A different approach is based on certification and authentication. Since any FDI Package needs compliance testing and certification the presumption is that such certified FDI Packages don’t pose any threats to a system. This means a UIP could be executed with full trusted permissions. While an over-constrained system could lead into functional problems an un-constrained permissions can be seen as security threat. Thus Subclause 4.9 represents a compromise between both ways. Next >