UA Bundle SDK .NET  2.2.4.281
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties Events Groups Pages
Configuration Schema

Overview

The ApplicationInstance depends on an XML configuration file which specifies various parameters needed by the application to run. Most of these parameters have suitable default values; however, some are required to properly configure security. In these cases, the SDK will pick suitable defaults to ensure an application can run without a configuration file, however, Application Developers must provide them before deploying any real application.

The schema for this configuration file is based on the SecuredApplication schema defined in Annex D of Part 6 of the OPC UA Specification. Configuration specific to the SDK or to applications built with the SDK can be added to the Extensions element defined by the SecuredApplication schema. This can be found in the folder "configurationschema". The methods ParseExtension<T> and UpdateExtension<T> on the ApplicationInstance object can be used to read or update any individual extension. These methods require a class which supports serialization with the WCF DataContract serializer or with the standard .NET XML serializer.

The SDK defines several standard extensions for different groups of configuration parameters which, by convention, all end with the suffix ‘Settings’. These standard extensions are described below along with the mandatory elements from the SecuredApplication schema. The SDK supports the use of file paths relative to special folder names. This allows the same configuration file to be used on different machines. The syntax replaces the drive letter with a special folder name enclosed in percent signs (%). For example, the following path refers to the Documents folder for the current user:

%MyDocuments%/Logs/LogFile.txt

The complete set of special folder names is defined by the Environment.SpecialFolder enumeration.

SecuredApplication

This is the base schema for the application configuration file.

Note
All HTTPS certificates must be placed in the “LocalMachine\My” store because of issues with Windows HTTPS.SYS configuration. The TrustList for HTTPS certificates is “LocalMachine\Root”. HTTPS certificates must also be explicitly bound to a port and a network interface. The SDK takes care of creating these bindings and uses the existing bindings to find the certificate for the endpoint.
ElementDescription
ApplicationNameA human readable name for the application.
The value has a default chosen by the application vendor but can be changed by the administrators of the application.
ApplicationUriA globally unique identifier for the application instance. This must be a valid URI which should include the DNS name of the machine, the name of the product and the name of the application.
ApplicationTypeThe type of application.
May be Server_0 or Client_1.
Product NameA human readable name for the product.
This value is set by the application vendor.
ApplicationCertificateLocation and identifier for the application instance certificate.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\PrivateKeys"
TrustedCertificateStoreLocation of the trusted certificate store.
Peer and CA certificates which the application trusts are placed here.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\Trusted"
IssuerCertificateStoreLocation of the issuer certificate store.
Certificates which are needed to validate certificate chains are placed here.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\Issuers"
RejectedCertificatesStoreLocation of the rejected certificate store.
Stores certificates which have been rejected because they are untrusted.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\Rejected"
BaseAddressesThe list of endpoint URLs supported by Server.
Any URL with “localhost” as the domain is bound to all machine IP addresses. The “localhost” is changed to the default DNS name of the machine during initialization.
A URL with “127.0.0.1” as the domain is only accessible to Clients running on the same machine.
For each URI scheme the following transport profiles are assumed:
opc.tcpUaTcpTransport
httpWsHttpXmlOrBinaryTransport
https HttpsXmlOrBinaryTransport
nosecurityhttpHttpsXmlOrBinaryTransport
SecurityProfilesA list of supported security profiles.
If omitted then the Basic256 and None profiles are used as defaults.
ExtensionsA list of SDK and application specific configuration settings.
Any valid XML is allowed. The XML is parsed when the ApplicationInstance.ParseExtension<T> method is called by the application.

TransportSettings

These values specify various limits used by the transport layer.

ElementDescription
MaxBufferSizeThe maximum size of any buffers allocated.
If not specified, the default is 65,536.
MaxStringLengthThe maximum length of any encoded String value.
If not specified, the default is 16,777,216.
MaxByteStringLengthThe maximum length of any encoded ByteString value.
If not specified, the default is 16,777,216.
MaxArrayLengthThe maximum length of any encoded array value.
If not specified, the default is 65,536.
MaxMessageSizeThe maximum size of any encoded message.
If not specified, the default is 16,777,216.
OperationTimeoutThe default timeout, in milliseconds, for any service request.
If not specified, the default is 120,000.
ChannelLifetimeThe lifetime, in milliseconds, of a secure channel.
If not specified, the default is 3,600,000.
SecurityTokenLifetimeThe lifetime, in milliseconds, of a security token.
If not specified, the default is 120,000.

InstallationSettings

These values specify various options used during installation/uninstallation.

ElementDescription
GenerateCertificateIfNoneIf TRUE a new certificate is generated if a valid one does not exist.
If not specified, the default is TRUE.
CertificateKeyLengthThe length of the auto-created certificate in bits.
The default and minimum is 1024.
CertificateHashAlgorithmThe hash algorithm used on the auto-created certificate.
The default is 'sha1'. Supported values are 'sha1' and 'sha256'.
DeleteCertificateOnUninstallIf TRUE the application certificate is deleted during uninstall.
If not specified, the default is TRUE.
ConfigureFirewallIf TRUE the firewall is configured to open or close ports used by the endpoints specified for the application.
If not specified, the default is FALSE.
ConfigureHttpAccessIf TRUE any HTTP or HTTPS endpoints are configured to allow access by a process running with the credentials of the UsersGroup.
If not specified, the default is TRUE.
InstallAsServiceIf TRUE a Server is configured to run as a Windows Service.
If not specified, the default is FALSE.
The service will run as 'Local System'.
ServiceNameThe name of the Windows Service created during install.
Must be specified if InstallAsService is set to TRUE.
ServiceDescriptionA human readable description for the Windows Service.
If not specified, the default is an empty string.
ServiceStartModeThe following values are possible: Auto, Manual, Disabled.
If not specified, the default is Manual
UsersGroupThe name of the Windows Account Group which is allowed to run the application. If not specified, the default is the ‘Users’ built-in group.
AdministratorsGroupThe name of the Windows Account Group which is allowed to administer the application.
If not specified, the default is the ‘Administrators’ built-in group.

TraceSettings

These values control the information written to the trace log files.

ElementDescription
TraceFileThe location of the trace file.
If not specified, then no trace information is written to a file.
MaxEntriesPerLogThe maximum number of entries per log file.
If not specified, then default is 0 (no limit).
MaxLogFileBackupsThe maximum number of backup for log files.
If not specified, then default is 0 (no backups).
FastTraceIf TRUE, the trace file is kept open. If FALSE, the trace file is opened and closed for each log message written.
If not specified then the default is FALSE.
MasterTraceEnabledIf FALSE, all tracing is disabled.
If not specified then the default is FALSE.
DefaultTraceLevelThe default trace level.
If not specified, then the default is “Error”.
ModuleSettingsA list of settings for each trace module in the process.
ModuleNameThe name of the trace module.
If not specified, then the module is ignored.
TraceEnabledIf FALSE, then tracing is disabled for the module.
If not specified, then the default is TRUE.
TraceLevelThe default trace level for the module.
If not specified, then the default is “Default”.

TraceLevels

These are the possible trace levels that can be specified.

LevelDescription
DefaultUse the default trace level.
NoneTurn all tracing off.
ErrorUnexpected errors that require the attention of developers or administrators.
WarningLess critical issues that also require the attention of developers or administrators.
SystemGeneral system messages.
InfoInformational messages.
InterfaceCallThe entry and exit messages for major API methods.
ConstructorThe constructors of major API objects.
ProgramFlowAdditional entry and exit messages for minor API methods.
DataVerbose information when the state of objects changes during processing.

ClientSettings

These values control the information written to the trace log files.

ElementDescription
ProductUriA globally unique identifier for the product that client belongs to.
If not specified then the default is an empty string.
DiagnosticMasksThe diagnostic masks to use with each request.
If not specified, then the default is 0 (no diagnostics).
RequestTimeoutThe timeout in milliseconds for each service request.
If not specified, then the default is 30,000.
MaxOperationsPerRequestThe maximum number of operations per request.
If a request is passed to the SDK with more than this number, then the SDK will break the call into separate requests.
If a service request is broken into multiple requests, then the RequestTimeout is for the entire set of requests.
If not specified, then the default is 1,000.
SessionTimeoutThe requested timeout, in milliseconds, for a session.
If not specified, then the default is 600,000.
WatchdogCycleTimeThe time interval, in milliseconds, between cycles of the watchdog which checks the status of the connection with the Server.
If not specified then the default is 5,000.
WatchdogTimeoutThe maximum time, in milliseconds, that the watchdog waits for a response from the Server before starting the reconnection process.
If not specified then the default is 10,000.
AutomaticReconnectIf TRUE, the watchdog will attempt to reconnect to the Server when it detects an error after it has connected.
If not specified then the default is TRUE.
RetryInitialConnectIf TRUE, the server will keep trying to connect if the initial attempt fails.
It will stop when a timeout occurs.
If not specified, then the default is TRUE.
ReconnectDelayThe time in milliseconds between reconnect attempts.
If not specified, then the default is 10,000.

ServerSettings

These values control the base configuration for the Server.

ElementDescription
ProductUriA globally unique identifier for the product that server belongs to.
The default is constructued with the ApplicationUri.
ProductNameA human readable name for the product that server belongs to.
The default is the Product attribute for the EXE assembly.
ManufacturerNameA human readable name for the manufacurer of the product.
The default is the Company attribute for the EXE assembly.
SoftwareVersionA string representing the version of the Server software.
The default is the first 2 fields from the EXE assembly FileVersion attribute.
BuildNumberA string representing the build of the Server software.
The default is the last 2 fields from the EXE assembly FileVersion attribute.
BuildDateWhen the Server software was built.
The last write time for the EXE assembly is the default.
IsAuditActivatedIf true, the Server will produce audit events.
The default is FALSE.
IsDiagnosticsEnabledIf true, the Server will track diagnostics information.
The default is FALSE.
AvailableLocaleIdsA list of locales supported by the Server. The syntax is defined by RFC 1766.
The default is "en-US".
AvailableServerProfilesA list of profiles supported by the Server.
No profiles are specified by default.
UserIdentityThe user identities supported by the server.
DiscoveryRegistrationThe discovery registration settings for servers.

EndpointSettings

These values control the security options and network interface used by a base address.

ElementDescription
EndpointUrlThe URL which the settings apply to. This URL must match one of the URLs in the SecuredApplication.BaseAddresses list.
NetworkInterfaceThe IP address to use when binding the socket. It can be an IPv4 or IPv6 address. If omitted, then the socket is bound to all IP addresses for the machine.
DisableNoSecurityIf true, the None message security mode is disabled for this endpoint. The default value is false.
EnableSignOnlyIf true, the SignOnly message security mode is enabled for this endpoint. The default value is false.
DisableSignAndEncryptIf true, the SignAndEncryp message security mode is disabled for this endpoint. The default value is false.

UserIdentitySettings

These values control what user identity tokens are accepted by a Server.

ElementDescription
EnableAnonymousWhether anonymous users are allowed.
Enabled if the UserIdentitySettings are missing from the configuration.
EnableUserNameWhether authentication with a username and password is allowed.
Disabled if the UserIdentitySettings are missing from the configuration.
EnableCertificateWhether authentication with an X509 certificate is allowed.
Disabled if the UserIdentitySettings are missing from the configuration.

DiscoveryRegistrationSettings

These values control how a server registers with the local discovery server.

ElementDescription
UrlThe URL of the discovery server the server must register with.
The default is 'opc.tcp://localhost:4840'.
EnabledWhether the server should attempt to register with the discovery server.
The default is TRUE.
RegistrationIntervalThe interval in milliseconds between registration attempts.
The default and maximum is 30,000.

ThreadPoolSettings

These values control the thread pool used by the server.

ElementDescription
MinThreadCountThe minimum number of threads.
The default and minimum value is 10.
MaxThreadCountThe maximum number of threads.
The default is 1000 and the minimum value is 10.
MaxRequestCountThe maximum number of requests in the queue waiting for a thread.
The default is 2000 and the minimum value is 100.

SessionSettings

These values control the behavoir of the SessionManager in the Server.

ElementDescription
MaxRequestAgeThe maximum difference in milliseconds between the timestamp of the request and the current time.
The minimum and default is 600,000.
MaxSessionCountThe maximum number of open sessions.
The default is 100 and the minimum is 10.
MinSessionTimeoutThe minimum timeout in milliseconds for sessions.
The default is 20,000 and the minimum is 1,000.
MaxSessionTimeoutThe maximum timeout in milliseconds for sessions.
The default and the minimum is the MinSessionTimeout. The maximum is 600,000.
MaxBrowseContinuationPointsThe maximum number of browse continuation points per session.
The default and minimum is the MaxNodesPerBrowse.
MaxHistoryContinuationPointsThe maximum number of history continuation points per session.
The default and minimum is the MaxNodesPerHistoryDataRead.
MaxNodesPerReadThe maximum number of read operations per request.
The default and minimum is 10,000.
MaxNodesPerWriteThe maximum number of write operations per request.
The default and minimum is 10,000.
MaxNodesPerHistoryDataReadThe maximum number of history data read operations per request.
The default and minimum is 1,000.
MaxNodesPerHistoryDataUpdateThe maximum number of history data update operations per request.
The default and minimum is 1,000.
MaxNodesPerHistoryEventReadThe maximum number of history event read operations per request.
The default and minimum is 1,000.
MaxNodesPerHistoryEventUpdateThe maximum number of history event update operations per request.
The default and minimum is 1,000.
MaxNodesPerMethodCallThe maximum number of call operations per request.
The default and minimum is 10,000.
MaxNodesPerBrowseThe maximum number of browse operations per request.
The default and minimum is 1,000.
MaxNodesPerRegisterNodesThe maximum number of register node operations per request.
The default and minimum is 1,000.
MaxNodesPerTranslateBrowsePathsToNodeIdsThe maximum number of translate browse operations per request.
The default and minimum is 1,000.
MaxNodesPerNodeManagementThe maximum number of add or delete node operations per request.
The default and minimum is 100.
MaxMonitoredItemsPerCallThe maximum number of monitored item operations per request.
The default and minimum is 10,000.
MinNonceLengthThe minimum nonce length.
The default and minimum is 32.

SubscriptionSettings

These values control the behavoir of the SubscriptionManager in the Server.

ElementDescription
MinPublishingIntervalThe minimum publishing interval in milliseconds.
The minimum and default is PublishingIntervalResolution.
MaxPublishingIntervalThe maximum publishing interval in milliseconds.
The minimum and default is the MinPublishingInterval. The maximum is 60,000.
MaxKeepAliveIntervalThe maximum keep alive interval in milliseconds.
The minimum and default is the MinKeepAliveInterval. The maximum is 3,600,000.
MinKeepAliveIntervalThe minimum keep alive interval in milliseconds.
The minimum and default is 1,000.
MinLifetimeThe minimum subscription lifetime in milliseconds.
The minimum and default is the larger of 20,000 or the MinKeepAliveInterval.
MaxLifetimeThe maximum subscription lifetime in milliseconds.
The minimum and default is the MinLifetime. The maximum is 3,600,000.
PublishingIntervalResolutionThe minimum publish interval in milliseconds.
The default is 100. The minimum is 50.
MaxPublishRequestCountThe maximum number of queued publish requests per session.
The default is 100. The minimum is 2.
MaxSubscriptionCountThe maximum number of subscriptions.
The default and minimum is 10.
MaxNotificationsPerPublishThe maximum number of notifications per publish request.
.The default is 10,000.
MaxMessageQueueSizeThe maximum of saved messages per subscription.
The default is 100.
MaxDataValueQueueSizeThe maximum queue size for data monitored items.
The default and minimum is 1,000.
MinEventQueueSizeThe minimum queue size for event monitored items.
The default and minimum is 1,000.
MaxEventQueueSizeThe maximum queue size for event monitored items.
The default is the MinEventQueueSize. The minimum is 10,000.