Back to contents pageHow to create a simple Ubisense application

How to create a simple Ubisense application

Summary

This article goes through the necessary steps to create a very simple Ubisense application that gets a list of the named objects. By following these steps you will learn the basics of using the Ubisense.NET API functionality in your application.





Prerequisites

None. You can use this article on its own.



Example material

Save this link to get a zip file of the example material


Guide

1) Create a new project

You can use the Ubisense .NET API within any type of .NET application: console applications, windows forms applications, website service applications, etc. In this example we will create a Windows Forms Application.

Start Visual Studio and create a new project and choose Windows Forms Application under C#. Locate the project at a known location and give it a reasonable name. See below.







2) Add the assembly references to the Ubisense dlls

For any Ubisense application you will have to add an assembly reference to the Ubisense dlls that contain the functionality to work with the Ubisense system. This allows you to instantiate client schemas that can be connected to any Ubisense (or user created) services available on the Ubisense system.

The Ubisense dlls are:

Note: For a complete list of each dll's components, check the Ubisense API documentation (accessible from the Visual Studio IDE by pressing F1).


You can include the assembly references into your project by right clicking 'References' in the Solution Explorer and selecting 'Add reference' from the context menu that appears.



When the window pops up, go the Browse tab and browse to the folder where the Ubisense software was installed (the default location is C:\Program Files\Ubisense 2.1\bin). For this example we only need the UbisensePlatform and UbisenseLocationServices dlls, choose them as shown below and click OK.





3) Design the User Interface

From here we will begin to design the GUI aspect of the form. This can include labels, buttons, etc. that the user will see when running the application.

Go to the form designer by right clicking the Form1.cs item on the Solution Explorer and selecting 'View Designer' from the list. You should be able to see the empty WinForm and the toolbox bar.

We will use a list box control to display the list of user-created objects and a button to retrieve this information from the Ubisense system. Simply drag and drop a list box control and a button into the WinForm. The user interface should look something like this:



Note: To modify the properties like, name, size, display text, etc. of the button, the list box or any Windows Form control right click the control and select properties from the context menu that appears. This should display the properties window where you can modify them.



4) Expose the desired Ubisense symbols within the scope of your program

Right click on Form1.cs in the Solution explorer and choose 'View Code'. This will show the code for the WinForm you just designed.

We will be using:

We can use the 'using' keyword to create some aliases (saving us from some keystrokes) and to bring into scope the functionality of the schema we need. See below

    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Text;
    using System.Windows.Forms;

    // Ubisense symbols
    using Naming   = Ubisense.UName.Naming;

Note: The using keyword is not used in the source code of the sample application to clearly display the namespaces used in each line.



5) Instantiating the schemas

Now we have to declare the schema object and connect it to the server so that we can query the particular schemas for information.

Your code so far should look like this:

    namespace UbisenseApp1
    {
        public partial class Form1 : Form
        {
            public Form1()
            {
                InitializeComponent();
            }

            // Declarations of the objects we need
            // Notice the use of the aliases defined in the previous code snippet
            private Naming.Schema namingSchema;
        }
    }



6) Connecting the schemas

From here we will create a simple OnLoad event to connect the schemas when the application opens. To do this return to the Form View where you see the GUI we created. In the right column make sure it says Form1 and click the lightning bolt icon to get a list of events. Double click the Load event and it will automatically drop add the event code to yours.



Add the following code into the event code, this will instantiate the namingSchema.

    private void Form1_Load(object sender, EventArgs e)
    {
        // Instantiate the objects
        namingSchema = new Ubisense.UName.Naming.Schema(false);

        // Connect the cached naming schema as client to read transactions
        namingSchema.ConnectAsClient();
    }



7) Getting the names of all the Ubisense Objects

When the user clicks the button we need to iterate over the ObjectName relation of our namingSchema object and add to the list box the names of any Ubisense objects we find. Return to the Form View again and this time right click the button control you created and select properties from the context menu that appears. On the properties window, select the bolt icon and double click the Click event to generate the button click event handler.

We need to get a ReadTransaction from the naming schema. Any entry (or row) of type ObjectName.RowType we find in this table will contain an object and a name for that object, which we will add to the list box. It is very important to wrap ReadTransaction in a using statement, otherwise the ReadTransaction is not disposed, and the lock is not released until is garbage collected. This blocks subsequent events indefinitely.

    private void btnGetObjects_Click(object sender, EventArgs e)
    {
        lboxObjects.Items.Clear();
        using (Naming.ReadTransaction xact = namingSchema.ReadTransaction())
        {
            foreach (Naming.ObjectName.RowType row
                in Naming.ObjectName.name_(xact))
            {
                lboxObjects.Items.Add(row.name_);
            }
        }
    }



8) Disconnecting the schema

The namingSchema object should be disposed of by the garbage collector when it falls out of scope. In this case, that occurs when the user ends closes the form, but is a good practice to do this yourself. Go back to the properties of the form in the form design window and select the lightning bolt icon again. Double click the FormClosed event. In the event code, call the following:


    private void Form1_FormClosed(object sender, FormClosedEventArgs e)
    {
        namingSchema.Disconnect();
        namingSchema.Dispose();
    }



9) Test the finished application

Create some objects using the Site Manager tool. Open the Site Manager tool (reachable from the Start Menu > Ubisense 2.1 > Site Manager), go to the Objects tab and select Object > New.



Run the application and verify that you get the list of the objects you created before. Try deleting some objects in Site Manager or add some more, return to your application and click the button again to update the results.





10) What's next?

This article covered the minimum concepts necessary to create a simple Ubisense application. We learned how to create a new Visual Studio project, to add the Ubisense assemblies, to bring the Ubisense symbols into the scope of our application, to create and connect schemas and finally to iterate over a relation in a Ubisense schema for information.

See the other articles for help on specific topics you need to cover for your application.





Back to top