siemens/tia-portal-ai-extensions/change-detection

Change Detection

Overview

Openness offers no single "diff" API. Instead, several targeted services and properties each answer a narrower question about what changed. Pick the right one for the question you're actually asking instead of re-reading and comparing the whole project.

Required Namespaces

using Siemens.Engineering;
using Siemens.Engineering.CrossReference;

Common Patterns

Choose the Right Change-Detection Service

Description: Match the question you need answered to the corresponding service or property. Re-reading and diffing an entire project tree is expensive (see `performance-and-caching`) — these services are purpose-built to be cheap and precise.

Check the PLC Program Checksum

Description: PlcChecksumProvider exposes a checksum that changes whenever the compiled PLC program changes. It is empty until the software has been fully compiled at least once, and resets to empty on further edits until the next compile.

Example:

PlcChecksumProvider checksumProvider = plcSoftware.GetService<PlcChecksumProvider>();
string checksum = checksumProvider.Checksum;
if (string.IsNullOrEmpty(checksum))
{
    // Not compiled yet, or changed since last compile — trigger ICompilable.Compile() first
}

Key Types and Methods:

• PlcChecksumProvider — service on PlcSoftware
• PlcChecksumProvider.Checksum — empty when not (yet) compiled or when the program changed since the last compile

Check Fine-Grained Block/UDT Fingerprints

Description: FingerprintProvider exposes separate fingerprints for different aspects of a block or PLC data type (code, interface, properties, comments, etc.), letting you detect exactly what part changed instead of only whether something changed.

Example:

FingerprintProvider fingerprintProvider = block.GetService<FingerprintProvider>();
string interfaceFingerprint = fingerprintProvider.InterfaceFingerprint;
string codeFingerprint = fingerprintProvider.CodeFingerprint;

Key Types and Methods:

• FingerprintProvider — service available on program blocks and PLC data types
• Exposes separate fingerprints per aspect (code, interface, properties, comments, ...)

Check Safety Signatures

Description: SafetySignatureProvider exposes multiple, granular F-signatures used for Safety administration and Safety program blocks, allowing precise change tracking in Safety-relevant parts of a project.

Key Types and Methods:

• SafetySignatureProvider — service exposing F-signatures for Safety administration and program blocks

Quick Reference

Related Files

• `blocks` — CrossReferenceService usage pattern in full
• `global-library` — LibraryTypeVersion dependency/dependant tracking
• `performance-and-caching` — ObjectIdentifierProvider for stable re-fetch, and why avoiding full re-reads matters
• `plc-safety-administration` — Safety administration context for SafetySignatureProvider

Exception Handling

• GetService<T>() for these providers throws if the object does not support that service — check object classification (e.g. only PlcSoftware supports PlcChecksumProvider) before requesting it.
• A PlcChecksumProvider.Checksum of empty string is a valid state (not-yet-compiled or changed-since-compile), not an error — do not treat it as a failure.