S4 Basics: How to create an Interface Component

This article describes how a new plug-in component is created. It is assumed that you use Microsoft Visual Studio 2005, 2008, or 2010.

Step by step

  1. Open Visual Studio and load (or create) the solution that should contain the interface component.
  2. Add a new project to the solution, using the "Class Library" template.
  3. Edit the AssemblyInfo.cs file in your project like that:
using System.Reflection;
using System.Runtime.CompilerServices;

[assembly: AssemblyTitle("Common Icons")]
[assembly: AssemblyDescription("Provides access to commonly used icons within the framework")]
[assembly: AssemblyCompany("3S-Smart Software Solutions GmbH")]
[assembly: AssemblyProduct("CoDeSys")]
[assembly: AssemblyCopyright("Copyright © 1994-2010 by 3S-Smart Software Solutions GmbH. All rights reserved.")]
[assembly: AssemblyVersion("3.4.0.0")]

The assembly version is essential because with this information the plug-in installer decides whether to overwrite an existing interface component or not. It is not allowed to use an asterisk (*) in the version specification.

4. Finished! Once you reference this interface component from one of your plug-in components, it will be automatically installed to the correct location in your system.

Important notes

Compatibility

Take care about compatibility. It is a core rule in Automation Platform that interfaces that are released (i.e. deployed into a production environment) must not be changed any more. Otherwise plug-ins built against a previous version of the interface will not be executable any more. However, it is of course allowed to define new interfaces in the same assembly that extend existing interfaces. It is highly recommended that you use the [ReleasedInterface] attribute to make use of some automatic checks.

A development timeline could look like this:

  1. Create a new interface ISample.
    public interface ISample { }
  2. While you are developing, you may change the interface as you like. In other words: As long as you are able to recompile all dependencies of your interface, changes are allowed.

  3. Once you make a release on any plug-in component that uses an interface, that interface must be released, i.e. it must not change any more in the future. You can mark that interface with the [ReleasedInterface] attribute.

    [ReleasedInterface] public interface ISample { } 

    This attribute has got two advantages: first the developer sees quickly whether he is allowed to modify the interface or not, second the plug-in installer can check whether an existing interface would be overwritten by an incompatible one, then refusing the installation.

  4. If you need to improve your interface, you can start a new one at any time, like so:

    [ReleasedInterface] public interface ISample { } public interface ISample2 : ISample { } 

    The new interface can then be changed at your will until the next production release. Of course, any code that calls the interface must check whether a particular instance implements that interface, like so:

    ISample inst; if (inst is ISample2) ((ISample2)inst).CallNewFunction(); else inst.DoSomethingElseOrReportAnError(); 

References to other assemblies

It is not allowed to add a reference to a plug-in component or to a GAC component to your project. The tools IPM and IPMCLI will refuse to install a plug-in component that statically references an interface component which violates against this rule.

Why is it forbidden to use types of a GAC component within your interfaces? The reason is because types from GAC components have got a strong name, i.e. the internal type name contains version information. If you now change the reference to another version of the same GAC component, all internal type names change and make the interface completely incompatible to the previous version, so the aforementioned compatibility rule is violated.

Interface components for interfaces

It is highly recommended that interface components do not contain any implementation code. Implementation code should be versioned and therefore be part of a plug-in component. Exceptions to that practice are classes that are mere data containers, i.e. EventArgs or things like that.