Functionality of the C# API

This chapter gives an overview of the different functional possibilities of the C# API:

Multithreading

The WinCC OA C# manager API can be used in a multithreaded environment. This means that the C# client application can use multiple threads to request and process data from WinCC OA. The communication with WinCC OA and the access to the DP Identifications is internally automatically serialized to one single communication thread.

Note:

Note that the C# manager API only provides the possibility to develop thread safe C# applications. It is, however, in the responsibility of the user / developer to develop proper applications.

Asynchronous and Synchronous function calls

WinCC OA functions of the C# manager API are provided in a synchronous and in an asynchronous version where reasonable (it makes, for example, no sense to provide a synchronous dpConnect(), but it makes perfectly sense for a dpGet()).

Following patterns/syntax will be provided for asynchronous function access:

  • EAP (Event based Asynchronous Pattern) for publish-subscribe functions (e.g.: dpConnect())

  • TAP (Task based Asynchronous Pattern) for request-response functions (e.g.: dpGet())

Note:

If you need high performance in your C# application, the asynchronous versions of the functions should be used. If you focus on simplicity on the other hand, use the synchronous versions.

Manager Events

With the help of the C# manager API it is possible to subscribe to important system and data point events. For example C# Events for the following situations are provided:

  • Manager connection state changed - triggered e.g. when lost connection to a WinCC OA project

  • Redu Switch (triggered when a redundancy switch occurs)

    - Redu switch to active

    - Redu switch to passive

  • Connection to Dist system (triggered when disconnected/connected to a remote system)

    - Dist system connected

    - Dist system disconnected

  • Changes in the Data model

    - DP created, deleted, renamed

    - DP Alias changed, deleted

    - DP Description changed, deleted

Use of native C# data types

The C# manager API automatically converts between native C# data types or C# classes and WinCC OA data types when setting or querying WinCC OA values. This means that you can use native C# data types (e.g.: DateTime) and classes in your code. Internally the following mapping table applies:

WinCC OA data type C# data type
FLOAT_VAR double
INTEGER_VAR int
UINTEGER_VAR Uint
LONG_VAR Long
ULONG_VAR Ulong
BIT_VAR Bool
TEXT_VAR String
CHAR_VAR

Char

CAUTION: A C# char has another value range than the WinCC OA CharVar. Therefore, the permitted max and min values are defined as constant byte members “MinCharValue” and “MaxCharValue” in the class OaVariant.
BLOB_VAR byte[]
TIME_VAR

DateTime

CAUTION: A DateTime in C# has an other value range than the WinCC OA TimeVar. Therefore, the allowed max and min values in UTC time are defined as static DateTime members “MinTimeValue” and “MaxTimeValue” in the class OaVariant
BIT32_VAR Own C# class: Bit32
BIT64_VAR Own C# class: bit64
LANGTEXT_VAR Own C# class: LocalizedString
DPIDENTIFIER_VAR Own C# class OaDpIdentifier

ANYTYPE_VAR

MIXED_VAR

 is automatically converted into the real (contained) data type
DYNXXX_VAR IEnumarable<> of the output type

C# API Classes

The C# API contains separate classes in order to access the different data models of a WinCC OA project.

  • ProcessValues – Access to current process values and configuration data

    e.g.: query or change online values of WinCC OA data points, etc.

  • Alerts – Access to current alerts

    e.g.: query current alerts and alert values, etc.

  • ValueHistory – access to historical process values

    e.g.: query historical values of data points, etc.

  • AlertHistory – Access to historical alert data

    e.g.: query historical alerts, etc.

  • ProcessModel – Read/Write/Modify the data model of a project

    e.g.: create, delete, rename data points, etc.

  • TypeModel – DpType related functionality

    e.g.: Return all data points of a given DpType, etc.

  • PlantModel – CNS related functionality

    e.g.: create and modify CNS views and trees, etc.

  • ProjectEnvironment - Provides access to the configuration of the current project

    e.g.: get the data and event hosts and ports, etc.

  • RuntimeSystem - Provides access to runtime and system information

    e.g.: get the local system name and ID as well as the connected systems, current project languages, etc.

Class and Function Documentation

The following C# Online Help provides a rough overview of the functionality of the C# manager API. You can find a detailed class and function documentation for the WinCC OA C# API in the “api/csharp_docu” directory of the

< wincc_oa_path>/api/Csharp_docu/index.html. This is a HTML based documentation. To open the documentation, open the index.html in a Web Browser.

For how to install the C# API. See chapter Installation for more information.