/tia-csharp-common

name: tia-csharp-common
description: Internal reference skill — do NOT load directly from user queries.
license: MIT

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 exter