UA SDK for .NET

UA SDK 1.00.132 Readme
October 28, 2007

Overview

The UA SDK is a set of interfaces, libraries and executables that allow developers to quickly create UA applications with the .NET programming environment. The SDK includes:

Implementations of the XML Web Services and UA Native Binary stack profiles;
Server and Client development toolkits;
Sample Applications;
A wrapper for COM-DA Servers (DA 2.05a and DA3.00);
A Diagnostics Client Application;
Local Discovery Server;

The sample applications are available with source code. The stack and development toolkits are available only as binaries.

Release Notes

This release of the SDK supports the core specification (Parts 1 though Part 6). It also has support for Part 8, 9, 10 and 12.

The key changes in this release are:

ANSI C and C# implementations of the UA TCP protocol (including security);
Local Discovery Server;
Diagnostic Client;
Binaries installer no longer requires IIS;
Various bug fixes and code clean up;

Known Issues

This release does not incorporate a number of changes to the specification (i.e. any changes approved after September 15th, 2007).

This release is a stable build that can be used for interoperability testing between .NET and C/C++ applications.

Installation

The SDK requires the .NET 3.0 runtime. It should run on any Microsoft operating system that supports the .NET 3.0 runtime. It has been tested with Windows XP at this time.

The Binaries installer requires that the OPC Core Components Redistributable be installed first. Note that this package is installed by many OPC applications.

The SDK will install on Vista, however, the UAC (User Access Control) must be turned off to install the application certificates.

If the SDK installer does not run on Vista then you must turn on IIS6 compatibility mode. You form the 'Turn windows features on or off' dialog and check the IIS6 Management components.

The SDK also requires that IIS be installed. If IIS is installed after installing the .NET runtime then it may be necessary to run the following command in a command shell:

%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\aspnet_regiis.exe –r

Building the sample applications requires the Windows SDK.

Developers using Visual Studio 2005 should install Service Pack 1 and the .NET 3.0 extensions.

The SDK is distributed as a ZIP file that contains a program called setup.exe and an MSI file. On Vista you must unzip the files into their own directory and run the setup.exe. Trying to run the MSI directly will not work.

Using the COM-DA wrapper requires a the COM DA 3.00 Sample Servers. These can be downloaded from the OPC Foundation website here.

Configuration

The sample applications require application instance certificates which must be installed in the local machine certificate store. The install program placed a batch file in the Programs Menu under "OPC Foundation | UA SDK 1.00" that will create and install test certificates.

Note that you must turn off the UAC if you want to use the batch file with Vista.

There is an MMC plug-in that allows computer administrators to browse the certificate store and manage the certificates in it. It can be launched with the following steps:

1) Run mmc.exe

2) Click Files | Add/Remove Snap In…

3) Click Add...

4) Select “Certificates” and click “Add”

5) Select “Computer account” and click “Next”.

6) Select “Local computer” and click “Next”

7) Click “Close”

8) Click “OK”

If the script ran successfully there should be two UA sample certificates in the “Personal” folder.

If the script did not run then you can import the certificates manually by using the certificate import wizard.

You can start this wizard by right clicking on a store folder and clicking "All Tasks | Import..".

The are three files to import which are placed in the 'UA SDK 1.00\Install' directory. You will need to change the file type to 'Personal Information Exchange (*.pfx)' to see the files.

These files are called UASampleRoot.pfx, UASampleClient.pfx and UASampleServer.pfx

After selecting a file you will be prompted for a password which is: password

The UASampleServer and UASampleClient certificates must go into the Personal store.

The UASampleRoot certificate must go in the Trusted Root Certification Authorities store.

Confirm that the certificate should be placed in the store your selected and finish the wizard.

Sample Applications

There are two sample applications bundled with the SDK:

"UA Sample Client" is a UA client and server application with a GUI (the client and server are independent of each other)

"UA Sample Server" is a standalone UA server application without a GUI

The applications can be launched from "OPC Foundation | UA SDK 1.00" directory in the Programs menu.

The UA Sample Server application can also be hosted inside IIS. The installer creates and a virtual directory for the IIS hosted server here: http://localhost/UASampleService/Service.svc

Clicking on that link should display an ASP .NET test page in a web browser.

If the ASP .NET test page does not appear it is a problem with your ASP .NET configuration. This page may help.

Running the Local Discovery Server

The Local Discovery Server (LDS) must be started manually. The installer places a shortcut in the the Programs Menu. This process is used by the client applications to discover servers running on a machine. Note that, unlike COM, UA servers *must* be started manually before a client can connect to them.

If you get a error starting the LDS then that likely means an instance of the LDS is already running. Try restarting IIS if no process appears to exist.

Selecting a Server

The UA Sample Client can connect to any of the sample servers. When this application is launched a drop down menu with several URL appears. The URLs of the sample servers are:

UA Sample Client	http://localhost:6000/UA/SampleClient
UA Sample Server	http://localhost:5000/UA/SampleServer
IIS Hosted Server	http://localhost/UASampleService/Service.svc

Note that you must manually start the UA Sample Server application before you can connect to it. If the UA Sample Server application is running an OPC icon should be visible in the tray of the task bar. Right clicking on this icon will allow you to stop the application.

You connect to a server by selecting it in the drop down and click on the “Connect” button.

You will also see additional text after the URL that indicates what security and/or message encoding is being used. Servers may support multiple endpoints with different security settings. These endpoints can be found by clicking on the '<Browse..>' option and clicking on the 'Discover' button when the endpoints for a server are in view.

Choosing an Endpoint

Any valid URL can be typed into the address bar. However, the client assumes that the discovery endpoint for the server can be constructed by appending '/discovery' to the end of the URL typed in. The client will not be able to connect if the server does not have a discovery endpoint at that address. It is possible to manually enter the the Discovery URLs for the endpoint by selecting <Browse..> in the drop down menu.

After the “Connect” button is clicked the client calls the GetEndpoints service on the discovery endpoint for the server.

Selecting an endpoint URL starting with ‘http:’ will use XML Web Services for communication. Selecting a URL starting with ‘opc.tcp’ will use UA Native Binary for communication. Note that the current release of the UA Native Binary stack profile does not implement security even though the user interface claims it is being used.

The XML Web Services stack profile allows clients to use either pure XML messages or UA binary encoded messages. The setting can be changed in the configuration for the endpoint. The <Browse..> entry in the dropdown allows you to edit the EndpointDescription and EndpointConfiguration.

The <Browse...> will also you to browse servers on the network using the LDS.

Creating a Session

The ‘Open Session’ dialog appears after clicking 'Connect'. This dialog allows you specify a name for the session and the client’s user credentials. The authentication modes depend on the endpoint. Only options available for the current endpoint are available.

The name of the session is only used as the name of the node containing the diagnostic information for the session in the server address space.

The user name/password may be left blank. If a user name is specified then it must be a valid windows account on the server machine.

Click “OK” to connect to server.

At this point data will appear in the controls.

The ‘Session Panel’ is on the left and it displays the active sessions and any subscriptions that they have.

The ‘Browse Panel’ is on the right and it displays the Object instances in the server address space.

The ‘Notification Panel’ is at the bottom and it displays the contents of Publish responses returned from the server.

Browsing the Server Address Space

The client browses the Objects folder immediately after creating a session and displays the results in the right hand panel. The top level nodes are:

Server	Diagnostics information specified in Part 5
Test Object	Simulation nodes with are part of the UA Server reference implementation (not operational in this release)
Vendors	Contains metadata describing equipment vendors used in the Boiler example.
BoilerArea	An alarm area containing the sample Boilers
Area1	Another alarm area containing the sample Boilers
Boiler1	A sample Boiler.
Boiler2	A second instance of the sample Boiler.

The Boiler example is described in detail in the presentations from the UA DevCon. The overview slide can be found here. The nodes that appear in the address space for each boiler are here.

Clicking on the plus sign next to any of these nodes with cause the client to issue a Browse request and display the results as children of the node. By default, the client only follows forward hierarchical references.

Right clicking on any node will bring up a context menu. The actions in this menu do the following:

Browse Options….	Displays dialog that sets the options passed to the Browse request.
Show References	Adds nodes representing the references into the tree.
View Attributes…	Displays the values of all attributes and properties for the node.
Refresh	Re-issues the Browse request with the current options.

It is also possible to open a new browse window by right clicking on the session in the left hand panel. The menu that appears provides a number of choices for a starting node. Selecting “All” will display all nodes in the address space.

Changing the Browse Options

The UA address space is a full mesh network, however, such a network is difficult to render in a typical two dimensional user interface. For that reason, the sample client uses filters passed to the Browse request to limit the information displayed in any given view. The user can change these filters by following these steps:

Right click on any node and select ‘Show References’. This will add an extra node into the tree control that displays the reference type for the reference between two nodes.

Right click on the ‘Boiler1’ node in the address space and select ‘Browse Options’.

Set the Reference Type to ‘References’. This tells the server to return all references from the node being browsed.

The client will re-issue the Browse request when the OK button is pressed. The tree control should now display a child folder called ‘HasTypeDefinition’. In that folder there should be a node called ‘BoilerType’.

Before changing the browse options the only references displayed were subtypes of the ‘Hierarchical References’ reference type. In this case, the only references from Boiler1 that met these criteria were the ‘HasComponent’ references.

Using Views

Server defined Views offer a way to browse a sub-set of the address space that the server feels is useful to some clients. The sample servers provide a single view called ‘BoilerView’. This view can be browsed by right-clicking on the session in the left-hand tree and selecting Browse | Server Defined Views | BoilerView

The BoilerView displays the sample boilers and their components. References to the type model do not appear in this view.

Reading Data

Reading data can be done in a number of ways. The simplest approach uses the ‘View Attributes’ option that is available in the context menu when browsing the address space. If the node is a Variable that allows read access then the ‘Read’ option will appear in the context menu.

The node ‘Area1/ Boiler1/LC1001/Measurement’ is readable. Find it and click Read. This should display the Read dialog. Clicking the ‘Read’ button will send the request and display the results.

You can add more nodes to the request by right-clicking in the top panel of the Read dialog. The ‘Select Nodes…’ option brings up the Select Node dialog. Note that double clicking on a node in a tree control simply expands or collapses the tree. If you wish to select a node you must right-click and click on the ‘Select Item’ or ‘Select Children’ options.

It is also possible to access the Read dialog from the Session Panel.

Writing Data

Writing can also be done from the Browse Panel. Selecting any Variable that allows write access will cause the ‘Write’ option to appear in the context menu.

The node ‘Area1/ Boiler1/LC1001/SetPoint’ is writable. Find it and click Write. This should display the Write dialog. Clicking the ‘Write’ button will send the request and display the results.

Double clicking on a value in the Write dialog will allow you to change it.

It is also possible to access the Write dialog from the Session Panel.

Creating Subscriptions

It is possible to create new subscriptions by right-clicking on a session in the Session Panel. This will bring up the Subscription Parameters dialog. Clicking OK brings up an empty Subscription.

At this point notification messages should start to appear in the Notifications Panel. These are the keep alive messages for the subscription and tell the client and server that communication is still functional even if there are notifications available.

You can monitored items to the subscription by choosing the ‘Add Items’ in the main menu. The node ‘Area1/ Boiler1' produces events so try adding it to the subscription. After about 20 seconds the first event notification should appear in the Subscription window.

It is possible to alter the fields returned in the event notification by selecting a monitored item and clicking the ‘Set Filter’ command from the context menu.

Try adding the children of ‘Area1/ Boiler1/CC1001’ to the subscription. These are all variables and they should change each time the subscription publish interval expires.

Calling Methods

Each instance of the sample boilers has a method called ‘SetSimulationMode’. It can be called by right-clicking on the method node and selecting the Call option. This brings up the call dialog which displays the input and output parameters for the method.

Double-clicking on an input parameter will allow you to change its value. You must specify a valid value for every parameter in this example.

Try setting the ‘RequestedMode’ to False – this will stop the simulation. You can verify that the simulation has stopped by reading or subscribing to variables for the same boiler. They do not change when the simulation is nor running.

Configuring the COM Wrapper

The app.config file for each of the sample applications contains a configuration section called Opc.Ua.SampleServer. The section has the following elements which control the wrapper:

NamespaceUri	The URI for the namespace used by the wrapper.
BrowseName	The browse name of the folder that contains the wrapped server address space.
Url	The URL of the COM server.
SeperatorChars	Specifies the separator characters that the server uses for its item ids. This field is not required and is only used to improve performance when it is possible to extract the browse name from an item id.

Note that the COM server must be accessible to the server process. This is a particular concern when running the IIS hosted version of the server which runs using the ASPNET account.

Contributors

The OPC Foundation would like to acknowledge the contributions made by the following companies towards the development of this deliverable.

Christian Zugfil, Matthias Damm

ascolab

http://www.ascolab.com

Stefan-Helmut Leitner

ABB

http://www.abb.com

Alisher Maksumov

OSIsoft

http://www.osisoft.com

Jan Burian, Rudolf Griessl