Building Wizard Data Provider Plug-ins for the Office 2003 Research Service Class Library
Chris Kunicki
OfficeZealot.com
September 2004
Applies to:
Microsoft Office 2003 Editions
Summary: One of four articles, read this article to discover the requirements and steps to build a new data provider plug in for use with custom data providers. The Microsoft Office 2003 Research Service Class Library (RSCL) Wizard includes a pluggable architecture to allow you to add new data providers to the wizard. (5 printed pages)
Download Office2003_ResearchServicesDevelopmentExtras.msi.
Contents
Using the Research Services Class Library
Understanding the RSCLWizardInterface IPlugin Interface
Walk Through the OleDB Data Provider
Additional Documentation for the Research Service Development Extras Toolkit
Using the Research Services Class Library
The Research Services Class Library is an object model wrapper around the XML schema API for research services, as defined in the Microsoft Office 2003 Research Service SDK.
The Research Services Class Library simplifies the creation of research services by abstracting often-used features normally specified through the manipulation of XML into a simple object model wrapper. The wrapper produces the XML code required by the Research task pane. Using the Research Services Class Library, you can focus on the business logic of the solution rather than the XML code for the research service.
For more information about the Research Services Class Library, see Introduction to the Office 2003 Research Services Class Library.
The data provider plug-in is responsible for generating the data layer code used by the RSCL Wizard. The data providers included with the RSCL Wizard are actually plug-ins and can provide you with a good starting point to build a new data provider plug-in.
Once you install the download, you can find the source code to the included data provider plug-ins at the following location:
\Install_Path\Class Library Wizard Source Code\Plugins
Understanding the RSCLWizardInterface IPlugin Interface
A plug-in is a .NET Framework class library that exposes certain methods and properties, and a user interface in the form of a .NET UserControl. The plug-in must derive from the RSCLWizardInterface IPlugin interface. The RSCL Wizard loads all available plug-ins and displays the selected plug-in to the client. The RSCLWizardInterface IPlugin interface defines the methods and properties for the plug-in. The following is a list of interface property and method requirements for a plug-in:
Table 1. Properties and requirements for a plug-in
| Property | Requirement |
|---|---|
| Name | A public read-only string representing the name of the plug-in. This is displayed to the user when selecting a data provider to use. |
| GenerateVB | A public write-only Boolean. The wizard sets this value based on whether the generated data layer code should be Microsoft Visual C# or Microsoft Visual Basic .NET. If set to True, the provider should generate Visual Basic .NET code; if set to False, the provider should generate C# code. |
| AssembliesToAdd | A public read-only StringDictionary collection used to add assemblies to the generated project. For each Key-Value pair in the StringDictionary, an assembly is added to the generated project. The Key of the StringDictionary can be any string; the Value of the StringDictionary must be a valid path to an assembly. |
| UserControlInterface | A public read-only reference to a user control that displays when the user selects the data provider. This user control collects data from the client to build the data layer code for the generated project.
Note The recommended dimensions of the user control is no larger than 528 pixels wide by 256 pixels high; anything larger than this is truncated when displayed to the client. |
| Code | A public read-only string representing the code that is added to the data layer of the generated Research service. This code must be complete, with no errors, or the generated project fails. |
Table 2. Methods and requirements for a plug-in
| Property | Requirement |
|---|---|
| Initialize | The RSCL Wizard calls this method when it loads all the plug-ins. Include any set up work for the plug-in with this property.
Note Because multiple plug-ins loaded at this time, do not ask for a response from the client computer. |
| SetValues | This method is called when the client computer clicks Next on the RSCL Wizard to advance to the next screen. This is where you set the return values for the plug-in. |
| Finalize | This method is called when the RSCL Wizard closes. Include any cleanup work for the plug-in with this property. |
Walk Through the OleDB Data Provider
First, consider what the OleDB Data Provider does. It is a very simple plug-in that collects two values from the client. The OleDB Data Provider collects a database connection string and a SQL statement to run against the database. The plug-in loads a code template and inputs the values entered by the client into the template. It then sets the public property Code to the value of the modified template. The RSCL Wizard uses the code for the data layer of the Research service project it generates.
To start, open the OLEDB Data Provider project by going to the following location:
Install_Path\Class Library Wizard Source Code\Plugins\OleDBProvider
And then open the OleDBProvider.sln solution file in Microsoft Visual Studio .NET.
References
Notice the RSCLWizardInterface reference under References. This reference points to
Install_Path\Class Library Wizard\Providers\RSCLWizardInterface.dll
This is the complied version of the RSCLWizardInterface. It is in the same directory as the release version of the plug-in. The RSCL Wizard iterates through this directory when it is looking for data provider plug-ins. For that reason, when you build your own plug-in, make sure the compiled version resides in this same directory.
OleDbProvider.cs
The RSCL Wizard uses this class when it loads the plug-in. The first thing to notice in this file is the using statements at the top of the page. There are two noteworthy points: RSCLWizardInterface and System.Collections.Specialized for AssembliesToAdd. RSCLWizardInterface is used because it contains the IPlugin interface from which the OleDbProvider class is derived. Use System.Collections.Specialized for AssembliesToAdd as the StringDictionary collection of assemblies to add to the generated project.
Next, notice how the public class OleDbProvider inherits IPlugin. This is essential when the wizard loads. The RSCL Wizard scans the provider directory for all .dll files, then, using reflection, interrogates each DLL for a class inheriting from the IPlugin interface. If nothing inherits the IPlugin interface, the wizard will not load the plug-in.
All of the properties are GET or SET to an internal variable used by the plug-in. It is important to have the Name property set to a value right away because the wizard uses this name to display it values to the client.
Next, the methods, both Initialize and Finalize are present but do not do anything, because no setup or cleanup work was required for this plug-in. Both are required by the interface.
The SetValues method does a few things. It first determines the language in use then it selects a code template to use based on the chosen language. Let's review the code templates.
Open Constants.cs. There are two constants in this file. One is CSharp and the other is VB; these are code templates to generate for the data layer. There are two vital elements that the code for the data layer must have. First, the root namespace must be ResearchService. In Visual Basic .NET, this is specified for you, but in C #, you must specify the namespace. The second element is that there must be a public class called DataLayer with a method called RetrieveData accepting a single string parameter and returning a DataTable. If these two requirements are not present, the data layer fails and the generated Research service project will not build.
The SetValues method adds the client computer's input into the code template and sets the Code string to return to the wizard as the value of the modified code template.
Next, the SetValues method adds an entry into the AssembliesToAdd collection. This is a reference to the System.Data library that you need for the Research service to work. Using this method, you could add any assembly the plug-in requires to the generated Research service project.
UC.cs
UC.cs is a very simple UserControl with two labels and two textboxes. Your UserControl does not need to be simple; it could include many pages to collect whatever information from the client you need.
Additional Documentation for the Research Service Development Extras Toolkit
Read the following articles for more information about the Research Service Development Extras Toolkit:
- Getting Started with the Research Service Development Extras Toolkit for Office 2003 Editions. Describes the items included with the Research Services Development Extras toolkit in detail.
- Introduction to the Office 2003 Research Services Class Library. Describes each sample and describes the Research Services Class Library.
- Connecting to Databases Using the Office 2003 Research Service Class Library Wizard. Describes how to use the Research Services Class Library (RSCL) Wizard to connect to existing databases.
About the Author
Chris Kunicki is a longtime enthusiast of Office development and has been evangelizing Office as an important platform for building solutions for many years. As the founder of OfficeZealot.com, a leading Web site on Office solutions development, Chris builds enterprise solutions, designs tools for developers, delivers presentations, and writes extensively on the topic of Microsoft Office. Find out more about Chris and Office at www.OfficeZealot.com or send him an e-mail message at chris@officezealot.com.