.NET Client Toolkit (recommended)

NOTICE (July 2008) - The ASCOM .NET Client Toolkit included in the Platform 5.0 was not rebuilt for a late change to the ICamera interface. Applications that use the Client Toolkit in Platform 5.0 will not run. Thus, it is required that both you and your customers install the .NET Client Toolkit Update 1.0.5. We sincerely apologize for this.

The ASCOM Platform includes a .NET assembly that provides high-level simplified access to ASCOM drivers. Astronomy software developers wishing to use ASCOM drivers from .NET applications are encouraged to use this library, as it provides not only simplified access to drivers, but also automatic switching between the preferred early-binding interfaces and, for older drivers that don't support it, late-binding. If late binding is needed, the Client Toolkit hides all of the ugly details of calling a driver via its late-bound interface. Your code will always use native .NET class/object syntax.

Background

The Client Toolkit is an assembly that is always installed into the .NET Global Assembly Cache. Thus, everyone who installs the ASCOM Platform 5 will have the Client Toolkit installed. You do not need to include the Client Toolkit assembly in your software's distribution, and you must not do so.

However, in order to get the IntelliSense documentation for the Client Toolkit, your .NET software project must reference the copy of the Client Toolkit that is optionally installed in C:\Program Files\Common Files\ASCOM\.net. When you install the Platform, you will see a wizard panel with checkboxes for installing optional developer components. Make sure you select the Client Toolkit for developer installation. This will cause a copy of the assembly and its XML IntelliSense documentation to be put into the above folder. Your program then must reference that copy of the assembly and not the one in the GAC. See the next section for particulars.

Using the Client Toolkit

Assuming you installed the Client Toolkit via the Platform's optional developer items, as described above, set a reference to it in your .NET project. To do this, you must use the Browse tab in the Add References window, then browse to C:\Program Files\Common Files\ASCOM\.net\ASCOM.DriverAccess.dll. After setting your reference, double check that this copy of the assembly is referenced and not the one in the GAC. You must also set a reference to the ASCOM Master Interfaces for .NET and COM as well as the ASCOM Helper Interfaces for .NET. These will be found under the COM tab of the Add References window. When you are finished, make sure that you have references to ASCOM.DriverAccess, ASCOM.Interfaces, and ASCOM.Helper.

Next, in your code, use/import the following:

// C#
using ASCOM.Interface;
using ASCOM.Helper;
using ASCOM.DriverAccess;


' VB.NET
Imports ASCOM.Interface
Imports ASCOM.Helper
Imports ASCOM.DriverAccess
Simplified Driver Choosing

The Client Toolkit provides a simplified way to display the Chooser and get the driver's "progID" back. The details of creating the chooser, setting its device type, etc. are handled by the Client Toolkit. A one-line call is all that's needed. The following examples are for Telescope drivers. Substitute Focuser, Dome, etc., to choose other types of drivers.

// C#
string progID = Telescope.Choose("");

' VB.NET
Dim progID As String = Telescope.Choose("")

If you want to pre-select a particular (Telescope) driver when displaying the chooser (e.g. one that was previously chosen by your user), substitute its progID for the "" in the above calls. It's up to you to save the previously chosen driver's progID somewhere (persistently).

Creating the Driver

Once you have the progID of the chosen (or remembered) driver, it's a one-line call to create the driver itself. Again, using Telescope as an example:

// C#
Telescope T = new Telescope(progID);

' VB.NET
Dim T As Telescope = New Telescope(progID)

At this point T is a handle to the driver and may be used to access any of the standard properties and methods (members) of the driver. Upon typing T. you should see IntelliSense popups to guide you in using the standard members. If not, go back and check that you added the reference to ASCOM.DriverAccess.dll from the Platform .net folder and not from the GAC.

Using the Driver

Once you have chosen and created the driver, and have a handle to it, you can use the normal object member calling syntax of your .NET language to access its members and you should see IntelliSense documentation to guide you. The applicable driver standard document (also available as a developer option during Platform installation) will be a great help as well!

Before diving into full-blown application development, it is suggested that you create a simple Console program that walks through the process of choosing, creating, and using a driver. You can use Console.WriteLine() to write to the console window and Console.ReadLine() to read input from you. At the end of the program, put a Console.ReadLine() call to keep the console window open until you've looked at the things you're interested in. Play with it until you're really comfortable with both the process of choosing and creating the driver, and also the techniques for making the driver do what you want for the device. Choose the simulator for your device type and exercise it from the console program.