mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-17 05:11:13 +08:00
Marc Schier
c4e0721a29
## Summary
### Documentation
- Stage the documentation index as a learning path: a first application,
independent client, server, and PubSub paths, then data and services,
companion models, production, advanced integration, and draft or
experimental capabilities.
- Add Getting started (repository samples or NuGet packages), OPC UA
concepts, Your first information model, and a production readiness
checklist.
- Add Native AOT application publishing, a first PubSub publisher and
subscriber exchange, and the UDP transport options.
- Add or expand contents navigation throughout `docs/`, and keep
contributor documentation separate.
- Correct outdated SDK examples and capability guidance, consolidate
repeated explanations into canonical guides, and repair local links and
heading structure.
- Rewrite What's New in 2.0 as a concise feature overview with short
linked details; keep migration instructions in the Migration Guide.
- Expand the feature catalogue with specification IDs, GDS, LDS, the OPC
10000-21 onboarding registrar, ISA-95, xRegistry, OpenUSD, and
sample-local models; distinguish draft status, explain crypto
pluggability, and bring performance guidance forward.
- Address review feedback on wording, active monitored items during
shadow reload, and the `Samples.md` filename and references.
- Regenerate the `opcua-v20-migration` plugin's bundled copy of the
migration guides so it matches the edited `docs/migrate/2.0.x` guides.
- Merge the latest `master`, preserving upstream resource-isolation
guidance within the task-based documentation index.
- Retain deferred Lingity findings where appropriate; this PR does not
claim that every document meets the Lingity score thresholds.
### Fixes found while verifying the guides
Each fix has regression tests that fail without it.
- **Client:** V2 subscriptions compared their lifetime with the
operation timeout instead of the session timeout, and logged a spurious
warning. `ISubscriptionEngineContext`, which is new in 2.0, gains a
`SessionTimeout` property; implementations must add it.
- **PubSub:** a subscriber now registers the `DataSetMetaData`
configured on its readers (OPC 10000-14 6.2.9.4), and the UADP decoder
decodes DataSetMessages that carry no ConfigurationVersion. Before, a
secured subscriber of the reference sample received no DataSets.
- **Source generator:** a ModelDesign method that declares its arguments
inline, without a method type, produced code that did not compile; it
now uses `MethodState`. The generated code of existing models is
unchanged.
- **MinimalClient sample:** waits for its first data-change notification
before it disconnects.
### Known issues, not addressed here
- UDP multicast: the publisher does not send on the interface that the
subscriber joins, and `MulticastLoopback` defaults to false. The PubSub
guide uses unicast for the exchange on one computer.
- The UDP metadata announcement is sent unsecured on secured writer
groups; a secured subscriber drops it with a warning.
- A server does not start in globalization-invariant mode, because
`ResourceManager` creates `CultureInfo("en-US")`. The Native AOT guide
cautions against the mode.
## Validation
- `git diff --check` and
`./.azurepipelines/validate-migration-plugin.ps1` (15 bundled migration
docs validated, plugin manifests synchronized).
- Local Markdown links, anchors, file-link casing, and contents lists
checked across all 87 documents under `docs/`. The index links every
top-level guide and every target of the previous index.
- Both Getting started routes, Your first information model, the PubSub
exchange, and the Native AOT publish of the Getting started client and
server were run as documented. The NuGet route and the tutorial use the
public `2.0.0-preview.5` packages.
- The changed libraries build for all target frameworks in Release
without warnings.
- Tests on .NET 10: Opc.Ua.SourceGeneration.Tests 199 passed;
Opc.Ua.SourceGeneration.Core.Tests 3,977 passed, 8 skipped;
Opc.Ua.Server.Tests `Fluent` category 621 passed; Opc.Ua.Client.Tests
subscription-engine tests 70 passed; Opc.Ua.PubSub.Tests 1,374 passed, 2
skipped; PubSub fuzz replay 145 passed. The new and affected tests also
pass on .NET Framework 4.8.
- Earlier merge validation: 174 resource-isolation tests passed on .NET
10.
- The full solution suite was not run locally.
Review and validation artifacts are maintained outside the repository.
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
6.8 KiB
6.8 KiB
Production readiness checklist
The samples and Getting started use shortcuts that are suitable only on a development computer: temporary certificate stores, automatic certificate acceptance, anonymous users, and short reconnect limits. Review this checklist before you deploy a client or server. Each item links to the guide that explains the setting. The checklist does not replace a security review of your deployment.
Contents
- Application identity and certificates
- Endpoints and message security
- Users and permissions
- Secrets and private keys
- Resource limits
- Diagnostics and auditing
- Clients
- Deployment and operation
Application identity and certificates
- Give each installation a unique
ApplicationUrithat matches its application certificate. See Concepts: applications. - Set
PkiRootto a persistent, access-controlled directory. The hosted client and server default to a folder in the system temporary directory. See Application identity and certificate defaults. - Keep
AutoAcceptUntrustedCertificatesdisabled, and provision the trusted and issuer certificates, or CA-issued certificates, before peers connect. See Certificates. - Keep SHA-1 certificates rejected and an RSA key size of at least 2048 bits; both are the defaults. See Server security and resource controls.
- Plan certificate renewal and trust-list updates, for example with certificate-expiration alarms, push management, or a Global Discovery Server. See Certificate manager and GDS.
Endpoints and message security
- Offer
SignAndEncryptendpoints and keepIncludeUnsecurePolicyNoneset tofalse; both are the hosted-server defaults. See Server security and resource controls. - Enable
IncludeEccPoliciesonly when every client supports the ECC policies. ECC SecureChannel policies require the .NET 8 or later assemblies. See ECC profiles: known limitations. - Configure clients to select a
SignAndEncryptendpoint. See Concepts: endpoints, secure channels, and sessions.
Users and permissions
- Decide whether anonymous access is acceptable. A hosted server without
UserTokenPoliciesadvertises anAnonymouspolicy. See User token policies. - Register an authenticator for each user-token policy that the server
advertises, for example with
AddDefaultIdentityAuthenticators. A policy without an authenticator does not authenticate users. See Identity providers. - Map identities to roles and restrict node permissions. See Role-based user management.
- Set session and channel ceilings for the expected load, and keep the
failed-authentication lockout (
MaxFailedAuthenticationAttempts, default 5). See Server security and resource controls.
Secrets and private keys
- Keep passwords, tokens, and private keys out of source code, configuration files in source control, and container images.
- Store credentials through an
ISecretStorethat is backed by a durable, access-controlled secret service; a hosted server registers one withAddSecretStore. See Dependency injection: server feature. - Where policy requires it, keep private keys in a TPM, HSM, PKCS#11 token, or key service. See Crypto providers.
Resource limits
- Review the transport quotas (
MaxMessageSize,MaxArrayLength,MaxByteStringLength) and the serviceOperationLimits. See Operation limits. - Tune the admission rate limits, which are enabled by default, with
ConfigureRateLimits. See Rate limiting. - Review the resource-isolation profile;
Balancedis the default. See Server resource isolation. - Size the server for the expected sessions, subscriptions, and monitored items. See Server scalability.
Diagnostics and auditing
- Send logs, metrics, and traces to your monitoring system through the
host's logging and
ITelemetryContext. See Diagnostics. - Enable audit events when you must record security-relevant actions; they are off by default. See Enabling auditing.
- Decide whether to keep the server diagnostics nodes (
DiagnosticsEnabled, defaulttrue), which add per-session and per-subscription work. See Enabling diagnostics. - Use packet capture and key logs only for troubleshooting. Key logs make captured traffic decryptable. See Diagnostics: security model.
Clients
- Keep the default reconnect policy for long-running clients. The Getting started client limits retries only to report errors quickly. See Reconnect semantics.
- Trust server certificates explicitly instead of accepting them automatically. See Certificates.
- Store namespace URIs, not namespace indexes, and resolve indexes after each connection. See Concepts: node identity and namespaces.
- Pass cancellation tokens and dispose sessions and subscriptions. See Concepts: how the SDK is organized.
Deployment and operation
- Keep the clocks of clients and servers synchronized, for example with NTP or PTP. Certificate validity, timestamps, and redundancy depend on it. See Kubernetes: time synchronization.
- In containers, mount the certificate stores on persistent storage and supply secrets at run time. See Container reference server and Kubernetes: secrets, certificates, and trust.
- Use a Global Discovery Server or provisioning mode to manage certificates across many installations. See GDS and Provisioning mode.
- Add redundancy only when availability requirements need it. See High availability.