Tutorial MiniBroker & VS.Net (Lesson 1)

This article shows some basic functions of MiniBroker using C# and .Net. While I will try to keep to very simple examples a basic knowledge of programming and C# or VB.Net would be very helpful. I recommend starting with Microsoft's C# Developer Site or Visual Basic Developer Site for more information. To run this example you need the Integrator version of Premise installed.

The MiniBroker acts as a client to the Home Control Server or Sys. With it you can control or configure anything in Sys from a device, media, schedule or scenes. In todays example we will see how to connect and display information.

The example will be creating is a simple Window Application that mimics in some ways Builder. It will contain a tree view of your Premise Objects and allow you to manipulate some basic properties of the object.

Starting

To start we will use VS.Net to build the basic layout of the window.

1. Open VS.Net
2. Start a new Window project in your language of choice (Make sure you have closed any open solution) with a name of PremiseClient
3. Give the Window Form a Caption of "Premise Objects" using the Text property
4. From the Toolbox drop a TreeView component on to the form
5. Name the TreeView PremiseObjectTree
6. Set the TreeView dock property to Left
7. From the Toolbox drop a Splitter component on to the form
8. From the Toolbox drop a Panel component on to the form
9. Name the Panel ObjectView
10. Set the Panel dock property to Fill
11. Set the Panel border style property to Fixed3D
12. Compile and test the interface to make sure you can re-size the tree view and panel

Connecting

First thing to using the MiniBroker is to create an instance of the broker. To accomplish we must first have the program see the MiniBroker. You have two choices:

• Use the Premise provided assembly that wraps the MiniBroker COM object. This is found in the MiniBroker samples in the MiniBroker forum.
  1. Go to the Solution Explorer
  2. Right Click on the Project Item PremiseClient
  3. Select Add Reference
  4. Click Browse with the Add Reference Dialog box tab set to .Net
  5. Select the Premise.dll from under [premise installation directory]\Sys\MiniBroker (you may have it in a different directory and click open
  6. Hit the OK button of the Add Reference Dialog this will add an assembly that has all the COM-Interop classes already generated
• The alternative is to add the MiniBroker COM object directly to .Net and have it generate the COM-Interop assembly for you
  1. Go to the Solution Explorer
  2. Right Click on the Project Item PremiseClient
  3. Select Add Reference
  4. Click Browse with the Add Reference Dialog box tab set to COM
  5. Scroll down the list of COM objects looking for MiniBroker 1.0 Type Library
  6. Click the MiniBroker entry and hit the select button
  7. Hit the OK button of the Add Reference Dialog this will generate and add an assembly that has all the COM-Interop classes for MiniBroker

For the purposes of this example I assume that you added the Premise.dll assembly rather than create one from the COM type interface.

Now double click on the caption of the form to create an event for the OnLoad of the form. This should give you a new window with the code showing and an empty method called Form1_Load created. This is where we will create a connection to HCS aka: Sys.

1. Add a using clause for Premise using C#

using System;
using System.Drawing;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;
using Premise;

2. Add a variable called miniBroker which will be used to create a connect to the MiniBroker COM object
   private ISYSMiniBroker miniBroker = new SYSMiniBrokerClass();

The ISysMiniBroker is the interface for the MiniBroker COM interface. To get the actual COM object to instantiate we need to create it using the SysMiniBrokerClass object. We will also need to create a variable called root which represents the root of HCS object tree. To set the root you need to use the Connect method of the ISysMiniBroker interface. This method takes three parameters (ServerName, UserName, and Password) and returns the root of the HCS object tree. You must have a server name either localhost, ip address, or server name. If you have specified a username and password to get to the server then you need to supply those as well otherwise you can use null or empty string as the username and password.

Finally lets add the root to the TreeView component. By default IRemotePremiseObject exposes Name, DisplayName, and Description properties directly. Other properties are exposed directly as well but we will leave that for another day. So your code should now look like the following:

using System;
using System.Drawing;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;
using Premise;

namespace PremiseClient
{
	/// 


	/// Summary description for Form1.
	/// 
	public class Form1 : System.Windows.Forms.Form
	{
		private System.Windows.Forms.TreeView PremiseObjectTree;
		private System.Windows.Forms.Splitter splitter1;
		private System.Windows.Forms.Panel ObjectView;
		private ISYSMiniBroker miniBroker = new SYSMiniBrokerClass();
		private IRemotePremiseObject root = null;
		/// 

		/// Required designer variable.
		/// 
		private System.ComponentModel.Container components = null;

		public Form1()
		{
			//
			// Required for Windows Form Designer support
			//
			InitializeComponent();

			//
			// TODO: Add any constructor code after InitializeComponent call
			//
		}

		/// 

		/// Clean up any resources being used.
		/// 
		protected override void Dispose( bool disposing )
		{
			if( disposing )
			{
				if (components != null) 
				{
					components.Dispose();
				}
			}
			base.Dispose( disposing );
		}

		Windows Form Designer generated code

		/// 


		/// The main entry point for the application.
		/// 
		[STAThread]
		static void Main() 
		{
			Application.Run(new Form1());
		}

		private void Form1_Load(object sender, System.EventArgs e)
		{
			root = miniBroker.Connect("LocalHost", "", "");
			PremiseObjectTree.Nodes.Add(new TreeNode(root.DisplayName));
		}
	}
}

At this point make sure the program compiles and runs. You will also notice a slight lag while the form connects and fetches the root object. Your window should look like the following:

Next lesson we will see how to load the TreeView by looping through the children of the root.