Preparing to Work with the Source Code in This Chapter

In this chapter, we continue working with the music store application that we've been developing over the past several chapters. We extend it with several new event providers that illustrate the various aspects of event provider development in SQL-NS.

This section describes the layout of the source files containing this chapter's code and the steps you need to take to get ready to use the working examples.

Source Files

As in previous chapters, we're going to modify the source code for the music store application in the C:\SQL-NS\Samples\MusicStore directory. Supplemental source files containing the code we look at in this chapter are provided in the C:\SQL-NS\Chapters\08\SupplementaryFiles directory. Table 8.1 provides a summary of the contents of these supplementary files.

Table 8.1. Supplementary Files and the Code They Contain

Filename	Code Added	Sections
InstanceConfiguration-0.xml	The ICF in its existing form, as first created in Chapter 5 (no code added)	Not used in this chapter; included only for reference
InstanceConfiguration-1.xml	The <EncryptArguments> element and a parameter definition used later in one of the event provider configurations	"Starting from a Clean Instance" (p. 241)
ApplicationDefinition-7.xml	FileSystemWatcherProvider declaration	"The FileSystemWatcherProvider" (p. 246)
ApplicationDefinition-8.xml	SQLProvider declaration and supporting event chronicle	"The SQLProvider" (p. 253)
ApplicationDefinition-9.xml	Continuous, custom, hosted event provider declaration	"Building a Continuous Custom Hosted Event Provider" (p. 269)
ApplicationDefinition-10.xml	Scheduled, custom, hosted, event provider declaration	"Building a Scheduled Custom Hosted Event Provider" (p. 281)
ApplicationDefinition-11.xml	Standalone event provider declarations	"Building Standalone Event Providers" (p. 291)

As before, the actual ICF and ADF that the compiler reads are C:\SQL-NS\Samples\MusicStore\InstanceConfiguration.xml and C:\SQL-NS\Samples\MusicStore\SongAlerts\ApplicationDefinition.xml. In this chapter, when you're instructed to add code, you can either edit these files manually, or you can copy over one of the supplemental files. You then update the instance as you did in previous chapters to compile the new code.

The source files for the custom event providers that we build in this chapter are in the C:\SQL-NS\Samples\MusicStore\SongAlerts\CustomComponents directory. We examine these files in the sections "Building Custom Hosted Event Providers" (p. 264) and "Building Standalone Event Providers" (p. 291).

Changes to the Scripts for Argument Encryption

As in previous chapters, we'll continue using batch files in the Scripts subdirectory under C:\SQL-NS\Samples\MusicStore to create, manipulate, and configure the SQL-NS instance. Many of these are the same as the ones you've seen in previous chapters, but some new ones are introduced to accommodate argument encryption, which we use in this chapter.

As explained in the "Argument Encryption" section (p. 237), you enable argument encryption by setting the value of the <EncryptArguments> element in the ICF to true. Listing 8.1 showed the fragment of the ICF we'll use in this chapter that sets this element. When we invoke the nscontrol create, register, and update commands, we need to pass the argument key value. This is done by means of the -argumentkey parameter, which each of these commands takes.

In the Scripts directory, you'll find scripts called create_with_argument_key.cmd, register_with_argument_key.cmd, and update_with_argument_key.cmd. These are equivalent to the scripts you used in previous chapters (create.cmd, register.cmd, and update.cmd, respectively) except that the nscontrol commands in the new scripts are invoked with the -argumentkey parameter. As an example, let's look at the call to nscontrol create in create_with_argument_key.cmd:

[View full width]
 nscontrol create -in "%INSTANCE_BASE_DIRECTORY_PATH%\InstanceConfiguration.xml"  %SQL_USER_INFO% -argumentkey MusicStoreArgumentKey _SqlServer_=%SQL_SERVER% _NSServer_= %NS_SERVER% _InstanceBaseDirectoryPath_="%INSTANCE_BASE_DIRECTORY_PATH%" 

The boldface portion of the command supplies the string, MusicStoreArgumentKey, as the value of the -argumentkey parameter. You can use any string value for the argument key; I've chosen the rather unimaginative value you see here purely for simplicity. Take a look at the other two scripts to see how the -argumentkey parameter is used with nscontrol register and nscontrol update.

Note

Whatever argument key you decide to use, it's important that you pass the same value for the -argumentkey parameter to nscontrol create, register, and update.

The steps in the following section instruct you to use create_with_argument_key.cmd to create the music store instance from scratch and register_with_argument_key.cmd to register it. When you update the instance to add the new code for this chapter, make sure you use update_with_argument_key.cmd instead of update.cmd. If you use the wrong script, the argument key won't be supplied to nscontrol update, resulting in a compile error.

Specifying an Argument Key When Creating, Registering, and Updating an Instance with the Management Studio Tools

Like the command-line tools, the SQL-NS tools in Management Studio also provide a way for you to specify an argument key when creating, registering, and updating an instance that uses argument encryption. The dialog boxes used to invoke these commands each have a page labeled Encryption, which contains a text box you can use to enter the argument key value.

You can select the Encryption page from the page selector in the left side panel of the New Notification Services Instance, Register Instance, and Update Instance dialog boxes. In all of these dialog boxes, enter the argument key in the text box on the Encryption page before clicking the OK button to invoke the command.

Starting from a Clean Instance

Although this chapter extends the prototype of the music store application that you built in previous chapters, you will need to recompile the music store instance from scratch, rather than just update the version you created earlier. Besides ensuring that you're starting from a clean instance (free of any artifacts that may have developed from earlier testing and debugging), this is necessary because we are now using argument encryption. Recall that it's not possible to update an existing instance to turn on argument encryption: You must first delete and then re-create the instance.

Before starting the work of this chapter, perform the following instructions to establish a clean instance:

1.	From a Notification Services Command Prompt on your development machine, navigate to the music store instance's scripts directory by typing the following command: cd /d C:\SQL-NS\Samples\MusicStore\Scripts
2.	Run cleanup.cmd to remove the music store instance and all associated files that might have been left over from previous chapters' work.
3.	Copy the supplementary file InstanceConfiguration-1.xml from this chapter's supplementary file directory over the existing music store ICF using the following command: copy /y C:\SQL-NS\Chapters\08\SupplementaryFiles\InstanceConfiguration-1.xml C:\SQL-NS\Samples\MusicStore\InstanceConfiguration.xml This changes the ICF to include the <EncryptArguments> element (set to true, as shown in Listing 8.1) and adds one parameter definition that we'll need later.
4.	Make sure that the music store ADF, C:\SQL-NS\Samples\MusicStore\SongAlerts\ApplicationDefinition.xml, contains the complete code for the music store prototype, as developed so far. It should contain the same code as the supplementary file ApplicationDefinition-6.xml in the Chapter 6, "Completing the Application Prototype: Scheduled Subscriptions and Application State," supplementary file directory, C:\SQL-NS\Chapters\06\SupplementaryFiles. If you completed the steps in previous chapters, the ADF should already have the correct contents. Otherwise, you can copy the supplementary ADF now.
5.	Run create_music_store_database.cmd. This rebuilds the music store database.
6.	Run create_with_argument_key.cmd to compile the instance and application from scratch.
7.	Run register_with_argument_key.cmd to register the instance.
8.	Run grant_permissions.cmd to assign the appropriate database permissions.
9.	Run enable.cmd to enable the instance.

Caution

If you accidentally invoked register.cmd instead of register_with_argument_key.cmd in step 7, the argument key will not be written to the Registry. The call to nscontrol register in register.cmd does not specify an argument key value (the -argumentkey parameter is omitted entirely).

As a result, the SQL-NS service will fail to start. Because the instance uses argument encryption, the service cannot do any processing if it can't retrieve the argument key from the Registry. If you use the net start command to start the service, you'll see an error message that reads, A system error has occurred. Also, an event message will be written to the Application Event Log. To see this message, open the Event Viewer from Administrative Tools, select the Application log, and look for a message with NotificationServices as the event source name and an event ID of 6. The description in the message will read:

 The argument key was not provided but an argument key was given when the database was created. 

To correct the situation, first unregister the instance using the unregister.cmd script (also located in the C:\SQL-NS\Samples\MusicStore\Scripts directory). Then run register_with_argument_key.cmd.

You do not need to add subscribers and subscriptions. Because we're focusing on event submission, all the tests in this chapter go only as far as making sure that the correct events end up in the events table. The tests do not check how those events are matched with subscriptions. We can do this with confidence because we've already tested the matching capabilities of the application in previous chapters. We know that when events end up in the events table, the matching logic in the application works. This chapter just presents several alternative ways to get events into the events table. It is a testament to the elegant design of the SQL-NS architecture that this kind of modular testing is possible.

The AddSongs Program

In the music store application, events represent songs added to the music store's catalog. In previous chapters, we simulated events by inserting the IDs of songs already in the music store catalog into the event class view. We never actually added any new songs to the catalog.

Some event providers in this chapter do look at the data in the music store catalog to determine whether new songs have been added. To test these event providers, we need a way to add new song records to the catalog tables. I've provided a program called AddSongs that presents a simple user interface for doing this. A Visual Studio solution containing the source code for this program is in the C:\SQL-NS\Samples\MusicStore\SongAlerts\AddSongs directory. Before continuing, build this solution so that you can run the program when it's needed later:

1.	Open the solution file, C:\SQL-NS\Samples\MusicStore\SongAlerts\AddSongs\AddSongs.sln, in Visual Studio.
2.	Build the solution. The project should compile with no errors.

At this point, it's not necessary for you to go through the source code for the AddSongs program. The "Submitting Events from an Application" section (p. 296) later in this chapter describes how this program can act as a standalone event provider; in that section, we look at the parts of its source code involved in event submission. For now, just start the program in Visual Studio (by going to the Debug menu and selecting Start Debugging, or by pressing F5) so that you can learn how to use it.

Caution

For AddSongs to work correctly, the music store database must already have been created. Before running the AddSongs program, make sure that you've completed the instructions in the "Starting from a Clean Instance" section (p. 241).

When AddSongs starts, it opens a database connection dialog box in which you specify how to connect to the music store database. Enter the name of the SQL Server hosting the database and select either Windows Authentication or SQL Server Authentication. If you select SQL Server Authentication, supply the username and password of the development account you created in Chapter 2, "Getting Set Up." Click OK to connect to the database.

After AddSongs connects to the database, you should see a window like the one shown in Figure 8.4.

Figure 8.4. The AddSongs program.

AddSongs allows you to enter a new album, with up to five songs. It's obviously a rather limited application. It does not allow you to add songs to existing albums, browse the songs already in the database, or enter more than five songs. However, for the simple purpose of adding songs to the database to test event providers, it is sufficient.

Enter an album title and artist name into the first two text boxes and pick a genre from the drop-down list. You can then enter up to five songs and click Add to Database to create the album and song records in the music store catalog. For now, leave the Submit Events for Songs Added box unchecked. I'll explain the use of this check box later in this chapter.

Take the time to play with AddSongs and familiarize yourself with it. Later in this chapter, you'll be asked to use it to add songs to the database.

Note

After having built the AddSongs program as instructed in this section, you can start it later by invoking the AddSongs.exe executable directly from the solution's binaries directory, C:\SQL-NS\Samples\MusicStore\SongAlerts\AddSongs\bin\Debug.

Installing Message Queuing

One of the event provider examples in this chapter uses Message Queuing, an optional Windows component. If you don't have this component installed, you should install it now. If you choose not to install Message Queuing, you will still be able to work through most of the material in this chapter. You just won't be able to run the continuous hosted event provider described later.

To install Message Queuing, use the following instructions:

1.	From your Start menu, open Control Panel and select Add or Remove Programs.
2.	In the left pane of the Add or Remove Programs window, choose the Add or Remove Windows Components icon. The Windows Components Wizard opens.
3.	Find the Message Queuing item in the components list. On some versions of Windows, Message Queuing is not in the top-level components list. If you don't see it in the first list in the Windows Components Wizard, select the Application Server item (which should be in the first list) and click the Details button. Message Queuing should be an item in the subcomponents dialog box that opens.
4.	Check the box next to the Message Queuing item, as shown in Figure 8.5. If the box is already checked, you already have Message Queuing installed. You can cancel the wizard and skip the rest of these instructions. Figure 8.5. The Windows Components Wizard.
5.	If your development machine is not part of a domain, you must not install the Active Directory Integration subcomponent of Message Queuing: select the Message Queuing component, click the Details button, and deselect the Active Directory Integration option in the subcomponents dialog box. If your development machine is part of a domain, you can skip this step (the default subcomponents of Message Queuing will be installed).
6.	Close any sub-component dialog boxes that may be open and then click the Next button in the wizard to allow Windows Setup to install the necessary files (you may be prompted to insert your Windows installation CDs).
7.	Finish the wizard, close Add or Remove Programs, and close the main Control Panel window.