Preparing to Work with Delivery Protocols

In this chapter, we will continue to develop the music store application by adding support for real delivery protocols. First, we add the code required to use the built-in SMTP delivery protocol; then we build a custom delivery protocol and modify the application to use it.

To work with the sample code in this chapter, you must re-create the instance and make a few other changes to your system. This section describes the steps you need to take. Make sure that you complete these steps before proceeding with the code shown in later sections of this chapter.

Build Supporting Components

We will continue to use the AddSongs program (developed in Chapter 8) to submit events into the application. If you've been following the steps in the previous chapters, you probably have this program built and ready to run, in which case you're ready to submit events in this chapter. If this is not the case, refer to the section "The AddSongs Program" (p. 243) in Chapter 8 for instructions on how to build and run AddSongs . Complete these instructions and make sure that you can start AddSongs before proceeding.

Note

If the music store database does not exist on your system (as will be the case if you performed the cleanup instructions described at the end of Chapter 9), AddSongs will display an error message if you try to connect to your SQL Server. The next section provides instructions on how to re-create the music store database, as well as the instance and application databases. After completing those instructions, you will be able to connect to the music store database with AddSongs .

Because AddSongs is our event provider, check the Submit Events for Songs Added box whenever you use AddSongs in this chapter.

In this chapter we continue using the custom content formatter developed in the previous chapter to format notifications. In Chapter 9, you built the content formatter source code that produced the content formatter assembly ( NewSongNotificationFormatter.dll ). Verify that this assembly exists (in the C:\SQL-NS\Samples\MusicStore\SongAlerts\CustomComponents\NewSongNotificationFormatter\bin\Debug directory). If the assembly doesn't exist in that location, you will need to build the source code to create it. Refer to the instructions in the "Implementing the Content Formatter Interface" section in Chapter 9 for a description of how to open the Visual Studio solution containing the content formatter code. Build the solution to produce the content formatter assembly.

Re-creating the SQL-NS Instance

Supplementary files containing the ICF and ADF code shown in this chapter are located in the C:\SQL-NS\Chapters\10\SupplementaryFiles directory:

InstanceConfiguration-2.xml adds the declaration of a delivery channel that uses the SMTP delivery protocol to what was previously in the ICF.
InstanceConfiguration-3.xml adds the declaration of the custom delivery protocol we develop in this chapter, as well as a delivery channel that uses it.
ApplicationDefinition-14.xml contains the changes to the ADF required to work with the SMTP protocol.
ApplicationDefinition-15.xml contains the changes to the ADF required to work with the custom delivery protocol we develop in this chapter.

The supplementary files InstanceConfiguration-2.xml and ApplicationDefinition-14.xml contain the initial ICF and ADF code from which we re-create the music store sample in this chapter. Use the following instructions to prepare the source files and get the new instance running:

1.	If you have not already done so, clean up any old version of the music store instance left on your system, as described in the "Cleanup: Preparing for the Next Chapter" sidebar (p. 346) in Chapter 9.
2.	Copy the supplementary file `C:\SQL-NS\Chapters\10\SupplementaryFiles\InstanceConfiguration-2.xml` over the music store instance's ICF, `C:\SQL-NS\Samples\MusicStore\InstanceConfiguration.xml` , using the following command: [View full width] [View full width] copy /y C:\SQL-NS\Chapters\SupplementaryFiles\InstanceConfiguration-2.xml C:\SQL-NS \Samples\MusicStore\InstanceConfiguration.xml
3.	Copy the supplementary file `C:\SQL-NS\Chapters\10\SupplementaryFiles\ApplicationDefinition-14.xml` over the music store application's ADF, `C:\SQL-NS\Samples\MusicStore\SongAlerts\ApplicationDefinition.xml` , using the following command: [View full width] [View full width] copy /y C:\SQL-NS\Chapters\SupplementaryFiles\ApplicationDefinition-14.xml C:\SQL-NS \Samples\MusicStore\SongAlerts\ApplicationDefinition.xml
4.	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
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

Do not start the music store instance's Window service ( NS$MusicStore ) at this time. As instructed in the following section, "Change Service Account Permissions" (p. 363), you will need to change the permissions of the service account. If the service is running at the time you do this, you'll be required to stop and restart it.

Change Service Account Permissions

When you test the music store application with the SMTP delivery protocol later in this chapter, you'll use a local SMTP server installed on your development machine as the delivery endpoint. The "Installing the SMTP Service" section (p. 366) describes how to install the SMTP service on your development machine in preparation for this testing.

Because of the way the .NET Framework Mail APIs (used in the implementation of the built-in SMTP protocol) interact with Internet Information Services (of which the SMTP service is a part), sending email via the local SMTP server requires Administrator privileges. However, from a security perspective, it's always best to run the SQL-NS engine under a low-privileged account; to test the capabilities of the SMTP delivery protocol in this chapter, you need to temporarily grant Administrator privileges to the engine's account (the account used to run the SQL-NS Windows service). The "Restoring Your System" section (p. 389) at the end of this chapter provides instructions on how to revoke these privileges after you're finished working with SMTP in this chapter.

Note that if you're using the SMTP delivery protocol with a remote SMTP server (as is most often the case in production environments), you do not need to grant Administrator privileges to the service account. This step is necessary only in the development environment we're using.

Use the following instructions to add the service account to the Administrators group on your development machine:

Note

To complete these instructions, you will need to know the name of the service account you created in Chapter 2, "Getting Set Up." If you don't remember the account name , open the C:\SQL-NS\Common\ setenv .cmd file and look at the value you specified for the NS_SERVICE_USER_NAME environment variable.

1.	From the Start menu, right-click My Computer and choose Manage from the context menu that appears. The Computer Management window opens.
2.	In the tree in the left pane of the Computer Management window, select the Local Users and Groups node.
3.	Double-click the Groups folder in the right pane.
4.	Double-click the Administrators group to open its properties page.
5.	Click the Add button beneath the list of group members .
6.	In the Select Users, Computers, or Groups dialog box that appears, type the name of the service account. If your service account is a domain account, make sure that you specify the domain name, using the `DOMAIN\User` syntax (for example, `PATHERNET\SQL-NS_Service` ).
7.	Click OK to close the dialog box and return to the Administrators group properties page. The service account should now appear in the list of members.
8.	Click OK to close the Administrators group property page and then close the "Computer Management" window.

Adding Subscriber Devices for New Delivery Channels

In Chapter 9, we used a T-SQL script to add a set of hard-coded subscribers, subscriber devices, and subscriptions to the instance and application. The data specified various device types and locales that allowed us to test the content formatting capabilities of the application. However, all the subscriber devices specified the delivery channel name as FileChannel , the name of the delivery channel that uses the File delivery protocol.

In this chapter, we create two new delivery channels: one that uses the SMTP delivery protocol, and another that uses the custom delivery protocol that we build. To test the new delivery protocols with the music store application, we need subscriber devices that refer to the new delivery channels. Again, we'll use T-SQL scripts to enter the required data.

The C:\SQL-NS\Chapters\10\Scripts directory contains three T-SQL scripts:

AddSubscribers.sql adds a set of subscriber records.
AddSMTPSubscriberDevicesAndSubscriptions.sql adds subscriber devices configured to the delivery channel that uses SMTP and a set of subscriptions that reference these devices.
AddMQSubscriberDevicesAndSubscriptions.sql adds subscriber devices configured to the delivery channel that uses our custom delivery protocol and a set of subscriptions that reference these devices.

In these scripts, the subscriber devices configured to the SMTP delivery channel are of the Email device type. Those configured to the delivery channel that use the custom delivery protocol are of the TextMessageDevice type.

The delivery channel that uses SMTP is defined in the ICF you already compiled in the "Re-creating the SQL-NS Instance" section (p. 362) earlier. The delivery channel that uses the custom delivery protocol will be added to the instance when we build the protocol itself. Both delivery channel definitions are described in detail later in this chapter. Because SQL-NS does not allow subscriber devices to reference nonexistent delivery channels and only the SMTP delivery channel is currently defined, we can add only the Email devices at this time. We cannot run the third script in the preceding list, AddMQSubscriberDevicesAndSubscriptions.sql , until we add the second delivery channel, later on.

For now, complete the following steps to submit the subscriber records, the subscriber device records for the SMTP delivery channel, and the corresponding subscription records:

1.	Open `AddSubscribers.sql` and `AddSMTPSubscriberDevicesAndSubscriptions.sql` (from `C:\SQL-NS\Chapters\10\Scripts` ) in Management Studio.
2.	Take a look at the data hard-coded in these files so that you're familiar with the subscriber, subscriber device, and subscription records that will be submitted.
3.	Execute `AddSubscribers.sql` first, then execute `AddSMTPSubscriberDevicesAndSubscriptions.sql` .

Installing the SMTP Service

To test the application with the SMTP delivery protocol, you need to have the SMTP Service installed on your development machine. However, the service need not be running (and, as described later in this chapter, should not be running while you're testing the application).

Use the following instructions to install the SMTP Service:

1.	From your Start menu, open Control Panel and then Add or Remove Programs.
2.	In the left pane of the Add or Remove Programs window, choose the Add or Remove Windows Components icon. This opens the Windows Components Wizard.
3.	Select the Internet Information Services (IIS) item in the components list. In some versions of Windows, Internet Information Services (IIS) appears under the Application Server item in the components list. If you don't see Internet Information Services (IIS) in the first list of components, select Application Server, then click Details. Internet Information Services (IIS) should be in the subcomponents list that appears.
4.	With Internet Information Services (IIS) selected, click the Details button to open the IIS subcomponents dialog box.
5.	Find the SMTP Service item in the subcomponents list and check the box next to it. If the box is already checked, you already have the SMTP Service installed, so you can cancel the wizard and skip the rest of these instructions.
6.	Click OK to close the subcomponents dialog box and then click Next in the wizard. Windows Setup then installs the necessary files (you may be prompted to insert your Windows installation CDs).
7.	Finish the wizard and close Add or Remove Programs, as well as the main Control Panel window.

Message Queuing for the Custom Delivery Protocol

The custom delivery protocol that we build in this chapter uses Message Queuing to deliver notifications. In Chapter 8, we also used Message Queuing to build one of the custom event providers. If you installed Message Queuing in Chapter 8, you are already set up to work with the custom delivery protocol in this chapter. If you did not install Message Queuing earlier but want to use the custom delivery protocol that we build here, refer to the "Installing Message Queuing" section (p. 245) in Chapter 8 and carry out the installation instructions given there.

Flylib.com

Category list

Similar pages

Preparing to Work with Delivery Protocols