jfk-solutions.TiaFileFormat 2026.9.16.1

Info

TiaFileFormat a Library to access all Tia Portal project Files from Version V10.5 - V20

Package

https://www.nuget.org/packages/jfk-solutions.TiaFileFormat/

Homepage

https://github.com/jfk-solutions/TiaFileFormat

Documentation

• AutomationML export and cross references: TiaFileFormat vs. TIA Portal Openness
• TIA file format storage overview

Project loading

The default loading mode reads project data sequentially and works with project archives, standalone database streams, and unpacked projects without an index:

using var provider = TiaFileProvider.CreateFromSingleFile(projectPath);
var project = TiaProject.Load(provider);

Unpacked projects with a supported System/PEData.idx can load database object payloads on demand instead:

var project = TiaProject.Load(provider, useIndex: true);

To ignore an existing index and force the original sequential behavior:

var project = TiaProject.Load(provider, useIndex: false);

The same useIndex parameter is available on TiaDatabaseFile.Load. Indexed loading also defers business-object headers and object allocation. Use the type-aware block lookup to preserve that behavior during exports:

foreach (var storageObject in CodeBlockConverter.FindConvertibleObjects(
             project.Database, prioritizeLargeObjects: true))
{
    // Convert matching PLC block objects in a balanced order for parallel export.
}

Omit prioritizeLargeObjects or set it to false when the original database order is required.

StorageObjectCount, MaterializedStorageObjectCount, IndexedHeaderReadCount, IndexedPayloadReadCount, IndexedPayloadBytesRead, and IndexedHashReadCount show how many indexed objects and payloads were actually touched. Accessing the legacy StorageObjectDictionary, StorageObjects, or AllStorageObjects properties still materializes every object to preserve existing behavior. Explicitly enabling indexed loading uses a supported index from an unpacked project. If the index is missing or belongs to an older project format, the loader ignores it automatically and uses the sequential path. A present but malformed index still causes loading to fail. Archives remain available through the default or explicitly disabled mode.

Automation XML compatibility

Existing calls keep the established V21 serialization conventions. To match TIA Portal V19 PLC block/type XML, select V19 explicitly:

using TiaFileFormat.Wrappers.Converters.AutomationXml;

var xml = block.ToAutomationXml(new AutomationXmlConverter.ConvertOptions
{
    Compatibility = AutomationXmlConverter.CompatibilityMode.V19,
    WriteCommentAndTitleAlthoughWhenEmpty = true,
});

The same options work with WriteAutomationXml. V19 mode writes interface and LAD/FBD/STL/SCL network XML as separately indented fragments, includes fail-safe memory layout, and exports author/family/version metadata for locked blocks. Implementation details of locked blocks remain suppressed. Existing switches, including WithDefaultsInInterface and WithReadOnlyAttributes, still apply. IncludeFailSafeMemoryLayout can also be enabled independently in V21 mode.

The mode controls serialization conventions; it does not convert a project to another TIA version or change the document's project version. It is not selected automatically from the project version, so existing callers retain their output. Other TIA versions and non-PLC exporters have no version-specific profile yet.

V19 was compared against Openness V19 Update 5 using a copy of Software1500_6.6.0-8014b79b: all 425 exported blocks/types matched byte for byte after excluding the UTF-8 BOM and Openness DocumentInfo metadata. FOB_RTG1 was excluded. The six reported AWL blocks exported successfully; template category casing is corrected in both modes. This comparison covers XML exports, not a separate source-format export_all run. The default output was also compared with the unmodified converter on MixedSample.ap21: all 64 exports were byte-identical.

Password-protected blocks

Pass passwords when converting storage objects, before calling ToAutomationXml:

var readOptions = new TiaFileFormat.Wrappers.ConvertOptions();
readOptions.EncryptionOptions.EncryptionPasswordsPerBlock[blockName] = password;
// Alternatively, add candidate passwords to EncryptionPasswords.
var block = (BaseBlock)new CodeBlockConverter().Convert(storageObject, readOptions);
var xml = block.ToAutomationXml(xmlOptions);

Password-based decryption is independent of V19/V21 XML compatibility. Successfully decrypted blocks export their implementation even while IsKowHowProtected remains true; DecryptionPossible records successful decryption. For supported protection formats, a missing or incorrect password leaves the block locked; the XML exporter still exports its available interface and metadata. Do not skip conversion solely because a block is protected, and do not set DecryptionPossible manually. A password cannot make an unsupported protection format decryptable; unsupported protection versions currently raise an exception during conversion. When retrying with a password, reconvert the original storage object with fresh read options; XML serialization itself does not try passwords.

Offline block call paths

BlockCallPathCatalogBuilder builds call sites, instance-DB associations, and complete calling paths directly from an offline TIA project:

using TiaFileFormat.Wrappers.CodeBlocks.CallPaths;

var catalog = BlockCallPathCatalogBuilder.Build(project);

foreach (var path in catalog.CallingPaths)
{
    Console.WriteLine(path.DisplayName);
}

If the blocks were converted already, avoid loading them again:

var catalog = BlockCallPathCatalogBuilder.BuildFromBlocks(blocks);

The protocol-neutral BuildFromCatalogData entry point is available to online adapters and other block sources that already provide resolved call sites.

Compact MDD catalog cache

Hardware AutomationML export can obtain channel definitions from the compiled MDD catalogs installed with TIA Portal. Point MddHardwareCatalogResolver at the TIA Portal Data directory and create a compact cache once:

using TiaFileFormat.Wrappers.Hardware.Mdd;

var resolver = new MddHardwareCatalogResolver(
    @"C:\Program Files\Siemens\Automation\Portal V21\Data");

var build = resolver.CreateCache(
    @"D:\TiaCatalogs\TIA-V21.mddcache",
    new Progress<MddCatalogCacheProgress>(progress =>
    {
        Console.WriteLine(
            $"{progress.ProcessedSourceFiles}/{progress.TotalSourceFiles}: " +
            progress.CurrentSource);
    }),
    cancellationToken);

Console.WriteLine(
    $"{build.EntryCount} entries, {build.ChannelCount} channels, " +
    $"{build.CompressedSize} bytes");

foreach (var diagnostic in build.Diagnostics)
    Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");

The first build opens each configured .mdd.bin.pkg archive once and decodes its MDD entries. It can take a while for a complete installed catalog. The output is a versioned, GZip-compressed binary file containing only package and entry identities, decode status, and the channel fields consumed by the hardware AML exporter. It does not contain raw MDD payloads, language dictionaries, or absolute installation paths. An existing cache is replaced atomically after a successful build. Cancellation or a failure therefore leaves the existing file intact.

Deploy the resulting cache instead of the installed MDD package directory and pass it through the normal hardware conversion options:

var options = new HardwareConversionOptions
{
    CatalogSources = new[] { @"D:\TiaCatalogs\TIA-V21.mddcache" }
};

var hardware = project.ToHardwareProject();
var conversion = hardware.ConvertAll(options);

A .mddcache file can also be passed directly to MddHardwareCatalogResolver, or placed in a catalog directory that contains no raw MDD files. Cached entries are preferred if both the cache and original packages are configured. Rebuild the cache after installing or updating TIA hardware support packages, or when a future cache format version requires it.

The compact cache covers MDD data only. GSDML XML is still read from the project's AdditionalFiles/GSD directory when present, or from an explicitly configured GSDML catalog source such as the installed Data/XDD/GSD directory.

Licensing

Visit http://jfk-solutions.de for more information.

How To Release

• Build release Build
• Run IntelliLock and Protect Assemblies
• Run nuget\CreateNuget.ps1
• Upload Nuget