mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-29 15:11:53 +08:00
f6b27025a6
## Proposed changes Fixes #4857. The stack's log messages wrote network addresses (endpoint, discovery and reverse connect URLs, host names, IP addresses, ports), application and user identities, file paths and exception texts as plain parameters. Applications had no reliable way to keep them out of general-purpose logs. This PR replaces the stack's own redaction mechanism with the standard .NET [data classification and redaction](https://learn.microsoft.com/dotnet/core/extensions/data-redaction) packages. Each sensitive `[LoggerMessage]` parameter is classified. The application decides per classification what reaches its logs: erase it, replace it with an HMAC token so entries stay correlatable, or pass it through. ### Taxonomy `Opc.Ua.Redaction.OpcUaDataClassifications` defines the `OpcUa` taxonomy and one attribute per classification: | Classification | Used for | Parameters | |---|---|---| | `[NetworkAddress]` | URLs, host and domain names, IP/MAC addresses, end points, ports | 120 | | `[ApplicationIdentity]` | certificates, subject, issuer, thumbprint, ApplicationUri | 103 | | `[FilePath]` | file, directory and certificate store paths | 67 | | `[SensitiveText]` | exception or remote-supplied text passed as a parameter | 55 | | `[UserIdentity]` | user names, token subjects | 7 | Correlation ids (`ChannelId`, `SessionId`, ...), status codes and NodeIds stay unclassified. ### Pipeline and defaults - Opc.Ua.Core now references `Microsoft.Extensions.Telemetry(.Abstractions)` 10.11.0, so every project above Core uses the `Microsoft.Gen.Logging` generator. Opc.Ua.Client already did, through Http.Resilience. The packages ship net462 and netstandard2.0 builds, so net48 is supported. - **A plain `ILoggerFactory` logs `(null)` in place of classified values.** Classified values are only written by the redaction-aware logger. - The new `ILoggingBuilder.EnableOpcUaRedaction()` turns that logger on. It is `EnableRedaction()` with the discriminator off; otherwise every unredacted value gets `:ParamName` appended. `AddOpcUa().AddLogging(...)` and `DefaultTelemetry.Create(...)` call it, as do the samples, so they log the same information as before until redactors are registered. - `services.AddOpcUa()` alone does not change the host's logging. Generic-host apps call `builder.Logging.EnableOpcUaRedaction()`. This is documented as a behavior-breaking change in `docs/migrate/2.0.x/telemetry.md`. ### Obsolete API `Redact`, `RedactionWrapper<T>`, `IRedactionStrategy`, `RedactionStrategies` and `SimpleRedactionStrategy` are `[Obsolete]`. They still work, but the stack no longer uses them. ### Not classified - The `Exception` passed to a log call. Applications can drop exception messages with `LoggerEnrichmentOptions.IncludeExceptionMessage`. - Exception and `ServiceResult` message texts. - `ServiceResult`/`StatusCode` parameters and logged data values. - The few log calls whose level is decided at run time. - `Opc.Ua.Vision.OpenUsd`, which references only Opc.Ua.Types and cannot see the attributes. ### Generator behavior differences These are visible to log consumers and to tests: - `IFormattable` values such as `NodeId` are stored in the structured state as invariant strings, not as objects. - The generated log state is a thread-local object that is cleared after the call. - Classified values are pooled redactor objects, valid only during the `Log` call. Tests that inspected log state after the fact now capture it during the call. The shared `RecordingLoggerProvider` snapshots classified values. ## Related Issues - Fixes #4857 ## Types of changes - [ ] Bugfix (non-breaking change which fixes an issue) - [x] Enhancement (non-breaking change which adds functionality) - [ ] Test enhancement (non-breaking change to increase test coverage) - [x] Breaking change (fix or feature that would cause existing functionality to not work as expected; plain logger factories drop classified values) - [x] Documentation Update (if none of the other choices apply) ## Checklist - [x] I have read the CONTRIBUTING doc. - [x] I have signed the CLA. - [x] I ran tests locally with my changes, all passed. - [x] I fixed all failing tests in the CI pipelines. - [x] I fixed all introduced issues with CodeQL and LGTM. - [x] I have added tests that prove my fix is effective or that my feature works and increased code coverage. - [x] I have added necessary documentation (if appropriate). - [ ] Any dependent changes have been merged and published in downstream modules. ## Further comments New tests: - `LogClassificationCoverageTests` (Tools.Tests) scans all 104 stack assemblies and fails if an address, identity or path parameter of a `[LoggerMessage]` method is unclassified. - `DataClassificationLoggingTests` (Core.Tests) pins erasing and HMAC redaction, pass-through, the plain-factory drop, and both stack defaults. Local results on net10.0: | Suite | Passed | Failed | |---|---|---| | Core.Tests | 6,489 | 0 | | Client.Tests | 3,231 | 0 | | Tools.Tests | 7,210 | 0 | | PubSub.Tests | 1,536 | 0 | | Core.Diagnostics.Tests | 571 | 0 | | Configuration.Tests | 241 | 0 | - **Server.Tests:** the full run predates the final test fixes and had 12 failures. All 12 were in the fixtures fixed afterwards, which now pass: RoleStateBinding (45/45) and the FileDirectory and compatibility-logging fixtures (74/74 in total). The full Core.Tests and Server.Tests runs were not repeated after those fixes. - **Builds:** `UA.slnx` builds with 0 errors for net10.0 and net48, and the whitespace check passes. - **NativeAOT:** not confirmed locally, because the machine has no C++ linker. A trimmed publish of `Opc.Ua.Aot.Tests` reported no trim or AOT warnings from the stack, the new packages or the generated logging code; its only errors come from the TUnit test framework (`FSharp.Core` not found). The `aot-test` CI job has to confirm the native build. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Marc Schier <marcschier@users.noreply.github.com>
Console Reference PubSub
A single, self-contained OPC UA Part 14 PubSub reference application built on the
fluent PubSubApplicationBuilder + dependency injection + .NET Generic Host surface.
One executable exposes three command-line-selectable modes, and publishes as a
NativeAOT-ready single-file executable.
Modes
ConsoleReferencePubSubClient <mode> [options]
| Mode | Purpose |
|---|---|
publisher |
Publishes a built-in sample DataSet over UDP/UADP or MQTT (UADP/JSON). |
subscriber |
Receives DataSets and logs each decoded message to the console. |
external |
Bridges an external OPC UA server to PubSub via the Opc.Ua.PubSub.Adapter library (publisher / subscriber / responder direction). |
publisher
ConsoleReferencePubSubClient publisher --profile udp-uadp --interval 1000
ConsoleReferencePubSubClient publisher --profile mqtt-json --endpoint mqtt://localhost:1883
Options: --profile udp-uadp|mqtt-uadp|mqtt-json, --config-file <xml>,
--publisher-id, --writer-group-id, --data-set-writer-id, --endpoint, --interval.
subscriber
ConsoleReferencePubSubClient subscriber --profile udp-uadp
Options: --profile, --config-file <xml>, --publisher-id-filter,
--writer-group-id-filter, --data-set-writer-id-filter, --endpoint.
Publisher and subscriber on one computer
The default UDP endpoint, opc.udp://239.0.0.1:4840, is a multicast address.
Multicast loopback is disabled by default, so a subscriber on the publisher's
computer can miss the messages. To run both on one computer, give both the
unicast loopback endpoint:
ConsoleReferencePubSubClient subscriber --profile udp-uadp --endpoint opc.udp://127.0.0.1:4840
ConsoleReferencePubSubClient publisher --profile udp-uadp --endpoint opc.udp://127.0.0.1:4840
See Run a first publisher and subscriber for the expected output and the settings that must match.
external
Bridges an external OPC UA server (defaults to the repository's ConsoleReferenceServer
at opc.tcp://localhost:62541/Quickstarts/ReferenceServer; override with --endpoint or
the OPCUA_EXTERNAL_ENDPOINT environment variable).
# Read an external server and publish its values (cyclic Read each cycle)
ConsoleReferencePubSubClient external --mode publisher --read-mode cyclic
# Read via a client Subscription cache, one subscription per WriterGroup
ConsoleReferencePubSubClient external --mode publisher --read-mode subscription --affinity writergroup
# Write received PubSub values back to an external server
ConsoleReferencePubSubClient external --mode subscriber
# Map an inbound PubSub Action to an external server method call
ConsoleReferencePubSubClient external --mode responder
# Run a bidirectional bridge in one process
ConsoleReferencePubSubClient external --mode publisher,subscriber
Options: --mode publisher|subscriber|responder (comma-separated list accepted),
--read-mode cyclic|subscription, --affinity writergroup|datasetwriter,
--endpoint <external server>, --pubsub-endpoint <udp url>, --hot-reload.
Hot reload
Add --hot-reload to the external bridge to run the opt-in live reconfiguration
demo:
ConsoleReferencePubSubClient external --mode publisher,subscriber --hot-reload
The bridge writes pubsub-config.xml next to the executable before starting and
loads adapter options from the copied appsettings.json in the same directory.
Edit and save either file while the bridge is running:
appsettings.json: changeExternalPublisher:ReadModefromCyclictoSubscription, or changeExternalPublisher:AffinitytoDataSetWriter, to rewire the external-server publisher options.pubsub-config.xml: add or remove aDataSetWriterto change the PubSub topology. The watching XML store raises a configuration change and the adapter incrementally rewires the affected binding.
The samples connect to the external server unsecured (
SecurityMode.None) for zero-config interop. A production bridge must useSignAndEncryptwith a provisioned application instance certificate. See docs/PubSub.md external-server adapter section.
Build / publish
dotnet build samples/PubSub/ConsoleReferencePubSubClient/ConsoleReferencePubSubClient.csproj
dotnet publish samples/PubSub/ConsoleReferencePubSubClient/ConsoleReferencePubSubClient.csproj -r win-x64
See docs/PubSub.md for the full PubSub guide.