Project Check

for TIA Portal

Siemens
TIA Portal / Openness API / Programming style guide Industry
Online
https://support.industry.siemens.com/cs/ww/en/view/109741418 Support
 Legal information

Legal information
Use of application examples
Application examples illustrate the solution of automation tasks through an interaction of several
components in the form of text, graphics and/or software modules. The application examples are
a free service by Siemens AG and/or a subsidiary of Siemens AG ("Siemens"). They are non-
binding and make no claim to completeness or functionality regarding configuration and
equipment. The application examples merely offer help with typical tasks; they do not constitute
customer-specific solutions. You yourself are responsible for the proper and safe operation of the
products in accordance with applicable regulations and must also check the function of the
respective application example and customize it for your system.
Siemens grants you the non-exclusive, non-sublicensable and non-transferable right to have the
application examples used by technically trained personnel. Any change to the application
examples is your responsibility. Sharing the application examples with third parties or copying the
application examples or excerpts thereof is permitted only in combination with your own products.
The application examples are not required to undergo the customary tests and quality inspections
of a chargeable product; they may have functional and performance defects as well as errors. It is
your responsibility to use them in such a manner that any malfunctions that may occur do not
result in property damage or injury to persons.

Disclaimer of liability
Siemens shall not assume any liability, for any legal reason whatsoever, including, without
limitation, liability for the usability, availability, completeness and freedom from defects of the
application examples as well as for related information, configuration and performance data and
any damage caused thereby. This shall not apply in cases of mandatory liability, for example
under the German Product Liability Act, or in cases of intent, gross negligence, or culpable loss of
life, bodily injury or damage to health, non-compliance with a guarantee, fraudulent
non-disclosure of a defect, or culpable breach of material contractual obligations. Claims for
damages arising from a breach of material contractual obligations shall however be limited to the
© Siemens AG 2020 All rights reserved

foreseeable damage typical of the type of agreement, unless liability arises from intent or gross
negligence or is based on loss of life, bodily injury or damage to health. The foregoing provisions
do not imply any change in the burden of proof to your detriment. You shall indemnify Siemens
against existing or future claims of third parties in this connection except where Siemens is
mandatorily liable.
By using the application examples, you acknowledge that Siemens cannot be held liable for any
damage beyond the liability provisions described.

Other information
Siemens reserves the right to make changes to the application examples at any time without
notice. In case of discrepancies between the suggestions in the application examples and other
Siemens publications such as catalogs, the content of the other documentation shall have
precedence.
The Siemens terms of use (https://support.industry.siemens.com) shall also apply.

Security information
Siemens provides products and solutions with industrial security functions that support the secure
operation of plants, systems, machines and networks.
In order to protect plants, systems, machines and networks against cyber threats, it is necessary
to implement – and continuously maintain – a holistic, state-of-the-art industrial security concept.
Siemens’ products and solutions constitute one element of such a concept.
Customers are responsible for preventing unauthorized access to their plants, systems, machines
and networks. Such systems, machines and components should only be connected to an
enterprise network or the Internet if and to the extent such a connection is necessary and only
when appropriate security measures (e.g. firewalls and/or network segmentation) are in place.
For additional information on industrial security measures that may be implemented, please visit
https://www.siemens.com/industrialsecurity.
Siemens’ products and solutions undergo continuous development to make them more secure.
Siemens strongly recommends that product updates are applied as soon as they are available
and that the latest product versions are used. Use of product versions that are no longer
supported, and failure to apply the latest updates may increase customer’s exposure to cyber
threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS Feed
at: https://www.siemens.com/industrialsecurity.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 2
 Table of contents

Table of contents
Legal information ......................................................................................................... 2
1 Introduction ........................................................................................................ 4
1.1 Overview............................................................................................... 4
1.2 Mode of operation ................................................................................ 4
1.3 Installation ............................................................................................ 6
1.4 Compatibility ......................................................................................... 6
1.5 System properties ................................................................................ 6
2 Handling.............................................................................................................. 7
2.1 Desktop application .............................................................................. 7
2.2 Console application ............................................................................ 12
2.3 Scope ................................................................................................. 13
2.4 Hints and error handling ..................................................................... 14
3 Rule set "Programming style guide for SIMATIC S7-1200 / S7-1500" ........ 15
4 Project Check SDK .......................................................................................... 19
4.1 Overview............................................................................................. 19
4.2 Scope ................................................................................................. 19
4.3 Usage ................................................................................................. 19
4.4 Debugging .......................................................................................... 22
4.5 Example rule ...................................................................................... 23
© Siemens AG 2020 All rights reserved

4.6 Hints and error handling ..................................................................... 24

5 Appendix .......................................................................................................... 26
5.1 Service and support ........................................................................... 26
5.2 Links and literature ............................................................................. 27
5.3 Change documentation ...................................................................... 27

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 3
 1 Introduction

1 Introduction
1.1 Overview
Code quality is a fundamental pillar in the software development, which is
encouraged by the help of standards, guidelines, suggestions, or "best practice"
examples. Checks, analyses, and tests can provide information about gaps, errors
or potential for optimization.
Table 1-1 Levels of the specifications
Specification Chief objective Quality Realization, tool
Programming style Comprehensibility Empirical Code review,
Style check
Programming Conformity Pragmatic Static code analysis,
technique Lint
Programming Efficiency Pragmatic Dynamic code analysis,
technique Profiling
Test cases Functionality Syntactic Function test,
Unit/integration test
Mathematical model Correctness, Semantic Formal verification,
completeness Model check
You can check TIA Portal projects automated or manually against specific rules
© Siemens AG 2020 All rights reserved

using this application "Project Check".

Siemens AG provides a rule set based on the "Programming style guide for
SIMATIC S7-1200 / S7-1500" \3\, which is already included.
You can export and evaluate the detailed results of the check in an Excel file or
XML file.
You can develop and provide further rule sets with the help of the included
"Project Check SDK" in the programming languages Visual Basic (.NET) or C#.
This means that even your complex rules can be implemented.
The focus of the Project Check is on the first level, the programming style, even
though this application can already check some – but not all – specifications for
programming techniques.

NOTE Since TIA Portal V16, there is the option package "TIA Portal Test Suite
Advanced". \8\
In V16, the integrated product contains a check against style guides and an
application test. The style rules are created in tabular form and the function tests
in text form in TIA Portal editors.

1.2 Mode of operation

The Project Check is a standalone Windows application, which can access an
existing, local TIA Portal project or also an already opened session of the
TIA Portal project server. It uses the programming interface "TIA Portal Openness"
to extract and process the project data and passes this project data to the rules for
checking. The rules produce results, which can be viewed and exported.
The Project Check offers two executable Windows applications:
1. The console application "Siemens.ProjectCheckConsole.exe" can be used for
automated processes, like an automatic check in the background.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 4
 1 Introduction

2. The desktop application "Siemens.ProjectCheck.exe" can be used for manual

checking.

NOTE You get additional information about using the console application via the
parameter "--help".

Before using the Project Check, ensure that your Windows user account is a
member of the Windows user group "Siemens TIA Openness" and that you have
rebooted the computer after changing the group membership. This group
membership permits you to execute Openness applications:
Figure 1-1 Computer management
© Siemens AG 2020 All rights reserved

A dialog of the Openness firewall will be prompted, if the Project Check tries to
access TIA Portal for the first time. Please acknowledge the access with "Yes to
all" to grant a permanent permission for this application to read out the project
data. If you acknowledge the dialog with "Yes" only, it will be prompted again for
the next project:
Figure 1-2 Openness firewall

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 5
 1 Introduction

1.3 Installation
Unzip the received archive \2\ into a local storage location for programs, like:
"C:\Program Files\Siemens\Automation\Project Check\".

NOTE For security reasons, it is recommended

• to install the application with administrative rights into the directory for
programs to avoid the dynamic loading of modules from the user space.
• to run the application with user rights only.

The rule sets are stored flat in the subdirectory "Rules" as program libraries. Other
directories or subdirectories are not observed by the application.

1.4 Compatibility
This application is usable for TIA Portal as of version V14 SP1 for all 64-bit
versions, which supply the long-term stable Openness libraries for V14 SP1, V15,
V15.1, or V16. These can also be newer TIA Portal versions.
TIA Portal and the option package "TIA Portal Openness" must be installed and
licensed.

NOTE If the application displays the error message "No supported TIA Portal
© Siemens AG 2020 All rights reserved

installation could be found" and both TIA Portal and the option package
"TIA Portal Openness" are installed, please perform a repair installation for
TIA Portal.
The application requires Microsoft .NET Framework Runtime 4.8. \6\, \7\

1.5 System properties

The application has been tested with the following configuration:
Table 1-2 Test configuration
Product Version
Microsoft Windows 10 Version 1607 (64-bit architecture)
Microsoft Office 2016
Microsoft .NET Framework Runtime 4.8
TIA Portal • V14 SP1 Update 9
• V15 Update 4
• V15.1 Update 4
• V16 Update 2
Installed TIA Portal software STEP7 Professional
Installed TIA Portal options TIA Portal Openness

NOTE It is not necessary to have Microsoft Office installed on the system. You can still
export the results and open the generated file on another computer.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 6
 2 Handling

2 Handling
2.1 Desktop application
Start the desktop application "Siemens.ProjectCheck.exe" via a double-click.

General
The application can be exited via the "X" in the upper right corner of the window.
The application can only be exited, if no action is executed.
In the lower area of the window, there is the "Activity log", which you can show via
a click at any time. You can follow the actions there. You can save, clear and hide
this log.

Figure 2-1 "Activity log"

© Siemens AG 2020 All rights reserved

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 7
 2 Handling

Start page
At the start page, you can see a list of already open TIA Portal projects. You can
refresh this list and click on an entry to check that project. Alternatively, you can
have another TIA Portal project opened via the button "Browse to another
TIA Portal project…".
You can go to help topics in the right lower area.

Figure 2-2 Start page

© Siemens AG 2020 All rights reserved

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 8
 2 Handling

Project page
After selecting or opening a project, a project tree is shown on the left area at the
project page. You can refresh the project tree, if you have made changes in the
TIA Portal project in the meantime. Additionally, you can expand and collapse the
whole project tree.
On the right area, you can see general project information.
You can define the content to be checked via the check boxes in the project tree.
You can save this selection (inclusion list or exclusion list) in a separate file and
load it for a repeated check via the buttons.
You are redirected to the start page via the buttons "Cancel" and "Back". The
connection to TIA Portal will be disposed and the project data will be reset.
You are redirected to the rule page via the button "Next". The button will be
enabled, if you have checked at least one object in the project tree.

Figure 2-3 Project page

© Siemens AG 2020 All rights reserved

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 9
 2 Handling

Rule page
After defining the content to be checked, a rule tree is shown at the rule page. You
can see all loaded rule sets with their categories and rules. You can expand and
collapse the whole rule tree.
Define the rules to be applied via the check boxes. You can save this selection
(inclusion list or exclusion list) in a separate file and load it for a repeated check via
the buttons.
You are redirected to the start page via the button "Cancel". The connection to
TIA Portal will be disposed. The project data and the rule selection will be reset.
You are redirected to the project page via the button "Back". The rule selection will
be reset.
The check will be started via the button "Check". The button will be enabled, if you
have ticked at least one rule in the rule tree. The check can take several minutes,
depending on the scope of the project and the rules. Afterwards, you are redirected
to the result page.

NOTE The check starts with the data extraction from the TIA Portal project. The
TIA Portal is exclusively locked by the Project Check during that process.

Figure 2-4 Rule page

© Siemens AG 2020 All rights reserved

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 10
 2 Handling

Result page
After completion of the check, the amount of errors, warnings and information is
shown in the upper area of the result page. Below, you see all results in the tab
"results", which you can filter.
You can go to the respective editor in TIA Portal via a click on the green arrow.
In the tab "Statistics", you can see the ten objects with the most errors and
warnings as well as the ten rules with the most errors and warnings.
You are redirected to the start page via the button "Cancel". The connection to
TIA Portal will be disposed. The project data, rule selection, and results will be
reset.
You are redirected to the rule page via the button "Back". The results will be reset.
You can export the results and statistics into an Excel file with several worksheets
or into an XML file for further processing via the button "Export". The generation
can take several seconds, depending on the scope.

Figure 2-5 Result page

© Siemens AG 2020 All rights reserved

NOTE The Excel file contains three worksheets: "Results", "Top 10 objects" and "Top
10 rules". The XML file contains "Results" only.
You can select the format in the "save" dialog.
All results are exported, regardless of the selected filter.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 11
 2 Handling

2.2 Console application

Start the console application "Siemens.ProjectCheckConsole.exe" in the Windows
Command Prompt or in the Windows PowerShell with the following parameters:
Table 2-1 Parameters of the console application
Shortcut Long version Required Description
-q --quiet No Disable the output of the "Activity log"
in the console
-l --logfile No Path for the log file
-p --project Yes Path to the TIA Portal project file
-r --report Yes Path(s) for the report file(s) (*.xml or
*.xlsx)
-s --filter-rules No Path to the rules filter file
-o --filter-project No Path to the project filter file
n/a --help No Show help
n/a --version No Show version

For example, a call in the Windows PowerShell can look like this. The call is made
in one single line:
.\Siemens.ProjectCheckConsole.exe
-p "D:\Projects\Project1\Project1.ap16"
© Siemens AG 2020 All rights reserved

-l "D:\Projects\Project1\UserFiles\ProjectCheck.log"
-r "D:\Projects\Project1\UserFiles\ProjectCheckReport.xml"
"D:\Projects\Project1\UserFiles\ProjectCheckReport.xlsx"

The console application uses the following exit codes:

Table 2-2 Exit codes of the console application
Exit code Meaning
0 The application has exited without errors.
1 The application has exited with an error.
In this context, "error" does not mean whether an error has been found in a
TIA Portal project during the check.
For an evaluation of the project errors, please analyze the results in the exported
file.

NOTE The Excel file contains three worksheets: "Results", "Top 10 objects" and "Top
10 rules". The XML file contains "Results" only.
All results are exported.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 12
 2 Handling

2.3 Scope
The Project Check can check the following objects of a TIA Portal project. Each
object provides certain properties described in the Project Check SDK.
• Project
• Group / folder
• PLC (since V16: with property "Simulatability")
• Software unit (since V16: available)
• Program block (without content for ProDiag; since V15: also with SimaticML for
SCL block and also LAD/FBD block containing SCL networks)
– Member of a block interface (since V15: also for LAD/FBD block containing
SCL networks)
– Child member of a member (only for Struct and array of Struct)
• Technology object (since V15: with opening editor; since V16: with SimaticML
for current TO versions)
• External source
• PLC tag table
– PLC tag
– PLC user constant
• PLC data type
© Siemens AG 2020 All rights reserved

– Member of a PLC data type

– Child member of a member (only for Struct and array of Struct)
• Force table (since V15.1: available)
– Entry of a force table (since V15.1: available)
• Watch table (since V15.1: available)
– Entry of a watch table (since V15.1: available)
• Master copy (without content)
• Library type of a program block
– Version of a program block (without content)
• Library type of a PLC data type
– Version of a PLC data type (without content)

NOTE The scope is limited by the scope of functions in the programming interface
"TIA Portal Openness" in the respective TIA Portal version.
System blocks, system data types, and system constants are skipped.
System members in a block interface are available and are marked with
"IsReadOnly".

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 13
 2 Handling

2.4 Hints and error handling

Keep your TIA Portal installation up to date by installing all updates.
You can use the "Activity log" in the desktop application to follow the actions.
You can have the "Activity log" displayed directly in the console application or log
into a separate file.
The Project Check can only access projects in TIA Portal, if all needed TIA Portal
packages, hardware support packages, and GSD files are installed and licensed
for the project.
All dialog windows must be closed in TIA Portal, so that the Project Check can
access the data. TIA Portal editors are not affected.
Compile all PLCs in the TIA Portal project before starting the check to get a
complete check. Only consistent data can be checked completely.
The Project Check supports TIA Portal projects with PLCs of the S7-1200 / S7-
1500 family. Other PLCs are skipped.
For knowhow protected program blocks, only the block interface can be read out.
The tree view of the TIA Portal project is inspired by TIA Portal, but only shows
essential information. For example, information about knowhow protection and
versioning are not displayed. The ordering may vary, too.
The node "Software units" is only displayed for supported PLCs.
© Siemens AG 2020 All rights reserved

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 14
 3 Rule set "Programming style guide for SIMATIC S7-1200 / S7-1500"

3 Rule set "Programming style guide for

SIMATIC S7-1200 / S7-1500"
The rules and recommendations from the "Programming style guide for
SIMATIC S7-1200 / S7-1500" \3\ have been implemented in a rule set with the
same name:
Table 3-1 Implemented rule set
Property Value
Implemented version V2.0
Program library for the rule set Siemens.ProgrammingStyleGuide.dll
A violation against a recommendation is shown as "Warning", a violation of a rule
as "Error", all passed or not applicable checks as "Info".
The following tables give an overview about the scope of implementation:

Table 3-2 Settings in TIA Portal

Nr. Description Note
ES001 User Interface Language "English" Not implemented. These rules
and recommendations are
ES002 Mnemonic "International"
used for TIA Portal settings.
ES003 Non-proportional font in editors These settings are
independent of the TIA Portal
© Siemens AG 2020 All rights reserved

ES004 Smart Indentation with two whitespaces project.

ES005 Symbolic representation of operands
ES006 IEC conformant programming
ES007 Explicit data access via HMI/ OPC UA/ Web
API
ES008 Automatic value evaluation (ENO) enabled
ES009 Automatic evaluation of Array boundaries

Table 3-3 Globalization

Nr. Description Note
GL001 Use consistent language Not implemented. It requires
grammar analysis.
GL002 Set editing and reference language to Implemented.
"English (US)"
GL003 Supply texts in all project languages Partially implemented. Texts
within the code are not
checked as it requires code
analysis.

Table 3-4 Nomenclature and Formatting

Nr. Description Note
NF001 Unique and consistent English identifiers Not implemented. It requires
grammar analysis.
NF002 Use meaningful comments and properties Partially implemented. Die
"Meaningfulness" cannot be
checked.
NF003 Document developer information Not implemented. There is no
fix format.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 15
 3 Rule set "Programming style guide for SIMATIC S7-1200 / S7-1500"

Nr. Description Note

NF004 Comply with prefixes and structure for Implemented.
libraries
NF005 Use PascalCasing for objects Implemented. The check is
performed without a dictionary.
NF006 Use camelCasing for code elements Implemented. The check is
performed without a dictionary.
NF007 Use prefixes Implemented.
NF008 Write identifier of constants in CAPITALS Implemented.
NF009 Limit the character set for identifiers Implemented.
NF010 Limit the length of identifiers Implemented.
NF011 Use one abbreviation per identifier only Not implemented. It requires
grammar analysis.
NF012 Initialize in the appropriate format Implemented.
NF013 Hide optional formal parameters Not implemented. There is no
access to this setting.
NF014 Format SCL code meaningfully Not implemented. It requires
code analysis.

Table 3-5 Reusability

Nr. Description Note
© Siemens AG 2020 All rights reserved

RU001 Provide blocks which can be simulated Implemented.

RU002 Version entirely with libraries Implemented.
RU003 Keep only released types in released Implemented.
projects
RU004 Use only local variables Implemented.
RU005 Use local symbolic constants Partially implemented. The
usage of global constants or
"magic numbers" is not
checked as it requires code
analysis.
RU006 Program fully symbolic Implemented.
RU007 Program independently from hardware Partially implemented. The
usage of system instructions is
not checked as it requires
code analysis.
RU008 Use templates Not implemented. There are
different templates, which can
be used differently or only
partially.

Table 3-6 Referencing objects (Allocation)

Nr. Description Note
AL001 Use multi-instances instead of single Implemented.
instances
AL002 Define array boundary from 0 to a constant Implemented.
value
AL003 Declare array parameter as ARRAY[*] Implemented.
AL004 Specify the required string length Implemented.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 16
 3 Rule set "Programming style guide for SIMATIC S7-1200 / S7-1500"

Table 3-7 Security

Nr. Description Note
SE001 Validate actual values Not implemented. It requires
code analysis.
SE002 Initialize temporary variables Not implemented. It requires
code analysis.
SE003 Handle ENO Partially implemented. The
attribute "Set ENO
automatically" is checked.
Code is not checked as it
requires code analysis.
SE004 Enable data access via HMI/ OPC UA/ Web Implemented. The desired
API selectively "selectivity" cannot be defined.
SE005 Evaluate error codes Not implemented. It requires
code analysis.
SE006 Write Error OB with evaluation logic Not implemented. It requires
code analysis.

Table 3-8 Design guidelines / architecture

Nr. Description Note
DA001 Structure and group a project/ library Not implemented. There is no
characteristic for "logical
© Siemens AG 2020 All rights reserved

units".
DA002 Use appropriate programming language Implemented.
DA003 Set/ evaluate block properties Implemented.
DA004 Use PLC data types Implemented. "Struct" in local
data is ignored, its usage is
not checked.
DA005 Exchange data only via formal parameters Not implemented. It requires
code analysis.
DA006 Access static variables from within the block Not implemented. It requires
only code analysis.
DA007 Group formal parameters Implemented.
DA008 Write output parameters only once Not implemented. It requires
code analysis.
DA009 Keep used code only Partially implemented. It
requires code analysis. The
existence of external sources
is checked only.
DA010 Develop asynchronous blocks according to Not implemented. The rule is
PLCopen only a general guideline.
DA011 Continuous asynchronous execution with Partially implemented. Only
"enable" blocks with an input "enable"
are checked.
DA012 Single asynchronous execution with Partially implemented. Only
"execute" blocks with an input "execute"
are checked.
DA013 Report status/ errors via "status"/ "error" Partially implemented. Only
blocks with an output "error" or
"status" are checked.
DA014 Use standardized value ranges for "status" Not implemented. There is no
characteristic for
"correctness".

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 17
 3 Rule set "Programming style guide for SIMATIC S7-1200 / S7-1500"

Nr. Description Note

DA015 Pass underlying information Not implemented. The
diagnostics structure is not fix
defined.
DA016 Use CASE instruction instead of ELSIF Not implemented. It requires
branches code analysis.
DA017 Create ELSE branch in CASE instructions Not implemented. It requires
code analysis.
DA018 Avoid Jump and Label Not implemented. It requires
code analysis.

Table 3-9 Performance

Nr. Description Note
PE001 Deactivate "Create extended status info" Not implemented. There is no
access to this setting.
PE002 Avoid "Set in IDB" Implemented.
PE003 Pass structured parameters as reference Implemented.
PE004 Avoid formal parameter with Variant Implemented.
PE005 Avoid formal parameter "mode" Implemented.
PE006 Prefer temporary variables Not implemented. It requires
code analysis.
© Siemens AG 2020 All rights reserved

PE007 Declare important test variables as static Not implemented. It requires

code analysis. There is no
characteristic for "importance".
PE008 Declare control/ index variables as "DInt" Not implemented. It requires
code analysis.
PE009 Avoid multiple access using the same index Not implemented. It requires
code analysis.
PE010 Use slice access instead of masking Not implemented. It requires
code analysis.
PE011 Simplify IF/ ELSE instructions Not implemented. It requires
code analysis.
PE012 Sort IF/ ELSIF branches according to Not implemented. It requires
expectation code analysis. There is no
characteristic for "expectation".
PE013 Avoid memory intense instructions Not implemented. It requires
code analysis.
PE014 Avoid runtime intense instructions Not implemented. It requires
code analysis.
PE015 Use of SCL/ LAD/ FBD for time critical Implemented.
applications
PE016 Check the setting for minimum cycle time Implemented.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 18
 4 Project Check SDK

4 Project Check SDK

4.1 Overview
SDK means "Software Development Kit". The Project Check SDK provides a
program library, which is made for creating own rule sets.

NOTE Experience in developing Microsoft Windows program libraries with the

Microsoft .NET Framework is required.

The SDK is a part of the application example. The SDK files are located in the
same directory as the executable applications.
Table 4-1 Properties of the Project Check SDK
Property Value
Name Siemens.Applications.TiaPortal.ProjectCheck.Sdk.dll
.NET version 4.8
Assembly file version 3.0.0
Assembly version 3.0.0
Public token 1208d84b9f643f11
XML documentation Siemens.Applications.TiaPortal.ProjectCheck.Sdk.xml
(intellisense)
© Siemens AG 2020 All rights reserved

PDF documentation Siemens.Applications.TiaPortal.ProjectCheck.Sdk.pdf

(interfaces, classes)

4.2 Scope
See also chapters 2.3.
Basically, the Project Check SDK provides the data as read-only. Additionally, the
properties SimaticML and Source are provided for consistent objects in several
classes, if the prepared properties are not enough for an own rule.

4.3 Usage
A rule set is provided as a program library. You can develop such a program library
with the help of the Project Check SDK.

NOTE • You map exactly one rule set in one program library.
• The maximum size of a program library is 10 MiB.
• A rule set can consist of several rules.
• A rule can check several different objects.

To do so, proceed as follows:

1. Start Microsoft Visual Studio (Version 2015 update 3 or newer)
2. Create a new project of type "Class Library" from the category "Visual C# >
Windows > Classic Desktop" and set the .NET Version to ".NET Framework
4.8".

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 19
 4 Project Check SDK

Figure 4-1 Creating a new Visual Studio project

3. In your project, add a reference to the Project Check SDK, which is located in
your installation directory. Set the property "Copy Local" to "False", because it
is not necessary to copy the SDK.
Figure 4-2 Reference to the SDK
© Siemens AG 2020 All rights reserved

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 20
 4 Project Check SDK

4. Open the file "AssemblyInfo.cs" below "Properties" and provide at least the
following attributes:
[assembly: AssemblyDescription("My rule set")]
[assembly: AssemblyCompany("My Company")]
[assembly: AssemblyCopyright("Copyright © My Company 2020")]
[assembly: AssemblyFileVersion("0.1.0")]
[assembly: AssemblyVersion("0.1.0")]
These attributes are shown as information about the rule set to the end user in
the graphical user interface of the Project Check.
5. Additionally, provide the following attributes in the file "AssemblyInfo.cs" to
specify the required code access security (CAS):
Either only the attribute
[assembly: SecurityTransparent]
or the following both attributes
[assembly: AllowPartiallyTrustedCallers]
[assembly: SecurityRules(SecurityRuleSet.Level2)]
You can find technical details about that at Microsoft Docs, "Security-
transparent code, level 2" \4\.
6. Create a new class, which is marked as public sealed.
You can integrate the following namespaces:
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Enums;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Interfaces;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Interfaces.User;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Models;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Models.User;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Rules;
© Siemens AG 2020 All rights reserved

7. Inherit the generic, abstract class BaseRule<T> to your class. T has to be your
own, same class. Implement the required parameterless constructor by calling
the base constructor:
public sealed class MyRule : BaseRule<MyRule>
{
public MyRule() : base("MR901", "My Rule", "My Category")
{
}
}
8. Override all Check() methods for the objects, which you want to check in your
rule. Delete the call of base.Check(item), if it has been added automatically:
public override void Check(Project item)
{
// TODO: Add check logic here
}
9. Add at least one result to the collection in every overwritten Check() method.
The Results collection is provided by the base class:
Results.Add(Level.Info, item, DefaultMessage.Passed);
10. Add a separate class for each additional rule.
11. Compile the rule set and copy the program library into the subdirectory "Rules"
of the Project Check.

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 21
 4 Project Check SDK

4.4 Debugging
The precondition is, that you already have developed an own rule set and you have
inserted its program library into the subdirectory "Rules" of the Project Check.
1. Open your rule set project in Microsoft Visual Studio.
2. Set breakpoints at all desired locations in your rule set project.
3. Start the desktop application of the Project Check.
4. Attach the debugger to the Project Check process via Visual Studio > Debug >
"Attach to Process…".
5. Select a TIA Portal project in the Project Check and select the content to be
checked.
6. When clicking on "Next", the program libraries of the rule sets are loaded, and
the constructors are called.
7. When clicking on "Check", the Check() methods of the rules are called.
8. You have to restart the application, if you exchange the program libraries.

NOTE Debugger.Launch() is not available, because this call needs critical permissions
to execute "unmanaged code".
It is not possible to inspect the parameter item during debugging. You will see
one of the following values instead, depending on your Visual Studio setting:
• Obtaining the runtime type of a transparent proxy is not supported
© Siemens AG 2020 All rights reserved

in this context.
• {System.Runtime.Remoting.Proxies.__TransparentProxy}

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 22
 4 Project Check SDK

4.5 Example rule

Requirements to this example
• The name of all members of a block interface must be shorter than 24
characters.
• In the good case, only one single information "Check passed." is added for a
program block.
• A warning will be added for a program block, if the block interface is not
available.
• An error is added for each violation in the block interface of the program block.

Implementation of the example

using System.Collections.Generic;
using System.Linq;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Models;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Models.User;
using Siemens.Applications.TiaPortal.ProjectCheck.Sdk.Rules;
namespace MyRuleSet
{
public sealed class MyRule : BaseRule<MyRule>
{
public MyRule() : base("MR901", "My Rule", "My Category")
{
}
public override void Check(ProgramBlock item)
© Siemens AG 2020 All rights reserved

{
if (item.InterfaceMembers == null)
{
// The program block may be not consistent,
// so the block interface may not be available.
Results.Add(Level.Warning, item, "The block interface is not available.");
}
else if (CheckInterfaceMembers(item, item.InterfaceMembers.Where(e =>
e.IsReadOnly != true)))
{
// All interface members have passed the check.
Results.Add(Level.Info, item, DefaultMessage.Passed);
}
}
private bool CheckInterfaceMembers(ProgramBlock item,
IEnumerable<ProgramBlockInterfaceMember> members)
{
var isSuccessful = true;
foreach (var member in members)
{
// Check the name of the current interface member
if (member.Name.Length > 24)
{
isSuccessful = false;
Results.Add(Level.Error, item,
$"The name of the interface member {member.Name} " +
$"is too long. It has {member.Name.Length} characters.");
}
// Check also all child interface members
if (member.Members != null && !CheckInterfaceMembers(item, member.Members))
{
isSuccessful = false;
}
}
return isSuccessful;
}
}
}

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 23
 4 Project Check SDK

4.6 Hints and error handling

Producing results
• A single call of a Check() method must create at least one Result.
• In the good case, a call of the Check() method adds exactly one Result with
Level.Info.
• A call of the Check() method adds at least one Result with Level.Warning or
Level.Error, but no Level.Info.
• If a call of the Check() method cannot perform a complete check, e.g. because
the object is not consistent, a Result with Level.Warning has to be added.
• Default texts for common result messages are provided in the class
DefaultMessage, for example DefaultMessage.Passed.
• Do not print the type, name or path of the object in Result by yourself. This
information is automatically added; because of this the checked object always
has to be passed when adding a Result.
• Print the type, name or path only for child elements of the object in Result, so
that the end user can locate the violation within the object faster.

NOTE Because the checks in the Project Check are performed in multiple threads in
parallel, you must expect, that two subsequently added results will not
necessarily be displayed directly next to each other in the overall result list.
© Siemens AG 2020 All rights reserved

Sandbox
The program libraries for the rule sets are loaded in a sandbox with restricted
permissions. Thus, the security risk by executing foreign code is mitigated for the
end user.
That is the reason, why it is also not possible to directly access the Openness
object model within a rule set, but only via the provided abstractions.
The following permissions are available in a rule set:
• SecurityPermission
– SecurityPermissionFlag.Execution
• ReflectionPermission
– ReflectionPermissionFlag.MemberAccess
• FileIOPermission
– FileIOPermissionAccess.Read
– FileIOPermissionAccess.PathDiscovery
– Only for the directory of the Project Check and its subdirectories

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 24
 4 Project Check SDK

Parallelism, multi-threading
Each Check() method must be able to be executed standalone. Instance data
should be avoided. Private (and ideally static) methods can be used to avoid
duplicated code. The reason for this is, that the checks are performed in parallel in
multiple threads and that the ordering is random.

Error handling
Each Check() method is automatically wrapped with an error handling. Thus, no
general exceptions must be caught inside of the method via try {…}.
Additionally, the check routine ensures, that the parameter item of the Check()
method is not null when called. Thus, the Microsoft Design rule CA1062 \5\ can be
ignored:
[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design",
"CA1062:Validate arguments of public methods", MessageId = "0")]
However, some properties of item can be null, e. g. if the data is not available. So,
these must be validated.

JetBrains ReSharper
The classes and interfaces in the Project Check SDK contain the attributes
[CanBeNull] and [NotNull] from the namespace JetBrains.Annotations.
© Siemens AG 2020 All rights reserved

Thus, you get the following hints during development of the rule set:
• An overseen NullReferenceException
(ReSharper: "Possible 'System.NullReferenceException'")
• Unnecessary comparisons against null
(ReSharper: "Expression is always true")

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 25
 5 Appendix

5 Appendix
5.1 Service and support
Industry Online Support
Do you have any questions or need assistance?
Siemens Industry Online Support offers round the clock access to our entire
service and support know-how and portfolio.
The Industry Online Support is the central address for information about our
products, solutions and services.
Product information, manuals, downloads, FAQs, application examples and videos
– all information is accessible with just a few mouse clicks:
support.industry.siemens.com

Technical Support
The Technical Support of Siemens Industry provides you fast and competent
support regarding all technical queries with numerous tailor-made offers
– ranging from basic support to individual support contracts. Please send queries
to Technical Support via Web form:
www.siemens.com/industry/supportrequest
© Siemens AG 2020 All rights reserved

SITRAIN – Training for Industry

We support you with our globally available training courses for industry with
practical experience, innovative learning methods and a concept that’s tailored to
the customer’s specific needs.
For more information on our offered trainings and courses, as well as their
locations and dates, refer to our web page:
www.siemens.com/sitrain

Service offer
Our range of services includes the following:
• Plant data services
• Spare parts services
• Repair services
• On-site and maintenance services
• Retrofitting and modernization services
• Service programs and contracts
You can find detailed information on our range of services in the service catalog
web page:
support.industry.siemens.com/cs/sc

Industry Online Support app

You will receive optimum support wherever you are with the "Siemens Industry
Online Support" app. The app is available for iOS and Android:
support.industry.siemens.com/cs/ww/en/sc/2067

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 26
 5 Appendix

5.2 Links and literature

Table 5-1 Topics
No. Topic
\1\ Siemens Industry Online Support
https://support.industry.siemens.com
\2\ Link to this entry page of this application example
https://support.industry.siemens.com/cs/ww/en/view/109741418
\3\ Programming style guide for SIMATIC S7-1200 / S7-1500
https://support.industry.siemens.com/cs/ww/en/view/81318674
\4\ Microsoft Docs: Security-transparent code, level 2
https://docs.microsoft.com/dotnet/framework/misc/security-transparent-code-level-2
\5\ Microsoft Design, CA1062: Validate arguments of public methods
http://msdn.microsoft.com/library/ms182182.aspx
\6\ Microsoft Docs: .NET Framework system requirements
https://docs.microsoft.com/dotnet/framework/get-started/system-requirements
\7\ Microsoft: Download .NET Framework 4.8
https://dotnet.microsoft.com/download/dotnet-framework/net48
\8\ Delivery release TIA Portal Test Suite Advanced V16
https://support.industry.siemens.com/cs/ww/en/view/109775720
© Siemens AG 2020 All rights reserved

5.3 Change documentation

Table 5-2 Versions
Version Date Modifications
V1.0.0 10/2016 First version,
Name: "Programming style guide checker"
V1.1.0 11/2016 Version for TIA Portal V14
V1.1.1 04/2017 Version for TIA Portal V14 SP1
V1.5.0 04/2018 Version for TIA Portal V15
V1.5.1 09/2018 Version for TIA Portal V15.1
V2.0.0 n/a Enhancements
V3.0.0 08/2020 Complete rework of the application example
• New name: "Project Check"
• One tool for multiple TIA Portal versions
• Easier creation of custom rulesets using the Project
Check SDK (without Openness)
• Save the results as Excel file or XML file
• More TIA Portal objects can be checked
• Selecting/filtering TIA Portal objects and rules
• Automated execution

Project Check
Entry-ID: 109741418, V3.0.0, 08/2020 27