What’s New in QuickOPC 5.40

Key changes:

• Support for OPC UA Alarms & Conditions
• NuGet package distribution format
• Targets .NET Framework 4.5.2 or higher
• Event pull mechanism

Targeting

• .NET Framework 4.5.2 or higher is now required (Microsoft support for .NET Framework 4.5 and 4.5.1 ended January 12, 2016).
• The .NET projects you create now need to target .NET Framework 4.5.2 or higher as well.
• If you use Visual Studio 2012 or Visual Studio 2013, you will need to install the targeting pack for .NET Framework 4.5.2 (or higher). The targeting packs for .NET Framework 4.5.2 and .NET Framework 4.6 come preinstalled with Visual Studio 2015.

Installation and Uninstallation

• The code signing certificate used is now “COMODO RSA Code Signing CA” and uses RSA256.
• .NET assemblies (earlier under the Assemblies folder) are now under the Assemblies\net452 folder in the product installation directory.
• The Code Contract assemblies are no longer contained in the installation package. Instead, the installer creates a link (to a ZIP file) in the corresponding folder, allowing the developer to download them when needed.
• Besides the Setup program itself, more binaries in the product are now code-signed. For instance, the executables under the ‘bin’ directory, such as the License Manager, or the OPC Kit Server (opcrtkit), are now code-signed, using the same certificate as the installation program.
• Type libraries for 64-bit development are now installed with the product (when appropriate options are chosen), and are located under Lib\x64.
• Type libraries (.TLB) are now generated “on the fly” on the target computer, during the installation.

Distribution Formats

• QuickOPC is now available in form of NuGet packages on http://www.nuget.org. The OpcLabs.QuickOpc package is common for all environments and project types. The OpcLabs.QuickOpc.Forms package contains components that are specific for Windows Forms (can be partially used from WPF as well). Note that NuGet is primarily a tool for resolving build-time dependencies, and the amount of functionality that you get through QuickOPC NuGet packages is smaller than what the QuickOPC Setup program provides. Specifically, most design-time features are missing.

OPC UA Alarms & Conditions

• QuickOPC now supports OPC Unified Architecture Alarms & Conditions (Specification Part 9). See the Concepts document for an explanation of how this works. The basic elements of this new feature are outlined below.
• Besides the existing UAMonitoringParameters.DataChangeFilter property, the UAMonitoringParameters class now has a new EventFilter property (of UAEventFilter type). The developer can specify either a data change filter, or an event filter, with monitoring parameters.
• Besides the IEasyUAClient.DataChangeNotification event, there is now a new IEasyUAClient.EventNotification event. This event is raised for every event generated by a subscribed OPC monitored item.
• As the UAMonitoringParameters are part of the information that gets passed (directly or indirectly) to any EasyUAClient.SubscribeMonitoredItem or SubscribeMultipleMonitoredItems call, the introduction of the EventFilter property and the EventNotification event (both described above) are, in fact, the only core changes that already in itself allow the Alarms & Conditions support to work. Many other features simply provide better developer experience above this.
• The EasyUAMonitoredItemArguments object now has (besides an existing DataChangeCallback property) a new EventCallback property. This property specifies an optional method to be invoked for each event notification generated by the monitored item.
• The arguments of each event notification (EasyUAEventNotificationEventArgs) have an EventData property (of type UAEventData, described further below), which contains details about the OPC UA event. In addition, common information such as the copy of the input arguments to the subscription, i.e. identification of the endpoint and node (monitored item) which has generated the event, is included. As usual, the Exception property (and several related properties) indicates success (when it is a null reference), or a failure (in which case it contains an exception object describing the error).
• The UAEventData object contains details about an OPC UA event, i.e. the information that the OPC UA server sends with the event notification. Primarily, it has a FieldResults property, which is a dictionary containing results for each of the fields in the select clauses of the event filter. Each field results is a ValueResult object, i.e. it can either contain the actual value, or an error indication. In order to make access to at least some of these results easier (without having to go through indexing an element in the dictionary), the UAEventData object also contains a BaseEvent property (of UABaseEventObject type). The UABaseEventObject class contains properties that directly correspond to information contained in the base event type (from which all UA events are derived), such as SourceName, Time, Message, Severity, etc. In case of an error related to a particular field, the corresponding property will contain its default value (e.g. an empty string for a Message).
• Besides the existing IEasyUAClient.SubscribeMonitoredItem extension method overload that accepts a data change callback (EasyUADataChangeNotificationEventHandler), added a new overload that accepts an event callback (EasyUAEventNotificationEventHandler).
• Added an IEasyUAClient.SubscribeEvent extension method, with several overloads. Similarly to the IEasyUAClient.SubscribeDataChange extension method (for data changes), the SubscribeEvent method provides a simplified way to subscribe to events.
• The UAEventFilter object (used for specifying the event filters) is probably the most complicated part of the OPC UA Alarms & Condition features. It has two main parts: Select clauses (contained in the SelectClauses property, of UAAttributeFieldCollection type), and a Where clause (contained in the WhereClause property, of UAContentFilterElement type). The Select clauses contain a collection of the attribute fields to return with each event in a notification. The Where clause contains the criteria limiting the notifications.
• Each Select clause of the event filter is a UAAttributeField object, which contains an Operand property. You can optionally set its the State property to an object of your choice, and the same object will then be made available to you in the event notification containing the operand. An Operand is of the UASimpleAttributeOperand type, and specifies primarily a TypeId node in the server, and a QualifiedNames collection (of UAQualifiedNameCollection type), which is a so-called simple relative path (inside that type) that leads to the required node. A simple relative path can only contain forward, “any hierarchical” references.
• Conversion methods, and conversion operators exist between the UAQualifiedNameCollection (for simple relative paths) and UABrowsePathElementCollection (for general relative paths). Conversion from UAQualifiedNameCollection to UABrowsePathElementCollection is always possible and has an implicit conversion operator, conversion from UABrowsePathElementCollection to UAQualifiedNameCollection is only possible for simple relative path, and has an explicit conversion operator instead.
• In order to make the specification of the most commonly used Select clauses easier, it is possible to use pre-defined clauses provided in the static UABaseEventObject.Operands class (for example, UABaseEventObject.Operands.Message). The UABaseEventObject.AllFields property can be used to obtain Select clauses for all fields of the UA base event type at once.
• The Where clause of the event filter is represented using the UAContentFilterElement object. This object contains the filter operand to be evaluated (the FilterOperator property, which is a UAFilterOperator enumeration), and the operands used by the selected operator (the FilterOperands property, which is a UAFilterOperandCollection). The UAFilterOperator enumeration contains all operators supported by OPC UA (Equals, IsNull, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual, Like, Not, Between, InList, And, Or, Cast, InView, OfType, RelatedTo, BitwiseAnd, BitwiseOr). The UAFilterOperandCollection is a collection of content filter operands (UAFilterOperand).
• The UAFilterOperand is a base class for four different types of filter operands: UAAttributeOperand (an operand consisting of an attribute of a node in a type, with optional relative path and alias), UAContentFilterElement (essentially, an operator with operands), UALiteralOperand (an operand consisting of a literal value), or UASimpleAttributeOperand (an operand consisting of an attribute of a node in a type, with optional simple relative path, and no alias).
• In order to make the creation of Where clauses appear shorter in the code, a UAContentFilterElementBuilder class is provided. Instances of this builder can be implicitly converted to the content filter element itself (hence you can create just the UAContentFilterElementBuilder objects, and use them at all places where the UAContentFilterElement object is expected). The builder contains an operator and is a collection of operands; you can use the C# collection initializer to specify the operands.
• For further simplification of the coding, the UAFilterElements static class provides an easy way to construct basic filter elements (literal, attribute, or a simple attribute), and elements with various operators. Using the UAFilterElement class is for most cases the recommended way to create the Where clause of the event filter. For example, UAFilterElements.GreaterThanOrEqual creates a Where clause with the ‘>=’ operator. There are methods for each of the OPC UA operators, with various overloads. The UAFilterElements.Attribute, UAFilterElements.Literal and UAFilterElements.SimpleAttribute methods can be used to create other types of filter elements. Moreover, useful overloads exist that assure that you can actually use .NET objects directly as values of operands, and they will be interpreted as literal elements. With use of all these code simplifying features, you can write, for example, the following Where clause:

 UAFilterElements.GreaterThanOrEqual(UABaseEventObject.Operands.Severity, 500).

• In order to make the creation of some event filters appear shorter in the code, a UAEventFilterBuilder class is provided. Instances of this builder can be implicitly converted to the event filter itself (hence you can create just the UAEventFilterBuilder objects, and use them at all places where the UAEventFilter object is expected). The builder contains a Where clause, and is a collection of Select clauses. You can therefore use the C# collection initializer to specify the Select clauses.
• The UAMonitoredItemArguments class now contains a new Boolean AutoConditionRefresh property. When set (this is the default), a UA ConditionRefresh will be automatically performed when needed to keep the condition information up-to-date.
• The component handles special events reserved for condition refresh automatically, and translates them to event notifications with a special form of event arguments. Event notifications that related to condition refresh have their Refresh property set to ‘true’. In addition, a start of condition refresh is indicated by a notification with event arguments that have their RefreshInitiated property set to ‘true’. Correspondingly, an end of condition refresh is indicated by a notification with event arguments that have their RefreshComplete property set to ‘true’.
• Added pre-made browse parameters (usable with IEasyUAClient.BrowseNodes method) for browsing the elements related to Alarms & Conditions: There are now new UABrowseParameters.EventSources, and Notifiers static properties. Similarly, added extension methods IEasyUAClient.BrowseEventSources and BrowseNotifiers, which you can use to perform Alarms & Conditions browsing easily.
• Added UATimeZoneData class. This class contains data returned in the UABaseEventObject.LocalTime property (defines the local time that may or may not take daylight saving time into account).
• Added extension methods on the IEasyUAClient that call standard UA methods for Alarms & Conditions: Acknowledge, AddComment, Confirm, Disable, Enable, OneShotShelve, Respond, TimedShelve, and Unshelve. These extension methods allow you to call the UA methods easily, without having to look up their Node Ids, and without having to assembly the arguments.
• Added UAEventNotifiers static class. This class contains flags that can be set for the EventNotifier attribute. You can use the symbolic values from this class to interpret the value of the attribute.

Event Pull Mechanism

• Event pull mechanism is an alternative to the traditional delivery mechanism of notifications through event handlers. Setting up event handlers, and properly handling events, is difficult or impossible in some (especially COM-based) tools (e.g. Python) and in some environments (e.g. applications running under Web server). In COM, unless taken care of already by the tool, the developer must also assure that (in an STA model) Windows messages are being pumped by the application. Event pull mechanism replaces the event handlers by methods that allow the developer to obtain a next available notification from an internally provided queue. Events can then be handled by a loop that calls the “pull” method and processes the notifications. In order to maintain reasonable performance, a so-called long poll approach is used: The method only returns after a notification becomes available, or a specified timeout elapses. Note that the event pull concept is strictly confined to how the QuickOPC exchanges notifications with the enclosing application, and is not related to how QuickOPC communicates with OPC servers.
• For each event XXXX, by convention, two methods for event pull mechanism are provided: A PullXXXX method, which allows to retrieve a single notification, and a PullMultipleXXXX method, which allows to retrieve multiple notifications, if they are available. Although currently is no significant performance difference between the two methods, it is recommended that your code uses the PullMultipleXXXX methods, because it may bring performance benefits in the future.
• The following table shows the traditional events, and their corresponding methods for event pull:

Type	Event	Pull method	PullMultiple method
EasyDAClient	ItemChanged	PullItemChanged	PullMultipleItemChanges
EasyAEClient	Notification	PullNotification	PullMultipleNotifications
EasyUAClient	DataChangeNotification	PullDataChangeNotification	PullMultipleDataChangeNotifications
	EventNotification	PullEventNotification	PullMultipleEventNotifications
	ServerConditionChanged	PullServerConditionChanged	PullMultipleServerConditionChanges

• In order to use the event pull mechanism, your code needs to set up a queue with a fixed capacity upfront. This is done by setting a corresponding property in the EasyXXClient object. By convention, for an event named XXXX, the property name is PullXXXXQueueCapacity. For example, set the EasyUAClient.PullDataChangeNotificationQueueCapacity property to allocate a queue for OPC UA data change notifications.

Technology

• Internal: The product is now developed with Visual Studio 2015 (managed parts, native parts and mixed mode assemblies). For widest compatibility, examples are still developed with Visual Studio 2012.
• Internal: Reference documentation is now built with Sandcastle Help File Builder 2015.

Components Core Improvements

• Added EasyUAClient.ServerConditionChanged event. This event is raised for a change in the condition of an OPC server. Specifically, you receive a notification whenever the connection to the server is established, or whenever the connection is terminated. Whether the server is currently connected is indicated by the Connected property in the event arguments (of EasyUAServerConditionChangedEventArgs type). Whenever there is an error (exception) associated with the server condition, it is also available in the event arguments. Additional properties of the event arguments distinguish the change further. For example, the ConnectionStatus property contains an enumerated value with members Disconnected, Connecting, Connected, and Disconnecting. The RetrialDelay property (valid in the Disconnected state) indicates the time (in milliseconds) to the next reconnection attempt.
• Added UAEndpointSelectionPolicy.SecurityPolicyUriString property. When not an empty string (an empty string is the default), it specifies the required security policy URI string of the endpoint. This allows the developer to select the precise security policy, when so required (as opposed to the default behavior which selects the security from multiple possible choices, based on properties that describe the intended capabilities of the endpoint). The new static UASecurityPolicyUriStrings class contains strings that can be used to specify the security policy URI.
• Added implicit conversions from System.Double and UADataChangeTrigger to UADataChangeFilter. This allows the developer to simply use the absolute deadband, or the trigger selection, in place of any data change filter. Consequently, we have generalized certain IEasyUAClient.SubscribeDataChange extension method overloads to accept UADataChangeFilter instead of System.Double for absolute deadband value (which still works, now due to the implicit conversion available).
• Added a new exception type, UACallServiceException, derived from UAServiceException. This exception type is used with the OPC UA method calls (IEasyUAClient.CallMultipleMethods, IEasyUAClientExtension.CallMethod), and contains an additional InputArgumentExceptions property. This property contains an array of exceptions that describe errors related to individual input arguments of the OPC UA method. This allows the application code to examine the status of individual input arguments.
• Improved conversions performed on input arguments to OPC UA method calls (IEasyUAClient.CallMultipleMethods, IEasyUAClientExtension.CallMethod), so that .NET types are better mapped to OPC UA data types.
• Much wider support of copy constructors among the types. Copy constructors are now available on all core objects where it makes sense.
• Much wider ICloneable support among the types. ICloneable is now available on all core objects where it makes sense. Note, however, that we generally use an explicit interface implementation of ICloneable; that is, in order to access the Clone method, you need to explicitly cast the object to ICloneable first.
• Much wider serialization support among the types. Binary serialization, XML serialization, XAML serialization and data contract serialization is now available on all core objects where it makes sense and is feasible.
• Default format of displaying the timestamps in DAVtq, UAAttributeData classes has been changed to sortable, culture-independent format, with milliseconds included.
• Added a SetValue method to COM interfaces _ValueResult, _DAVtq, _DAItemValueArguments, _UAAttributeData, _UALiteralOperand, _UAWriteValueArguments. This allows the (object-typed) value be set from Visual Basic 6.0 with early binding.
• Improved error codes and messages in OPC UA parsing.

Components Core Changes

• Changed the default trigger in UADataChangeFilter (DefaultTrigger) from UADataChangeTrigger.Status to UADataChangeTrigger.StatusValue. Consistently with the above change, the default trigger used by overloads of EasyUAClient.SubscribeDataChange is UADataChangeTrigger.StatusValue (in order to maintain backward compatibility, the default used with the obsoleted overloads of EasyUAClient. SubscribeMonitoredItem is still UADataChangeTrigger.StatusValueTimestamp).
• Removed the (already obsoleted) Handle property from the EasyAENotificationEventArgs, EasyDAItemChangedEventArgs, EasyUAMonitoredItemChangedEventArgs (and therefore also EasyUADataChangeNotificationEventArgs, EasyUAEventNotificationArgs) classes.
• The OPC UA components are now based on OPC Foundation UA .NET Stack 1.02.336.0.

Components Core Refactorings

• In order to allow enhancements for OPC UA Alarms & Conditions, some types and members have been renamed. The naming convention now uses the term “MonitoredItem” wherever the type or member applies to both Data Access and Alarms & Conditions, whereas the names that use the term “DataChange” apply to Data Access only.

The changes in types are described by the following table: Old type name New type name EasyUAMonitoredItemArguments<> EasyUADataChangeArguments<> EasyUAMonitoredItemChangedEventArgs EasyUADataChangeNotificationEventArgs EasyUAMonitoredItemChangedEventArgs<> EasyUADataChangeNotificationEventArgs<> EasyUAMonitoredItemChangedEventHandler<> EasyUADataChangeNotificationEventHandler<> UAMonitoredItemChangedObservable< > UADataChangeNotificationObservable<> UAMonitoredItemChangedPayload<> UADataChangeNotificationPayload<> UAMonitoredItemSubscription<> UADataChangeNotificationSubscription<>

Changes in member names are as follows: o The IEasyUAClient.MonitoredItemChanged event has been renamed to DataChangeNotification. o Some overloads of the extension method IEasyUAClient.SubscribeMonitoredItem have been renamed to SubscribeDataChange. o Some overloads of the extension methods IEasyUAClient.ChangeMonitoredItemSubscription and IEasyUAClient.ChangeMultipleMonitoredItemSubscriptions have been renamed to ChangeDataChangeSubscription and ChangeMultipleDataChangesSubscriptions, respectively. o The EasyUAMonitoredItemArguments.Callback property has been renamed to DataChangeCallback.

• In .NET, backward compatibility is provided for the most commonly used renamed types and members. This means that if your existing code uses them, you will get a compiler warning recommending you to use a different type or member, but the code will still compile. For the remaining types and members, you need to perform a manual renaming in your code, using the correspondences outlined above. We plan to remove the obsoleted types and members from the product with a version that will come approx. 1 year after the release of this version.
• For COM development, where applicable, the corresponding types and members have been renamed in an identical manner. Backward compatible types and members are not provided for COM development.
• Renamed some sub-properties by adding “Parameters” to their name (reverting a change made in an earlier version). For example, EasyUASharedParameters.Engine becomes EasyUASharedParameters.EngineParameters, and EasyDASharedParameters.Client becomes EasyDASharedParameters.ClientParameters.

Packaging

• For .NET development, all types from the OpcLabs.BaseLibExtensions assembly have been moved into the OpcLabs.BaseLib assembly, and the OpcLabs.BaseLibExtensions assembly has been consequently removed. Remove references to OpcLabs.BaseLibExtensions assembly from your projects when upgrading to QuickOPC 5.40. Namespaces have not been affected by this change.
• For .NET development, all types from the OpcLabs.EasyOpcUAInternal assembly have been moved into the OpcLabs. EasyOpcUA assembly, and the OpcLabs. EasyOpcUAInternal assembly has been consequently removed. Remove references to OpcLabs. EasyOpcUAInternal assembly from your projects when upgrading to QuickOPC 5.40. Namespaces have not been affected by this change.
• Similarly, for COM development, all types from the BaseLibExtensions type library (.TLB) have been moved into the BaseLib type library, and the BaseLibExtensions type library has been consequently removed. All types from the EasyOpcUAInternal type library (.TLB) have been moved into the EasyOpcUA type library, and the EasyOpcUAInternal type library has been consequently removed.
• All types from the OpcLabs.EasyOpcClassicExtensions assembly have been moved into the OpcLabs. EasyOpcClassic assembly, and the OpcLabs. EasyOpcClassicExtensions assembly has been consequently removed. Remove references to OpcLabs. EasyOpcClassicExtensions assembly from your projects when upgrading to QuickOPC 5.40. Namespaces have not been affected by this change.
• All types from the OpcLabs.EasyOpcUAExtensions assembly have been moved into the OpcLabs. EasyOpcUA assembly, and the OpcLabs. EasyOpcUAExtensions assembly has been consequently removed. Remove references to OpcLabs. EasyOpcUAExtensions assembly from your projects when upgrading to QuickOPC 5.40. Namespaces have not been affected by this change.
• Removed following assemblies: BoxedAppSdk.Managed, Interop.NetFwTypeLib, Opc.Ua.Client, Opc.Ua.Configuration, Opc.Ua.Core.dll OpcComRcw, OpcLabs.BoxUACertificateGenerator, OpcLabs.BoxOpcCorePS, OpcLabs.BoxVC120Redist, OpcLabs.EasyOpc, OpcLabs.EasyOpcClassicNative, OpcLabs.EasyOpcClassicNetApi, OpcNetApi, OpcNetApi.Com, OpcNetApi.Xml. Your projects did not need to reference these assemblies, because they contained only internal types, therefore this change only affects the application deployment. When upgrading your projects to QuickOPC 5.40, simply remove the corresponding DLLs from your installation.

Documentation and Help

• The Help Viewer contents is now signed using a code signing certificate, providing better installation experience (friendlier security prompts).
• The less frequently used conceptual documents are no longer part of the installation package, but the files for download are instead located on the Web. The icons (Start menu items) that invoke them are still installed with the product, and work as before. The documents that remain installed locally are: Concepts, Examples, and Getting Started.

Examples

• Source code to the OpcDAQualityDecoder application (from Bonus Material) is now available in the C# Examples solution (under the WPF folder).
• Added reference examples for UA Alarms & Conditions.
• Added examples for event pull mechanism.
• Added an example (APISimplifier.wsc, ReadUsingSimplifier.vbs) in VBScript/WSH that shows how to create and use a COM component that provides domain-specific API to QuickOPC.
• VB.NET projects with 3-rd party products (“integration” examples) have been separated into their own solutions.

Removed Parts

• The EasuOpcUAConsole bonus application has been removed from the product.
• A separately downloadable OPC UA SDK 1.01 COM Interop Components Redist package (available through a link) has been removed from the product.

Other

• The optionally installed test tools for OPC “Classic” and OPC Unified Architecture have been merged into a single application.