blocks
/blocks
TIA Portal PLC blocks management. Use when importing, compiling, exporting, protecting blocks with passwords, accessing InstanceDB/GlobalDB interface members, and finding cross-references.
- Author
- asckye ↗
- Repository
- tia_portal_openness_mcp ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
TIA Portal PLC blocks management. Use when importing, compiling, exporting, protecting blocks with passwords, accessing InstanceDB/GlobalDB interface members, and finding cross-references.
Original author description
TIA Portal PLC blocks management. Use when importing, compiling, exporting, protecting blocks with passwords, accessing InstanceDB/GlobalDB interface members, and finding cross-references.
How it works
- Overview
- Required Namespaces
- Required Assemblies
- Common Patterns
- Quick Reference
- Related Files
- Exception Handling
SKILL.md preview
---
name: blocks
description: TIA Portal PLC blocks management. Use when importing, compiling, exporting, protecting blocks with passwords, accessing InstanceDB/GlobalDB interface members, and finding cross-references.
metadata:
siemens-depends-on: "openness-base, engineering-objects"
---
# Blocks
## Overview
Blocks are the fundamental executable and data objects in a TIA Portal PLC project. They include OBs (Organization Blocks), FCs (Function Calls), FBs (Function Blocks), DBs (Data Blocks), and SFCs. The `PlcSoftware.BlockGroup` provides access to all blocks. Blocks can be imported, compiled, exported, password-protected, and analyzed for cross-references. InstanceDB and GlobalDB blocks expose interface members that define their variable declarations.
## Required Namespaces
```csharp
using Siemens.Engineering;
using Siemens.Engineering.Compiler;
using Siemens.Engineering.CrossReference;
using Siemens.Engineering.SW;
using Siemens.Engineering.SW.Blocks;
```
## Required Assemblies
- `Siemens.Engineering.Base.dll`
- `Siemens.Engineering.Step7.dll`
## Common Patterns
### Access Block Composition from PlcSoftware
**Description:** Retrieve the block composition from `PlcSoftware` to enumerate or search for blocks. The `BlockGroup.Blocks` collection contains all PLC blocks at that group level.
**Example:**
```csharp
var blockComposition = plcSoftware.BlockGroup.Blocks;
```
**Key Types and Methods:**
- `PlcSoftware.BlockGroup` — root container for all blocks
- `PlcBlockComposition` — collection of PLC blocks (one group level only)
### Find Block Recursively
**Description:** `Blocks.Find(name)` searches only the current group level. To find a block anywhere in the hierarchy, recurse into sub-groups. For a PLC-wide search that also covers SW-Unit groups, see [`sw-units`](../sw-units/SKILL.md).
**Example:**
```csharp
PlcBlock FindBlockRecursive(PlcBlockGroup group, string name)
{
var result = group.Blocks.Find(name);
if (result != null) return result;
foreach (var sub in group.Groups)
{
result = FindBlockRecursive(sub, name);
if (result != null) return result;
}
return null;
}
```
**Key Types and Methods:**
- `PlcBlockGroup.Blocks.Find(name)` — single-level lookup; returns `null` if not found at this level
- `PlcBlockGroup.Groups` — sub-folder composition; iterate to recurse
### Import Blocks into Composition
**Description:** Import block files into the block composition. Three distinct import paths exist — using the wrong API for a given format will fail silently or throw.
| Source type | API | Notes |
|---|---|---|
| XML block export (`.xml`) | `PlcBlockComposition.Import(FileInfo, ImportOptions)` | Direct import |
| SCL text source (`.scl`) | `ExternalSourceGroup` → `CreateFromFile` → `GenerateBlocksFromSource` | Two-step: register + compile |
| SIMATIC SD document (`.s7dcl`, V21) | `PlcBlockComposition.ImportFromDocuments(dir, name, options)` | Direct document import — see [`simatic-sd`](../simatic-sd/SKILL.md) |
**XML import example:**
```csharp
targetBlockGroup.Blocks.Import(new FileInfo(xmlFilePath), ImportOptions.Override);
```
**SCL import via ExternalSources example:**
```csharp
// Use the target SW-Unit's ExternalSourceGroup when placing inside a SW-Unit
var externalSource = externalSourceGroup.ExternalSources.CreateFromFile(
sourceFile.Name, sourceFile.FullName);
externalSource.GenerateBlocksFromSource();
externalSource.Delete();
```
**Key Types and Methods:**
- `PlcBlockComposition.Import(FileInfo, ImportOptions)` — XML only; do NOT use for `.scl` or `.s7dcl`
- `ExternalSourceGroup.ExternalSources.CreateFromFile` — registers an SCL/text source
- `PlcExternalSource.GenerateBlocksFromSource()` — compiles the registered source into blocks
- `PlcBlockComposition.ImportFromDocuments(DirectoryInfo, string, ImportDocumentOptions)` — SD documents (V21)
**Import anti-patterns:**
- Do NOT call `Import` on an `.scl` file — that API is XML-only.
- Do NOT use `ExternalSources.CreateFromFile` + `GenerateBlocksFromSource` on `.s7dcl` — use `ImportFromDocuments`.
### Import Order Rule
When importing multiple block types in one operation, always follow this order to avoid unresolved-type errors:
1. **PLC Data Types (UDTs)** — must exist before any block that references them in its interface
2. **FBs and FCs** — may reference UDTs
3. **OBs and Instance DBs** — may reference FBs/FCs
Violating this order causes `EngineeringException` ("Unresolved type reference") at import or compile time.
### Compile and Export Block
**Description:** Obtain the `ICompilable` service from a block or from `PlcSoftware` itself, trigger compilation, check the result, then export the block to a file.
**Example:**
```csharp
var block = plcSoftware.BlockGroup.Blocks.First(b => b.Name == "Axis_blue");
// Compile a single block
var compiler = block.GetService<ICompilable>();
var result = compiler.Compile();
// Inspect result.State and result.Messages — do not assume success
if (result.State == CompilationResultState.Success)
block.Export(fileInfo, ExportOptions.None);
// Compile the entire PlcSoftware
var swCompiler = plcSoftware.GetService<ICompilable>();
var swResult = swCompiler.Compile();
```
**Key Types and Methods:**
- `ICompilable` — service available on individual blocks and on `PlcSoftware`
- `ICompilable.Compile()` — compiles and returns a result object
- `CompilationResult.State` — overall outcome (`Success`, `Warning`, `Error`)
- `CompilationResult.Messages` — individual compiler messages with severity
- `PlcBlock.Export(FileInfo, ExportOptions)` — exports the block as XML
### Compile Scopes — Choose the Right Object to Compile
**Description:** `ICompilable` is available on several object types, each compiling a different scope. Requesting the service from the wrong level either compiles too much (wasting time) or too little (missing hardware/software consistency checks).
| Scope | Call `ICompilable` on | Notes |
|---|---|---|
| Hardware only | `DeviceItem` | Compiles the hardware configuration only, no PLC program |
| Software only | `PlcSoftware` | Compiles the PLC user program only, no hardware config |
| Hardware + Software | `Device` | Compiles hardware configuration and software together |
| Single block | the `PlcBlock` itself | Compiles just that one program block |
```csharp
// Hardware only
ICompilable hwCompiler = deviceItem.GetService<ICompilable>();
CompilerResult hwResult = hwCompiler.Compile();
// Software only
ICompilable swCompiler = plcSoftware.GetService<ICompilable>();
CompilerResult swResult = swCompiler.Compile();
// Hardware + software together
ICompilable deviceCompiler = device.GetService<ICompilable>();
CompilerResult deviceResult = deviceCompiler.Compile();
```
**Key points:**
- Prefer the narrowest scope that answers your question — e.g. compile a single block during iterative development instead of the whole `PlcSoftware`.
- Use `Device`-level compile when hardware and software consistency must be validated together (e.g. before download).
### Compile Diagnostics — recurse into nested `CompilationResult.Messages`
**Description:** Reading only the top-level `CompilationResult.Messages[].Description` often yields empty or summary-only text. The detailed compiler diagnostics can live on each message's nested `Messages` composition, so treat compile output as a tree rather than a flat list.
**Example:**
```csharp
IEnumerable<string> FlattenMessages(IEnumerable<CompilerResultMessage> messages)
{
foreach (var message in messages)
{
if (!string.IsNullOrWhiteSpace(message.Description))
yield return message.Description;
foreach (var nested in FlattenMessages(message.Messages))
yield return nested;
}
}
var readableMessages = FlattenMessages(result.Messages).ToList();
```
**Key points:**
- Recurse before concluding that a compile failed "without useful error text" — the useful text is often nested.
- Use `CompilationResult.ErrorCount` or `CompilationResult.State` first to decide whether you need to flatten the message tree.
- Keep both the summary rows and the nested leaf messages when reporting diagnostics to a user.
### Protect Block with Password
**Description:** Apply password protection to a block using the `PlcBlockProtectionProvider` service. Validate password characters before setting to ensure they meet the provider's requirements.
**Example:**
```csharp
var protectionProvider = block.GetService<PlcBlockProtectionProvider>();
var invalidChars = protectionProvider.GetInvalidPasswordCharacters().ToList();
protectionProvider.Protect(securePassword);
```
**Key Types and Methods:**
- `PlcBlockProtectionProvider` — service for managing block protection
- `GetInvalidPasswordCharacters()` — returns characters that are not allowed in passwords
- `Protect(SecureString)` — applies password protection to the block
### Get InstanceDB and GlobalDB Interface Members
**Description:** Access the interface members (variable declarations) of InstanceDB and GlobalDB blocks. Use pattern matching with `is not` to safely cast the block type before accessing its `Interface.Members`.
**Example:**
```csharp
if (plcSoftware.BlockGroup.Blocks.First(x => x.Name == "Axis_red_DB") is not InstanceDB instanceDb) return;
var instanceMembers = instanceDb.Interface.Members;
```
**Key Types and Methods:**
- `InstanceDB` — data block instance associated with an FB
- `InstanceDB.Interface.Members` — collection of variable declarations
- `GlobalDB` — standalone global data block
- `GlobalDB.Interface.Members` — collection of variable declarations
### Get Cross References for a Block
**Description:** Analyze which other blocks reference a given block using the `CrossReferenceService`. Filter by `AllObjects` or other criteria to get a comprehensive view of block dependencies.
**Example:**
```csharp
var db = plcSoftware.BlockGroup.Blocks.First(x => x.Name == "Axis_red_DB");
var crossRefService = db.GetService<CrossReferenceService>();
var crossRefs = crossRefService.GetCrossReferences(CrossReferenceFilter.AllObjects).Sources.ToList();
```
**Key Types and Methods:**
- `CrossReferenceService` — service for querying cross-references
- `CrossReferenceFilter.AllObjects` — filter to include all object types
- `CrossReference.Sources` — collection of referencing objects
## Quick Reference
| Method/Pattern | Purpose |
|---|---|
| `software.BlockGroup.Blocks` | Access blocks at the current group level |
| `FindBlockRecursive(group, name)` | Find a block anywhere in the group hierarchy |
| `PlcBlockComposition.Import(path, ImportOptions)` | Import blocks from an XML file |
| `ExternalSources.CreateFromFile` + `GenerateBlocksFromSource` | Import SCL text source |
| `PlcBlockComposition.ImportFromDocuments(dir, name, options)` | Import SIMATIC SD document (V21) |
| `ICompilable.Compile()` | Compile a block or PlcSoftware and get results |
| `ICompilable` on `DeviceItem`/`PlcSoftware`/`Device` | Compile hardware-only / software-only / hardware+software |
| `PlcBlock.Export(path, ExportOptions)` | Export a block as XML |
| `PlcBlockProtectionProvider.Protect(SecureString)` | Password-protect a block |
| `InstanceDB.Interface.Members` | Get variable declarations of an instance DB |
| `GlobalDB.Interface.Members` | Get variable declarations of a global DB |
| `CrossReferenceService.GetCrossReferences()` | Find references to a block |
## Related Files
- [`plc-data-types`](../plc-data-types/SKILL.md) — UDTs live in `TypeGroup`, not `BlockGroup`
- [`sw-units`](../sw-units/SKILL.md) — PLC-wide block search across root and all SW-Unit groups
- [`simatic-sd`](../simatic-sd/SKILL.md) — SD document export/import and network insertion
- [`global-library`](../global-library/SKILL.md) — placing blocks from a GlobalLibrary (MasterCopy or LibraryType)
- [`tags-and-tagtables`](../tags-and-tagtables/SKILL.md) — blocks reference tags defined in tag tables
- [`online-and-download`](../online-and-download/SKILL.md) — blocks are downloaded to the CPU device
- [`libraries-and-alarms`](../libraries-and-alarms/SKILL.md) — libraries may contain reusable blocks
- [`change-detection`](../change-detection/SKILL.md) — `PlcChecksumProvider` and `FingerprintProvider` for detecting program/block changes without recompiling
## Exception Handling
- `EngineeringException` may be thrown during compilation if the block has unresolved references or syntax errors
- `EngineeringException` may occur when importing blocks if the file format is incompatible or corrupted
- Check `CompilationResult.ErrorCount > 0` before attempting to export or download compiled blocks
Versions
The database has no other skills named blocks.
Database snapshot: 13.11.2026 · package version b67a8bfbeb7c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100tags-and-tagtables
Tags and tag tables management in TIA Portal. Use when accessing, creating, renaming PLC tags, exporting/importing tag tables to XML, and finding tags by name. - 90tiaxmz-tgdwjp
TIA Portal(博图)PLC 项目开发全流程——通过 tia-portal MCP 连接建项目、询问并添加 PLC 设备与型号、生成中文命名 IO 变量表、提纯控制要求交用户确认、按标准程序框架封装按钮/动作/流程/模式、以 S7DCL 梯形图编写并导入编译交付。Use when 用户说"写 TIA 程序"、"做 PLC 项目"、"博图编程"、"帮我写/改 PLC 控制程序"、"用 TIA 做 XX 站"、"PLC 梯形图",或发来 IO 表、控制要求、工艺描述要求编写西门子 S7 程序时。Not for 非西门子/非 TIA 的 PLC,或只讲概念不写程序的提问。 - 100online-and-download
Online connection and download operations for TIA Portal. Use when connecting to CPU devices via OnlineProvider, downloading PLC software, configuring connection modes, and handling passwords. - 100tia-multiuser
TIA Portal Multiuser Engineering operations. Use for managing server projects, local sessions, and multiuser commissioning workflows. - 100laddoc-cloud
把 LadDoc(JSON 格式的 PLC 梯形图文档)校验后确定性生成为 TIA Portal V19 可直接导入的 SimaticML 块(FC/FB/OB)。当用户要"用 AI 生成梯形图块"、"让 AI 写 LAD 并导入博途"、"LadDoc 校验/生成 SimaticML"、"批量生成 PLC 块"时使用。不需要博途即可生成,导入时才需要博途 V19。 In English — generate TIA Portal V19-importable SimaticML blocks (FC/FB/OB) deterministically… - 100laddoc-cloud
把 LadDoc(JSON 格式的 PLC 梯形图文档)校验后确定性生成为 TIA Portal V19 可直接导入的 SimaticML 块(FC/FB/OB)。当用户要"用 AI 生成梯形图块"、"让 AI 写 LAD 并导入博途"、"LadDoc 校验/生成 SimaticML"、"批量生成 PLC 块"时使用。不需要博途即可生成,导入时才需要博途 V19。 In English — generate TIA Portal V19-importable SimaticML blocks (FC/FB/OB) deterministically…