App validation rules

This article covers the following topics:

App validation rules introduction
App validation rules

App validation rules introduction

Before an App can be validated, it has to pass various tests. These tests ensure the quality, performance and stability of ETS. The test results are reported to the developer when an App version is uploaded in for validation. (see App validation)

The checks are divided into 2 different severities:

Error: These tests are unambiguous. Any failed test automatically prevents the validation of the App.

Warning: These tests indicate there might be a violation of rules. The App has to be inspected manually. If such a manual inspection shows the rule is not violated, the App can be validated. Otherwise, if the rule is violated, the validation is denied.

Since an App may contain additional assemblies, like a logging component or a zip assembly, the checks must adjust to that. Some rules that must be followed strictly by the App itself can be warnings for some other assemblies. For example, while the App must be compiled against .NET framework 4.0, third party components may be compiled against a different .NET framework. Otherwise, the use of, e.g., log4net would not be possible at all. On the other hand, loosening the strictness of the rules for additional assemblies too much, is not an option since it could invite developers to outsource problematic code to those additional assemblies.

The solution for this problem is to split the assembly checks into 2 runs:

All assemblies from the App developer itself must follow the strict interpretation of the rules. This ensures that the App itself is implemented according to the strict rules, as well as any component from the same developer.

In a second run, all assemblies from third party developers are checked. For those assemblies, some rules are less strictly checked, since the App developer has little chance to influence the implementation of those assemblies. Those less strictly handled rules are reported as warnings and have to be reviewed manually before granting the validation. Nonetheless, some rules remain strict, e.g. the usage of direct bus access is forbidden in any way.

The list of rules which every App has to follow are described below. In addition, a short description how the developer can avoid or solve the problem is provided, too. The severity is provided for both cases: The strict version (App developer assemblies) and the weaker version (third party developer assemblies)

Automatically checked rules

Missing strong name
More than one ETS AddIn found
Starting external process
Usage of unmanaged code
Usage of prohibited KNX assemblies
App instance cannot be created
Creation of App instance too slow
Direct connection to KNX bus
App file too big
Missing English help file
.Net runtime too old
App has no version
App attribute has a different version as specified in assembly version
Container must contain valid manifest file
Container may not contain SDK assemblies
Usage of non-official SDK version
SQL connection detected
Usage of suspect namespaces detected
Missing English language support
Unexpected App-ID
Invalid DCA Manufacturer ID
DCAs shall not use the UI App feature
DCA must support x64
App uses components that are used by ETS5 in a different version
The app assembly, as specified in the AddInAssembly attribute in the manifest file, was not found

ID	Name	Severity for developer	Severity 3rd party developer	Description	Solution
1	Missing strong name	Error	Error	Every .Net assembly within a etsapp container must be signed with a strong name, to prevent ambiguities.	Add a strong name key (snk file) to the solution.
2	More than one ETS AddIn found	Error	Error	Each etsapp container may only contain exactly one class inheriting from IEts4Addin and having the System.AddIn.AddInAttribute, or in other words: In every etsapp container, there may be only one ETS app.	Remove all other classes that inherit from IEts4App from the etsapp.
3	Starting external process	Error	Error	The App may not start an external process.	Remove the code that starts the external process.
4	Usage of unmanaged code.	Warning	Warning	The App uses calls to native components (DLLImport). This will lead to a manual inspection.	If the manual inspection reveals illegal use of unmanaged code, remove those usages.
5	Usage of prohibited KNX assemblies	Error	Error	References to KNX components are only allowed if they belong to SDK, i.e. Knx.Ets.SDK.*, Knx.Ets.CommonTypes, Knx.Ets.CommonResources are allowed. Any other KNX references are prohibited. References to .Net framework or own assemblies are allowed.	Remove all usages of the prohibited namespaces.
6	App instance cannot be created	Error	n.a. - The rule is checked for the App, not for each assembly.	When creating an instance of the App, no exception may be thrown.	Solve the problem that throws the exception.
7	Creation of App instance too slow	Error	n.a. - The rule is checked for the App, not for each assembly.	The creation of an instance of the App may not take longer than 5 seconds. This shall limit the App's negative impact on the overall ETS5 performance.	Identify the reason for the performance problem, change the implementation, so that the instance can be created within less than 5 seconds.
8	Direct connection to KNX bus.	Error	Error	Falcon connections are not allowed. No App is allowed to provide a direct connection to the KNX bus.	Remove all usages of direct access to KNX bus.
9	App file too big	Error	n.a. - The rule is checked for the etsapp, not for each assembly.	The maximum size of the etsapp container is 100 MB.	Solution: Reduce the file size, e.g. remove additional files, like pdf documents, videos or pictures, or reduce their size.
10	Missing English help file	Error	n.a. - The rule is checked for the etsapp, not for each assembly	At least one English compiled HTML help file (*.chm) must be provided.	Add an English compiled HTML help file to the etsapp.
11	.NET runtime too old	Error	Warning	All assemblies in the etsapp container must be built with .NET runtime 4.0. Older versions are not supported.	Rebuild the App with target framework .NET Framework 4.
12	App has no version	Error	n.a. - The rule is checked for the App, not for each assembly	The App must have a version number. This version will be used to identify available updates and/or help minimize work in support cases.	Rebuild the App with a specified file version.
13	App attribute has a different version as specified in assembly version.	Error	n.a. - The rule is checked for the App, not for each assembly	The App version and assembly version (App DLL) must be the same number. This version will be used to identify available updates and/or help minimize work in support cases.	Rebuild the App with a specified file version or assembly version.
14	Container must contain valid manifest file	Error	n.a. - The rule is checked for the App, not for each assembly.	Each ETS-App container must contain a valid manifest file.	Add a valid manifest file to the container.
15	Container may not contain SDK assemblies	Error	n.a. - The rule is checked for the App, not for each assembly.	The ETS-App container cannot contain any assembly from the ETS-SDK.	Remove any SDK assembly from the container.
16	Usage of non-official SDK version	Error	n.a. - The rule is checked for the App, not for each assembly.	It is not allowed to publish ETS-App containers that were build with an unreleased version of the ETS-SDK.	Re-build the App by referencing only files from released SDK versions.
17	SQL connection detected	Warning	Warning	If the assembly uses the SQL namespace (System.Data.SqlClient), a message is reported. This will lead to a manual inspection. If the SQL namespace, for example, is used to import data from an access database, this is allowed. Any attempt to access the ETS4 database without the SDK ObjectModel, either reading or writing, is prohibited.	If the manual inspection reveals illegal use of SQL namespace, remove those usages.
18	Usage of suspect namespaces detected	Warning	Warning	The usage of the namespaces System.Net.*, System.Data.Sql and System.Web results in a notification. A manual inspection has to check, whether these namespaces are used in a way that is in accordance with the etsapp rules. If not, the validation is denied.	If the manual inspection reveals illegal use of those suspect namespaces, remove those usages.
19	Missing English language support	Warning	n.a. - The rule is checked for the App, not for each assembly.	If the App provides support for multiple languages, English has to be among those supported languages. The check searches for an English localization for the App. If none is found, it has to be manually inspected, whether the neutral texts are already English.	Add support of English language.
20	Unexpected App-ID	Error	n.a. - The rule is checked for the App, not for each assembly.	The App-ID that is returned by the AddIn instance has to be the same as in the AddIn manifest file.	Use the same App-ID in the AddIn class and in the manifest file.
21	Invalid DCA Manufacturer ID	Error	n.a. - The rule is checked for the App, not for each assembly.	Manufacturer ID in DeviceConfiguration does not match manufacturer ID of AddIn.	Use the same manufacturer ID for App-ID and application program IDs.
22	DCAs may not use UI App feature	Error	n.a. - The rule is checked for the App, not for each assembly.	A DCA may not use the following features: Return an AddIn UI Subscribe to the ProjectOpening event Subscribe to the ProjectClosing event Set the SingleInstance attribute to true Implement the IMonitorAddIn interface	Do not use AddIn features in your DCA.
23	DCA must support x64	Error	n.a. - The rule is checked for the App, not for each assembly.	Any DCA must support x64, so that the ETS is not required to run in Compatibility mode.	Built your app to support x64, and set the Is64BitCompatible in the manifest to true.
24	App uses components that are used by ETS5 in a different version	Warning	n.a. - The rule is checked for the app, not for each assembly.	The ETS uses a component that is also used by the app, but in a different version	To avoid any possible incompatibility issues, use the same component version as the ETS
25	The app assembly, as specified in the AddInAssembly attribute in the manifest file, was not found	Error	n.a. - The rule is checked for the app, not for each assembly	The app assembly was not found	Make sure that the app assembly (indicated in the manifest file) exists

Rules that have to be confirmed formally

These rules have to be confirmed manually by the developers, since automatic verification is not possible.

If the developer violates any of the rules (either those automatically verified or these formally confirmed), the validation will be denied. If violation of any of the rules is noticed after validation, the validation can be revoked.

Name	Description	Solution
Updates possible only via MyKNX	The App may not have an own update mechanism. Updates for an App are only available via KNX OLT. This prevents the distribution of unvalidated Apps.	Remove any mechanism that is used to update the App bypassing the KNX OLT.
No SQL connections to ETS4 database	No App is allowed to access the database directly.	Remove any mechanism that accesses the ETS4 database directly.
Apps may not persist data in the filesystem	Project Related Data: The inclusion of project-related data within AddInData is essential. This data comprises all elements crucial for the project's functionality and integrity. Without it, the project would be incomplete and dysfunctional. The primary goal is to prevent critical failures, like those encountered with import/export handlers of ETS3 plug-ins. By centralizing project-related data in AddInData, ensures the project remains stable and operational. Non-Project Related Data: This includes user-related or temporary data that should be kept separate from project data. Placing such data within the project data or App installation folder can compromise the project's integrity, potentially breaking its signature.	Remove all mechanisms that store data directly in the file system and replace them with the usage of the project's AppData.
Apps may not run in fullscreen mode	An app may not hide the ETS window and act as the main application. The ETS must always be recognizable as the main application.	Remove any code that lets the App act as the main application.
App must either be responsive or indicate busy status	If the app performs a time consuming operation, which causes the ETS to be unresponsive, the app must display a progress or a busy indicator	Implement a progress indicator for time consuming operations.
The App must not close unexpectedly.	The App must react to exceptions by providing a user-friendly error message. After displaying the message, the App must continue to run. Generic or insufficient error messages are not accepted, as well as unexpected closure of the application after unhandled exceptions.	Implement a correct error handling that displays user-friendly messages in every situation. Ensure no unhandled exception can crash the App.

Search

ETS App development