Skip to content

configuration.md

Latest commit

 

History

History
90 lines (56 loc) · 5.04 KB

configuration.md

File metadata and controls

90 lines (56 loc) · 5.04 KB
Raw

Configuration and State Persistence

When to read this: Read this for ApplicationConfiguration changes, the removed Data-Contract serializer, Newtonsoft removal from Opc.Ua.Core, the new ParseExtension / UpdateExtension signature, and session / browser state persistence.

Configuration

Data Contract Serializer support removed

Because Data Contract serialization is not AOT compliant and does not support trimming, all use of DataContract in the configuration has been removed. Instead, the source generator enables generating IEncodeable implementations using the DataType and DataTypeField attributes which are now consequently used for all configuration. Because the configuration is now IEncodeable the existing encoders and decoders (in particular the new XmlParser which parses Xml and allows out of order fields) compliant with Part 6 can be used to serialize and deserialize all configuration and configuration extensions.

Generated Data types still support DataContract based serialization, however, consider this a deprecated feature.

All configuration DTO classes (ApplicationConfiguration, ServerConfiguration, TraceConfiguration, TransportConfiguration, ServerSecurityPolicy, OAuth2ServerSettings, OAuth2Credential, GlobalDiscoveryServerConfiguration, CertificateGroupConfiguration, BrowserOptions, etc.) migrated from [DataContract]/[DataMember] to source-generated [DataType]/[DataTypeField] attributes and are now partial classes.

  • ApplicationConfiguration.LoadWithNoValidation uses XmlParser/IEncodeable.Decode(). Existing XML config files should remain loadable.
  • Browser and session state persistence switched from XML to OPC UA Binary encoding. Old persisted files cannot be loaded — delete and re-save.
  • SecuredApplication uses SecuredApplicationEncoding helpers instead of DataContractSerializer.

Change code as follows:

  • Replace [DataContract(Namespace = ...)] with [DataType(Namespace = ...)] and [DataMember(...)] with [DataTypeField(...)] on custom configuration subtypes.
  • Add the partial keyword to any subclass of these configuration types.
  • Custom configuration extension types must implement IEncodeable (the [DataType] source generator handles this automatically for partial classes).
  • Code using reflection to inspect [DataContract]/[DataMember] attributes must switch to [DataType]/[DataTypeField].

Newtonsoft.Json removed from Opc.Ua.Core

Newtonsoft.Json is no longer a dependency of Opc.Ua.Core. Projects relying on its transitive availability must add an explicit reference:

<PackageReference Include="Newtonsoft.Json" Version="13.0.4" />

ParseExtension/UpdateExtension signature changed

ParseExtension<T>() and UpdateExtension<T>() now require T to implement IEncodeable. New delegate-based overloads were added for custom decoding:

// Generic overload (T must implement IEncodeable)
var config = configuration.ParseExtension<MyConfig>();

// Delegate overload for custom decoding
var config = configuration.ParseExtension<MyConfig>(
    new XmlQualifiedName("MyConfig", myNamespace),
    decoder => { var c = new MyConfig(); c.Decode(decoder); return c; });

ExtensionObject array helpers changed

ExtensionObject.ToArray(object, Type) and ToList<T>(object) removed. Use extensionObjects.GetStructuresOf<T>() or ExtensionObject.ToArray<T>(ArrayOf<ExtensionObject>).

IJsonEncodeable interface removed

The IJsonEncodeable interface and the entire "Default JSON Encoding" infrastructure have been removed. OPC UA JSON encoding is handled by the JsonEncoder/JsonDecoder classes which do not require per-type encoding node IDs — those classes are unaffected by this change.

Migration steps:

  1. Remove IJsonEncodeable from any custom class that implements it:

    - public class MyType : IEncodeable, IJsonEncodeable
+ public class MyType : IEncodeable

  2. Remove the JsonEncodingId property from those classes:

    - public ExpandedNodeId JsonEncodingId => ...;

Session and Browser State Persistence

Breaking Change: Persistence switched from DataContractSerializer XML to IEncoder and IDecoder. BrowserState, SessionState, SessionOptions, SubscriptionState, and MonitoredItemState are annotated with [DataType] and use the standard Encode/Decode methods generated by the source generator.

To register the state types with the encodeable factory:

context.Factory.Builder.AddOpcUaClientDataTypes();

The encoding format for session state has changed. Existing persisted session state files cannot be loaded by the new SessionConfiguration.Create() method. Handle restore failures and re-persist the new session state.

See also