How to create an Excel Real-Time Data Server
in Visual Studio: VB.NET, C#, C++

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Building Excel RTD servers

Creating Excel RTD servers

On this page you will find a step-by-step example of building a Real-Time Data server for Excel. The sample project demonstrates how you create an Excel RTD server handling a single topic.

A bit of theory

The RTD Server technology (introduced in Excel 2002) is used to provide the end user with a flow of changing data such as stock quotes, currency exchange rates etc.

To refer to an RTD server, you use the RTD function in an Excel formula. This instructs Excel to load the RTD server and wait for data from it; the bit of data to be retrieved is identified by the topic that the RTD function call specifies. (A topic is a string or a set of strings that uniquely identifies a data source or a piece of data that resides in a data source; the data source is any source of data that you can access programmatically.) When the RTD server gets new data, it notifies Excel. Every time the RTD server sends such a notification, Excel simply notes that the RTD server wants to give it an update. When Excel is ready for the update, it requests new data from the RTD server; when such a request is received, Add-in Express invokes the RefreshData event on the corresponding ADXRTDTopic component(s). When the RTD function returns a new value, Excel calculates the formula in the caller cell, recalculates dependent cells, and refreshes the work sheet(s) to reflect the changes; find background information in Excel Recalculation.

Add-in Express allows using the above-described notification mechanism in two ways:

• You can send Excel notifications at the time interval specified by the ADXRTDServerModule.Interval property.
• You can set ADXRTDServerModule.Interval=0 and call ADXRTDServerModule.UpdateTopic() or ADXRTDServerModule.UpdateTopics() when required.

Per-user and per-machine RTD servers

An Excel RTD Server can be registered either for the current user (the user running the installer) or for all users on the machine. That's why the corresponding module type, ADXRTDServerModule, provides the RegisterForAllUsers property. Registering for all users means writing to HKLM and that means the user registering a per-machine RTD server must have administrative permissions. Accordingly, RegisterForAllUsers = Flase means writing to HKCU (=for the current user).

Step 1. Creating an RTD server project

Make sure that you have administrative permissions before running Visual Studio. Run Visual Studio via the Run as Administrator command.

In Visual Studio, open the New Project dialog and navigate to the Extensibility folder.

Choose Add-in Express RTD Server and click OK. This starts the RTD server project wizard.

In the first wizard window, you choose your programming language (C#, VB.NET and C++.NET are supported):

When in the window below, choose Generate new or specify an existing .snk file and click Next. If you do not know anything about strong names or do not have a special strong name key file, choose Generate new. If you are in doubt, choose Generate new. If, later on, you need to use a specific strong name key file, you will be able to specify its name on the Signing tab of your project properties; you are required to unregister your add-in project before using another strong name.

The project wizard creates and opens a new solution in the Visual Studio IDE.

The solution contains an only project, the RTD server project. The project contains the RTDServerModule.vb (or RTDServerModule.cs) file discussed in the next step.

Step 2. Excel RTD module

RTDServerModule.vb (or RTDServerModule.cs) is the core part of the RTD server project. The module is a container for ADXRTDTopic components. It is a descendant of the ADXRTDServerModule class implementing the IRtdServer COM interface and allowing you to manage server's topics and their code.

To review its source code, right-click the file in the Solution Explorer and choose View Code in the context menu.

In the code of the module, pay attention to the CurrentInstace property. It returns the current instance of the RTD module. This is useful for example, when you need to access a method defined in the module from the code of another class.

Step 3. RTD Server module designer

The module designer allows setting real-time data server properties and adding components to the module.

In the Solution Explorer, right-click the RTDServerModule.vb (or RTDServerModule.cs) file and choose the View Designer popup menu item.

This opens the designer of the Excel RTD module:

Click the designer surface when you need to set properties of your real-time data server in the Properties window. The RegisterForAllUsers property shown in the screenshot above is described in Per-user and per-machine RTD servers. The Interval property sets the internal timer that causes Excel to generate the RefreshData event for topics of your RTD server.

Step 4. Adding and handling a new topic

To add a new topic to your RTD server, you use the Add RTD Topic command that places a new ADXRTDTopic component onto the module. Select the newly created component and, in the Properties window, enter string values identifying the topic in the String## properties. In this sample, the My Topic string in the String01 property identifies the topic.

It is possible to enter an asterisk (*) in any of the String## properties. When there is no ADXRTDTopic corresponding to the identifying strings entered by the user, Add-in Express creates a new ADXRTDTopic and passes it to the RefreshData event handler of the topic containing an asterisk (*). In that event, you can cast the Sender argument to ADXRTDTopic and get actual strings from its String## properties.

Now add the RefreshData event handler and write your code:

Private Function AdxrtdTopic1_RefreshData(ByVal sender As System.Object) _
      As System.Object Handles AdxrtdTopic1.RefreshData
   Dim Rnd As New System.Random
   Return Rnd.Next(2000)
End Function

Step 5. Running the RTD server in Excel

Choose the Register Add-in Express Project item in the Build menu, restart Excel, and enter the RTD function to a cell.

If you use an Express edition of Visual Studio, the Register Add-in Express Project item is located in the context menu of the RTD module's designer surface).

See Control Panel | Regional Settings for the parameters separator.

Step 6. Debugging the RTD server

To debug your RTD server, just specify Excel as the Start Program in the Project Options window.

Step 7. Deploying the RTD server

The table below provides links to step-by-step instructions for deploying RTD servers. Find background information in Deploying Office extensions.

What's next?

You can download this project as well as many other examples on the following pages: Excel VB.NET samples and Excel C# samples.

You may want to check the following sections under Add-in Express tips and notes:

• Development - typical misunderstandings, useful tips.
• RTD - FAQ on RTD Server and a valuable article: Inserting the RTD function in a user-friendly way.

An interesting series of articles describing the creation of a real project from A to Z is available on our blog. The starting point is Building a Real-Time Data server for Excel.