TIA Portal Openness C# — Common Foundation

Source: TIA Portal Openness General Functions Manual (03/2026, V21); V21 IntelliSense XML documentation files (PublicAPI\V21\net48\*.xml)

V21 modular assembly architecture

V21 splits the API across multiple DLLs instead of a single Siemens.Engineering.dll. Every project needs Siemens.Engineering.Base.dll; add domain DLLs as required. Referencing the wrong DLL (or omitting one) causes TypeLoadException at runtime.

Full mapping: See references/assembly-namespace-map.md for the V21 namespace → DLL → domain skill table, cross-assembly warnings, and csproj patterns.

Namespaces by assembly

Only import what is actually used. Commented using blocks for each assembly (Base, Step7, WinCC, Startdrive, Safety) are in references/assembly-namespace-map.md under "Common using blocks by assembly".

Assembly loading — mandatory for standalone Openness apps

Not needed for Add-Ins. TIA Portal loads Add-In assemblies via its own loader. This section applies only to standalone console/desktop Openness applications.

V21 installation paths

• Registry key: HKLM\SOFTWARE\Siemens\Automation\InstalledApps\Totally Integrated Automation Portal V21 → value INSTALLPATH
• Binary path: C:\Program Files\Siemens\Automation\Portal V21\PublicAPI\V21\net48\
• Manifest schemas: C:\Program Files\Siemens\Automation\Portal V21\PublicAPI\V21\Schemas\

Resolver pattern

When using the AssemblyResolve approach, register the event before any Openness type is referenced. This includes method parameters, return types, and class properties — not just method bodies. A correctly configured app.config binding is an alternative.

Recommended pattern: register in a static constructor of Program, then move all Openness code to a separate class so the resolver is active before those classes are loaded.

internal static class Program
{
    // Register resolver at earliest possible point
    static Program()
    {
        AppDomain.CurrentDomain.AssemblyResolve += OnAssemblyResolve;
    }

    public static void Main()
    {
        // All Openness code must be in a separate class
        var app = new OpennessApp();
        app.Run();
    }

    private static Assembly OnAssemblyResolve(object sender, ResolveEventArgs args)
    {
        // Read install path from registry (recommended) or hardcode for simple tools
        string opennessFolder = GetOpennessInstallPath(); // implement per project
        AssemblyName requestedName = new AssemblyName(args.Name);
        string filePath = Path.Combine(opennessFolder,
            string.Concat(requestedName.Name, ".dll"));

        if (!requestedName.Name.StartsWith("Siemens.Engineering.") ||
            !File.Exists(filePath))
            return null;

        Assembly loaded = Assembly.LoadFrom(filePath);
        if (requestedName.FullName != loaded.GetName().FullName)
            throw new FileNotFoundException(
                "TIA Portal Openness version does not match", filePath);

        return loaded;
    }
}

Key rules:

• Copy Local: False (<Private>False</Private>) must be set for every Siemens.Engineering assembly reference.
• V21 uses modular DLLs: Base.dll is always needed; add Step7.dll, WinCC.dll,

Startdrive.dll, etc. per task. The resolver handles all of them automatically because it matches any name starting with Siemens.Engineering..

• The recommended approach reads the install path from the registry key

HKLM\SOFTWARE\Siemens\Automation\InstalledApps\Totally Integrated Automation Portal V21 (value INSTALLPATH) rather than hardcoding it.

Registry-based path discovery:

private static string GetOpennessInstallPath()
{
    using (var key = Microsoft.Win32.Registry.LocalMachine.OpenSubKey(
        @"SOFTWARE\Siemens\Automation\InstalledApps\Totally Integrated Automation Portal V21"))
    {
        string installPath = key?.GetValue("INSTALLPATH") as string;
        if (string.IsNullOrEmpty(installPath))
            throw new FileNotFoundException("TIA Portal V21 installation not found in registry.");
        return Path.Combine(installPath, @"PublicAPI\V21\net48");
    }
}

Alternative — app.config: For stable installations where the path is known at build time, an app.config file with <assemblyBinding> / <codeBase> entries is a simpler option that requires no code. Use the AssemblyResolve event for tools that need to discover the install path at runtime.

TiaPortal instantiation

Always use a using statement so the session is disposed on exit or exception:

internal class OpennessApp
{
    public void Run()
    {
        using (TiaPortal tiaPortal = new TiaPortal(TiaPortalMode.WithUserInterface))
        {
            // All Openness work goes here
        }
        // TIA Portal is disposed (not necessarily closed) after this point
    }
}

Modes:

• TiaPortalMode.WithUserInterface — starts a new TIA Portal instance with a visible GUI
• TiaPortalMode.WithoutUserInterface — starts a new headless instance, suitable for automation pipelines

Attaching to a running instance:

// Attach to the first running TIA Portal process of this Openness version
TiaPortal tiaPortal = TiaPortal.GetProcesses().First().Attach();

Use GetProcesses() when TIA Portal is already open and you do not want to start a new instance. Returns only processes from the same Openness version as the loaded assembly.

Dispose vs. close:

• If started headless and no other Openness client is attached, Dispose() closes TIA Portal.
• If started with GUI or other clients are attached, Dispose() only disconnects.
• After disposal, the connection is no longer valid. A later API call after the TIA Portal

process is closed externally throws NonRecoverableException.

Service providers and event handlers

Full patterns: references/portal-services-and-events.md (Add-In MessageBoxProvider, ProgressProvider, FeedbackProvider via GetService<T>(), and the Disposed, Notification, Confirmation, Authentication events on TiaPortal).

Rules that always apply:

• GetService<T>() returns null in Add-In status callbacks (OnUpdateStatus);

use services only in action callbacks.

• Unsubscribe every TiaPortal event handler in a finally block.
• In Confirmation, e.Result must be "Yes", "YesToAll" or "No"; any other

value throws.

• Authentication (V17+) fires only for UMAC-protected projects; set

e.AuthenticationTypeProvider (DesktopSso, Anonymous, Interactive, Credentials).

Exclusive access

Highly recommended for all non-trivial operations. Signals TIA Portal that a controlled activity is in progress and displays a dialog to the user.

using (ExclusiveAccess exclusiveAccess = tiaPortal.ExclusiveAccess("Generating project"))
{
    // All Openness operations here run under exclusive access

    // Optionally update the displayed message during long operations
    exclusiveAccess.Text = "Compiling software";
    // ...
    exclusiveAccess.Text = "Downloading to PLC";
}
// Exclusive access is released on dispose

Rules:

• Only one ExclusiveAccess can exist at a time — a second attempt throws a recoverable

exception while the first is still active.

• Setting exclusiveAccess.Text = string.Empty or null clears the displayed message.

Transactions

Group multiple modifications into a single undo unit. Requires an active ExclusiveAccess.

using (ExclusiveAccess exclusiveAccess = tiaPortal.ExclusiveAccess("Bulk edit"))
{
    using (Transaction transaction = exclusiveAccess.Transaction(project, "Create blocks"))
    {
        // Perform all modifications
        project.DeviceGroups.Create("Line_1");
        project.DeviceGroups.Create("Line_2");

        // MANDATORY: call CommitOnDispose() to persist changes
        // If this line is never reached, the transaction is rolled back
        transaction.CommitOnDispose();
    }
}

Rollback rules — critical:

• If CommitOnDispose() is never called → rolled back on dispose.
• If an exception occurs at any point before the transaction is disposed → rolled back,

including when CommitOnDispose() was already requested or the exception was caught.

• After an EngineeringTargetInvocationException, a later CommitOnDispose() request can

itself raise a recoverable exception; check CanCommit and do not assume persistence.

Not allowed inside a transaction: Compile, go online/offline, ProjectText import/export, opening or closing a global library, project create/open/open-with-upgrade/save/save-as/close, and changing a TIA Portal setting. These calls raise a recoverable exception while a transaction is active.

Destructive-operation safety

These rules are mandatory for generated C# Openness code:

• Never bare `.Delete()`. Any destructive operation must be inside an active

ExclusiveAccess scope and a Transaction when the API permits transactions.

• Use using blocks for ExclusiveAccess, Transaction, TiaPortal, and other disposable

Openness objects so rollback and release behavior is explicit. Close projects explicitly according to lifecycle ownership; Project is not an IDisposable object.

• Call transaction.CommitOnDispose() only after every validation and mutation in

the transaction has succeeded.

• Run or request a compile check after generated block, tag, hardware, or HMI

changes. Do not present generated project changes as deployable until that check passes.

• If an API refuses to run inside a transaction, state that limitation explicitly,

use the narrowest possible ExclusiveAccess scope, and require a preview or user confirmation before the destructive call.

Exception handling

Two top-level categories:

Recoverable subtypes:

Recommended catch order:

try
{
    // Openness work
}
catch (EngineeringSecurityException ex)
{
    Console.WriteLine($"Access denied: {ex.Message}");
}
catch (EngineeringObjectDisposedException ex)
{
    Console.WriteLine($"Object disposed: {ex.Message}");
}
catch (EngineeringNotSupportedException ex)
{
    Console.WriteLine($"Not supported: {ex.MessageData.Text}");
    foreach (ExceptionMessageData detail in ex.DetailMessageData)
        Console.WriteLine($"  Detail: {detail.Text}");
}
catch (MissingProductsException ex)
{
    Console.WriteLine($"Missing products: {ex.Message}");
}
catch (EngineeringTargetInvocationException)
{
    throw; // Do not swallow — rethrow for caller to handle
}
catch (EngineeringException)
{
    throw; // Do not swallow general engineering exceptions
}
catch (NonRecoverableException ex)
{
    Console.WriteLine($"Fatal — TIA Portal closed: {ex.Message}");
    // Must restart TIA Portal; the session is gone
}

NonRecoverableException is generic; it can also mean TIA Portal crashed inside the call. Never retry the same call or continue an unattended batch after it. The real cause is in the Portal's crash report: %ProgramData%\Siemens\Automation\Portal V21\Diagnostics\<build>\<id>\<id>.dr (a ZIP with ErrorReport.xml, Reason="Openness") and the Windows Application log at the crash time.

Project open mode

When opening multiple projects or working in multiuser environments:

// Primary — visible in project navigation, full read-write access
Project primary = tiaPortal.Projects.Open(
    new FileInfo(path), umacDelegate, ProjectOpenMode.Primary);

// Secondary — hidden from UI, always read-only regardless of user rights
Project secondary = tiaPortal.Projects.Open(
    new FileInfo(path), null, ProjectOpenMode.Secondary);

bool isPrimary = secondary.IsPrimary; // false

Rules:

• Only one primary project per TIA Portal instance.
• Secondary projects do not need a primary project to be open first.
• A user with write rights to a UMAC-protected project still gets read-only access when

opening it as secondary.

Object model contracts

Composition methods

Most engineering objects are accessed through compositions. Available methods:

Not all methods are available on every composition — check domain skills.

Object equality

// Reference equality (same .NET object reference)
bool sameRef = (objA == objB);

// TIA Portal identity equality (same engineering object, possibly different references)
bool sameObj = System.Object.Equals(objA, objB);

Use System.Object.Equals() when comparing objects retrieved through different navigation paths that may represent the same underlying engineering object.

DirectoryInfo / FileInfo — absolute paths only

All DirectoryInfo and FileInfo instances passed to Openness must use absolute paths. Relative paths cause an exception at runtime.

// Correct
var dir = new DirectoryInfo(@"C:\Projects\MyProject\Export");

// Wrong — will throw
var dir = new DirectoryInfo(@"Export");

Bulk attribute access

Useful for dynamic tooling or when setting multiple attributes efficiently on HW objects.

Read all attributes

// Get names of all available attributes
IList<EngineeringAttributeInfo> infos =
    ((IEngineeringObject)deviceItem).GetAttributeInfos();

// Read all readable attributes in one call
IList<string> names = infos.Select(i => i.Name).ToList();
IList<object> values = ((IEngineeringObject)deviceItem).GetAttributes(names);

Filtered read by access mode

// AttributeAccessOptions: None, ReadOnly, WriteOnly, ReadWrite
IReadOnlyList<KeyValuePair<string, object>> readableAttrs =
    deviceItem.GetAttributes(AttributeAccessOptions.ReadOnly);

Bulk write (HW objects only — provides callback)

var pairs = new List<KeyValuePair<string, object>>
{
    new KeyValuePair<string, object>("Name", "NewModuleName"),
    new KeyValuePair<string, object>("Comment", "Auto-generated")
};

// Overload with callback fires after each attribute is set
deviceItem.SetAttributes(pairs, (name, val, ex) =>
{
    if (ex != null)
        Console.WriteLine($"Failed to set {name}: {ex.Message}");
});

// Overload without callback — for non-HW objects
((IEngineeringObject)someObject).SetAttributes(pairs);