What's new in QuickOPC 2023.1

See also: Versions; Previous version: What's new in QuickOPC 2022.2

Internal version number: 5.71

Key changes:

• UA Administration & PKI

Targeting

• .NET runtimes: Added support for .NET 7.
• .NET runtimes: Removed support for .NET Core 3.1.

Licensing

• Textual license keys with damaged newline markers are now silently fixed up internally and can be recognized as valid. The newline markers in the license keys are sometimes damaged by email systems, source control systems and other tools. This improvement applies to the GUI-based LicenseManager, to the LMConsole tool, and to the license keys registered from the code with the managed resource license store.
• When registering the license key embedded in a managed resource (.NET - methods LicensingManagement.RegisterManagedResource and RegisterManagedResourceWithExistenceCheck), it is now possible to use a match pattern instead of the precise resource name. This makes it easier to prevent common errors associated with either mistyping the key file name, or incorrectly determining the namespace of the managed resource. The recommended match pattern is "*.Key-*.*".
• In Windows Forms and certain other Windows desktop applications, when a trial license is activated, the component displays a corresponding warning notification in the Windows system tray. Clicking on the notification shows further details.
• In Windows Forms and certain other Windows desktop applications, when the license is not valid, the component displays a corresponding error notification in the Windows system tray. Clicking on the notification shows further details about the issue.

Component Improvements

OPC UA Client-Server

• When the effective endpoint selection policy only allows connection with no message security, the client instance certificate is not used (and not required) when creating the OPC UA session.

Specialized Client Objects

• Added GetCertificateGroupElement method to the IEasyUACertificateManagement interface. The method returns the certificate group element for a given certificate group Id.
• Added BrowseCertificateTypeTree method to the IEasyUACertificateManagement interface. The method browses the certificate types available in the Certificate Manager.
• Added static UACertificateGroupIds class. The class that declares constants for certificate group Ids.
• Added static UACertificateTypeIds class. The class that declares constants for certificate type Ids.

OPC UA Administration and PKI

• It is now possible to protect the private key of the client instance certificate with a password. The password can be set using the UAClientServerApplicationParameters.InstanceCertificatePrivateKeyPassword property. In addition, the relevant operations on the IEasyUAClientServerApplication interface now also have an additional argument for the private key password.
• Added operations on the IEasyUAClientServerApplication interface for protecting or unprotecting private keys of existing certificates. The methods and extension methods names are ProtectOrUnprotectOwnCertificate, ProtectOwnCertificate, and UnprotectOwnCertificate.
• Created a new object, CertificateGenerationParameters, with settings that influence how the certificates are generated. You can set the maximum expiration date of the generated certificate, its minimum key size, and/or the validity period in months. For creation of application instance certificates, these parameters can be changed in the new InstanceCertificateGenerationParameters property of the UAClientServerApplicationParameters object.
• The auto-generation of client instance certificate is now skipped when the effective endpoint selection policy only allows connections with no message security.
• The IEasyUAClientServerApplication.RemoveOwnCertificate method now takes an additional boolean argument, specifying whether the certificate must be present in the certificate store. An extension method without the additional argument is also available.
• Changed return type of the IEasyUAClientServerApplication.RemoveOwnCertificate method from void to Boolean. The return value indicates whether the certificate has been removed.
• When the application instance certificate is removed, its copies in the trusted peers certificate store, if any, are now removed as well.
• It is now possible to specify the default format of the application URI (which is used unless the application URI string is specified in the application manifest). The format can be set in the UAClientServerApplicationParameters.ApplicationUriTemplateString property. See OPC UA Application URI Derivation for the template syntax, and more details about how the application URI is determined.
• In common cases, shortened the auto-generated application URI string by leaving out tokens that are at their default ("0.0.0.0" for Version or FileVersion, "neutral" for Culture, and "Language Neutral" for Language).
• Added CreateOwnCertificate method to the IEasyUAClientServerApplication interface. The method creates the instance certificate the application is currently configured to use. It is possible to specify whether the instance certificate must not be present prior to the operation, or whether the operation will be able to replace it.
• Added ValidateOwnCertificate method to the IEasyUAClientServerApplication interface. The method validates the instance certificate the application is currently configured to use.
• Added AutoGenerateInstanceCertificate property to the UAClientServerApplicationParameters object (defaults to true). The property determines whether the application will automatically generate its instance certificate when not present.
• Added ValidateOwnInstanceCertificate property to the UAClientServerApplicationParameters object. The property determines whether the application will validate its own instance certificate before a connection with the other party is established.
• Methods on the IEasyUAClientServerApplication interface that work with the application instance certificate now have a new argument, a string certificate sub-id. It allows the OPC UA application to work with multiple own instance certificates (needed in advanced scenarios). The sub-id of the default instance certificate is an empty string. Extensions methods are provided with the certificate sub-id argument omitted.
• Added CertificateSubId property to the UAEndpointDescriptor object. This property allows you to select own application instance certificate which will be used when establishing the connection, in case the application uses multiple own instance certificates (needed in advanced scenarios).
• Added ListCertificateSubIds method to the IEasyUAClientServerApplication interface. The method finds certificate sub-ids of all application certificates in the certificate store.
• Added extension method AssureOwnCertificate to the IEasyUAClientServerApplication interface. The method assures presence of the instance certificate the application is currently configured to use. If the instance certificate does not exist in the certificate store prior to the operation, the method creates it. Otherwise, the method also checks whether the instance certificate is present in the trusted peers certificate store, and if it is absent, it copies it there.
• Added IEasyUAClientServerApplication.RemoveOwnCertificates method (notice the plural in the name), which allows to remove application certificates with sub-ids that conform to the specified pattern (you can use e.g. "*" to remove certificates with any sub-id).
• Allowed easy setting of more attribute values in generated certificate subject names, by adding properties to the UAApplicationManifest class. The new properties are CountryName (for C=), LocationName (for L=), OrganizationName (for O=), OrganizationalUnitName (for OU=), and StateOrProvinceName (for S=).
• The automatically generated certificate subject names now include the organization name (O=), taken from the application [AssemblyCompany] attribute, or application version info.
• The state of the OPC UA application (the application IDs obtained from the GDS endpoints) is now persisted on the disk. This means that when the application is terminated and then started again, the state information from the previous run will be reused. The state is persisted in the UAApplication.ini file.
• Added IEasyUAClientServerApplication.GetCertificateSubjectNameDictionary extension method. The method gets a dictionary of certificate subject names corresponding to all application certificate sub-ids.
• When using certificates obtained from the Certificate Manager, the application state now also remembers the mapping between the requested and actual certificate subject names, because the Certificate Manager may modify the requested subject name when issuing a new certificate. The mappings are also persisted in the UAApplication.ini file. This allows the application to find its own instance certificate even if the certificate subject name has been modified by the Certificate Manager.
• A certificate can now also be found in the certificate store using a "relaxed" method, in which case it is only enough when there is a match in the common name (CN=) of the certificate. This is useful when certificates are obtained from a Certificate Manager which modifies the subject names, and at the same time, the persistence of subject name mappings (in the UAApplication.ini) is not available. This method can be controlled using the new UAClientServerApplicationParameters.RelaxedCertificateSearch property (defaults to 'true').
• Improved the algorithm used to find the application assembly, which is then used to auto-generate application URI strings, and certificate subject names. The algorithm now works more reliably and gives better results under hosted environments such as ASP.NET (e.g. in IIS, IIS Express).
• Added an ability to specify the type of certificate to be obtained by the IEasyUAClientServerApplication.BeginObtainNewCertificate and IEasyUAClientServerApplicationExtension.ObtainNewCertificate methods. The certificate type Id can set in the UAObtainCertificateArguments.CertificateType property in the arguments object passed to the methods.
• Added ListCertificateTypeElements method to the IEasyUAClientServerApplication interface. The method retrieves node elements for of certificate types available for a given application store kind.
• Added arguments to IEasyUAClientServerApplication.CreateOwnCertificate, IEasyUAClientServerApplication.ObtainNewCertificate and IEasyUAClientServerApplication.RemoveOwnCertificate methods that allow to control whether the trusted peers certificate store will also be updated correspondingly. Added UAClientServerApplicationParameters.AutoTrustInstanceCertificate property with the same semantics, applied when a client instance certificate is automatically generated.
• Added overloads with capability to cancel the operation using the CancellationToken to extension methods IEasyUAClientServerApplication.ObtainNewCertificate and IEasyUAClientServerApplication.ObtainNewCertificateAsync.
• Added CheckTimeValidAndNested property to the UACertificateAcceptancePolicy class. When set to true (the default), the policy checks that the time value is valid (e.g. does not indicate that the certificate has expired) and that the CA certificate and the issued certificate have validity periods that are nested.
• Added RequireRevocationStatusKnown property to the UACertificateAcceptancePolicy class. When set to true (the default), the policy requires that it must be possible to determine whether the certificate has been revoked (the certificate revocation status may be unknown due to the certificate revocation list (CRL) being offline or unavailable).
• Added ImportOwnCertificateFromFile method to the IEasyUAClientServerApplication interface. The method imports the own certificate and its private key from a given file.
• Added ExportOwnCertificateToFile method to the IEasyUAClientServerApplication interface. The method exports the own certificate and optionally its private key to a given file.
• Added EasyUAApplication (generic) and EasyUAFormsApplication (for Windows Forms) components. The components allow direct access to operations related OPC UA Administration and PKI (rather than the former method of obtaining the OPC UA application service interface from the EasyUAClient object).

Component Refactorings

OPC UA

• The GdsEndpointDescriptor property (used in OPC UA global discovery with methods that do not specify their own GDS endpoint) has been moved from the EasyUAClient.InstanceParameters to the static EasyUAClient.SharedParameters.

Specialized Client Objects

• Renamed IEasyUACertificateManagement.GetCertificateGroups method to GetCertificateGroupIds.

OPC UA Administration and PKI

• The default lifetime of auto-generated application instance certificate is now 60 months (5 years), regardless of whether you target .NET Framework, or .NET 6+. Previously, the default was 600 months (50 years) for .NET Framework, and 12 months (1 year) otherwise.
• The property UAClientServerApplicationParameters.AllowOwnCertificatePrompt has been renamed to AllowUserInteraction and moved to the CertificateGenerationParameters class.
• The method IEasyUAClientServerApplication.RemoveInstanceCertificate has been renamed to RemoveOwnCertificate.
• Set non-empty default paths for HTTPS trusted and issuer certificate stores.
• The IEasyUAClientApplication service (interface) has been renamed to IEasyUAClientServerApplication.
• The IEasyUAClientServerApplication.GetApplicationManifest method has been renamed to GetEffectiveApplicationManifest.

User Interface

OPC UA Administration and PKI

• If the server certificate validation fails, and the component offers the user the option to accept it anyway (in console and Windows desktop applications), the user can now choose to trust the certificate permanently. With this choice, the certificate is copied to the trusted peers certificate store (and removed from the rejected certificates store). Note that the user running the application must have sufficient permissions to add the certificate to the trusted peers certificate store.
• Added IEasyUAClientServerApplicationExtension2.UIAdministerApplication extension method (typically used with the EasyUAFormsApplication component). In Windows desktop applications, the method shows the form (dialog) which allows the interactive user to administer the OPC UA application modally (end-user documentation: Dialog: Administer OPC UA Application). The "Administer OPC UA Application" dialog allows:
  • Viewing and managing trusted certificates. The user can change the Trusted, issuer and Rejected states of the certificates, import certificates, and delete certificates.
  • Managing the own application certificate, either using self-signed approach, or from an OPC UA Global Discovery Server (GDS). The application certificate can be exported or imported. The user can also protect the private key of the certificate with a password, or unprotect it. Automatic fixes are offered for common issues with the application certificate.
  • Viewing OPC UA application manifest.
• In Windows Forms applications, the method EasyUAFormsApplication.AddToSystemMenu adds the "Administer OPC UA Application" command to the system menu of the given form.

Development Productivity

Code Analysis

• When the Visual Studio extension is installed, it provides additional code analysis specifically aimed at the proper usage of QuickOPC APIs, and OPC in general. Affected places are marked up with "squiggles" directly in the code, and also appear as warnings (or other message severities) in the Error List window.

Tools and Online Services

Connectivity Explorer

• Added "Create Instance Certificate", "Remove Instance Certificate", "Validate Instance Certificate" and "View Instance Certificate" commands to the root OPC Unified Architecture (Client-Server) connectivity node.
• Added "Administer OPC UA Application" command to the application's system menu, and to the root OPC Unified Architecture (Client-Server) connectivity node.

OpcCmd Utility

OPC UA Client-Server

• Added command uaApplication|uaapp, which can be used instead of uaClient|uac getService|gs uaClientServerApplication|uacsa.
• The command uaApplication removeInstanceCertificate has been renamed to removeOwnCertificate.
• The uaApplication removeOwnCertificates command now has an additional option, -me|-mustExist <bool>, specifying whether the certificate must be present in the certificate store.
• Added createOwnCertificate and validateOwnCertificate commands to the uaApplication command.
• Added option --certificateSubId|-csi <string> to uaApplication commands that work with the application instance certificate. The option allows to enter the certificate sub-id, in case the application uses multiple own instance certificates. In some cases there is --certificateSubIdPattern|-csip <string> option instead.
• Added listCertificateSubIds command to the uaApplication command. The command finds and displays sub-ids of all application certificates in the certificate store.
• Added option --EndpointCertificateSubId|-ecsi <string> to commands that take OPC UA endpoint descriptor as an input. The option allows to enter the sub-id of the application instance certificate which will be used when establishing the connection.
• Added assureOwnCertificate command to the uaApplication command. The command assures presence of the instance certificate the application is currently configured to use.
• Added options to uaApplication createOwnCertificate and uaApplication validateOwnCertificate commands that allow you to parameterize the operation, such as choosing the minimum key size, or the certificate validity period in months.
• Added uaApplication getCertificateSubjectNameDictionary command. The command displays certificate subject names corresponding to all application certificate sub-ids.
• Added uaApplication listCertificateTypeElements command. The command list the certificate type elements available in the CM.
• Added commands related to certificate private key password protection to uaApplication. The commands are: HasPrivateKeyPassword, SetPrivateKeyPassword, RemovePrivateKeyPassword, ProtectOwnCertificate, and UnprotectOwnCertificate.
• The user can now cancel the uaApplication obtainNewCertificate command in progress, by pressing the X key.
• Added uaApplication importOwnCertificate command. The command imports the own certificate and its private key from a given file.
• Added uaApplication exportOwnCertificate command. The command exports the own certificate and optionally its private key to a given file.

All Command-Line Tools

• The .NET build configurations of the command-line tools now target .NET 7.
• In table output, values in columns with data of enumerated types are now automatically colorized, allowing quick visual distinction between the distinct enum values.

Examples

Platform: COM

• Added several Python examples for OPC "Classic" DataAccess, showing the usage of following methods: BrowseNodes, BrowseServers, GetPropertyValue, ReadMultipleItems, WriteItemValue.
• Added Python example showing how to subscribe to changes of multiple OPC-UA monitored items, pull events, and display each change.
• Added VBScript example showing how to read multiple values from the device (data source).

OPC UA Client-Server

• Added C# example showing how to set the validity period of the auto-generated application instance certificate.
• Added C# example showing how to assure presence of the own application certificate, and display its thumbprint.
• Added C# example showing how to browse and display the certificate groups available in the Certificate Manager.
• Enhanced example applications (EasyOpcUADemo, UAFormsDocExamples) using the EasyUAFormsApplication component to include the "Administer OPC UA Application" command on their form's system menu.

Documentation and Help

• User's Guide: Provided better explanation of which functionality belongs to the "designer integration" category and therefore will not work in Visual Studio versions earlier then the supported Visual Studio 2022. Explained what can be expected to work under Visual Studio versions such as Visual Studio 2019.
• User's Guide: Added a dedicated topic explaining which products parts are redistributable and which are not.