Microsoft SQL Server 2005 Developer’s Guide- P18 pptx

Chapter 5: Developing with Notification Services 149
The StoreID field identifies the store for which events will be subscribed to. The
IndexSqlSchema element is used to create an index on the StoreID column. As you
saw with the event class, Notification Services uses the subscription class descriptions
to create database objects when the Notification Services application is generated.
After the subscriptions have been set up, the next section of code in the
EventRules element defines the logic that the Notification Services application will
use to match events to subscriptions. While the Event and Subscription information
is defined using XML, the event rules are created using T-SQL code that’s stored in
the EventRules Action element. In this example, the most important thing to notice
is that when the join condition is met, a row for the subscriber will be created. In
other words, when an event record is added where the StoreID matches the StoreID
from a subscription record, then a new row will be written to the ShipNotifications
table creating a notification. That notification will contain the information
from the subscription, including the SubscriberID, the DeviceName, and the
SubscriberLocale, as well as information from the event, including the StoreID, the
Date, the ProductID, the ProductName, and the number of Units.
Defining the ADF Notification Schema
The final part of the ADF file defines the notification as described in the
NotificationClasses section. The NotificationClasses describe how the notification
information will be delivered. The NotificationClasses element could describe
multiple notification types, where each type is described in its own NotificationClass
element. Because this sample application uses only one type of notification, the
NotificationClasses section contains a single NotificationClass element.
<! Describes the Notifications >
<NotificationClasses>
<NotificationClass>
<NotificationClassName>ShipNotifications</NotificationClassName>
<Schema>
<Fields>
<Field>

<FieldName>StoreID</FieldName>
<FieldType>int</FieldType>
</Field>
<Field>
<FieldName>Date</FieldName>
<FieldType>datetime</FieldType>
</Field>
150 Microsoft SQL Server 2005 Developer’s Guide
<Field>
<FieldName>ProductID</FieldName>
<FieldType>int</FieldType>
</Field>
<Field>
<FieldName>ProductName</FieldName>
<FieldType>nvarchar(40)</FieldType>
</Field>
<Field>
<FieldName>Units</FieldName>
<FieldType>int</FieldType>
</Field>
</Fields>
</Schema>
<! Specify the Content Format XSLT >
<ContentFormatter>
<ClassName>XsltFormatter</ClassName>
<Arguments>
<Argument>
<Name>XsltBaseDirectoryPath</Name>
<Value>%_InstancePath_%</Value>
</Argument>

<Argument>
<Name>XsltFileName</Name>
<Value>NSApp.xslt</Value>
</Argument>
</Arguments>
</ContentFormatter>
<Protocols>
<Protocol>
<ProtocolName>File</ProtocolName>
</Protocol>
</Protocols>
</NotificationClass>
</NotificationClasses>
<Generator>
<SystemName>%_ServerName_%</SystemName>
</Generator>
<Distributors>
Chapter 5: Developing with Notification Services 151
<Distributor>
<SystemName>%_ServerName_%</SystemName>
</Distributor>
</Distributors>
<! ApplicationExecutionSettings >
<ApplicationExecutionSettings>
<QuantumDuration>PT15S</QuantumDuration>
<DistributorLogging>
<LogBeforeDeliveryAttempts>false</LogBeforeDeliveryAttempts>
<LogStatusInfo>false</LogStatusInfo>
<LogNotificationText>false</LogNotificationText>
</DistributorLogging>

<Vacuum>
<RetentionAge>P1D</RetentionAge>
<VacuumSchedule>
<Schedule>
<StartTime>3:00:00</StartTime>
<Duration>P0DT02H00M00S</Duration>
</Schedule>
</VacuumSchedule>
</Vacuum>
</ApplicationExecutionSettings>
</Application>
In this listing you can see that the notification class is named ShipNotifications.
The ShipNotifications class’ Schema element defines the information that will
be sent to the subscriber. Here you can see that the values of the StoreID, Date,
ProductID, ProductName, and Units will be sent as part of the notification.
The ContentFormatter element defines how the notification will be formatted
when it is sent to the subscriber. This example illustrates using the built-in
XSLTFormatter. The Arguments element describes the directory where the XSLT
file is found as well as the name of the file. In this listing you can see that the XSLT
file is found in the %_InstancePath_% directory (which, as you saw in the ICF file,
points to C:\temp) and is named NSApp.xslt. The value of File in the Protocols
section indicates that the notification will be generated in the file system.
The Generator, Distributor, and ApplicationExecutionSettings elements specify
the SQL Server system that will be used to generate notifications, the system that
will be used to distribute notifications, the interval at which system performance
counters will be updated, and the interval at which the notification tables will be
cleaned up of undelivered notifications, respectively.
152 Microsoft SQL Server 2005 Developer’s Guide
Formatting the Notification Output
In the preceding listing you saw that the notification was formatted using the

NSApp.xslt style sheet. You can see what that example style sheet looks like in the
following listing:
<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0"
xmlns:xsl=" /><xsl:template match="notifications">
<HTML>
<BODY>
<xsl:apply-templates />
<I>
This message was generated using
<BR/>Microsoft SQL Server Notification Services
</I><BR/><BR/>
</BODY>
</HTML>
</xsl:template>
<xsl:template match="notification">
<P>
There is a shipment for: <B><xsl:value-of select="StoreID"/></B>
<BR/>Date: <B><xsl:value-of select="Date"/></B>
<BR/>Product ID: <B><xsl:value-of select="ProductID"/></B>
<BR/>Product Name: <B><xsl:value-of select="ProductName"/></B>
<BR/>Units: <B><xsl:value-of select="Units"/></B>
</P>
</xsl:template>
</xsl:stylesheet>
The style sheet used to format the Notification Services application’s output is
a standard XSLT style sheet. In the template section you can see where the StoreID,
Date, ProductID, ProductName, and Units fields from the NotificationClass are
displayed in the notification.
Building the Notifi cation Services Application

After the required XML and T-SQL application code has been created, you’re ready
to build the Notification Services application. Notification Services applications can
be created interactively using the SQL Server Management Studio, or they can be
created using the nscontrol utility. First, you’ll see how to create them using the SQL
Server Management Studio, and then you’ll see how you can create Notification
Services applications using the nscontrol commands in the batch file.
Chapter 5: Developing with Notification Services 153
Building Notification Services Applications Using SQL Server Management Studio
After the icf.xml and adf.xml files that define the Notification Services have been
created, you can use them to build your Notification Services application from the SQL
Server Management Studio by first opening the Object Browser and right-clicking
the Notification Services node. Then you can select the New Notification Services
Instance option from the context menu to display a screen like the one in Figure 5-3.
To create a new Notification Services application using the New Notification
Services Instance dialog, you click Browse and navigate to the directory that contains
your application’s instance configuration file. For this example that file is named
icf.xml, so next you select the icf.xml file and click OK. If you want the application
Figure 5-3 The New Notification Services Instance dialog
154 Microsoft SQL Server 2005 Developer’s Guide
to be immediately enabled after it is created, you need to check the Enable Instance
After It Is Created check box. Clicking OK generates the Notification Services
application and displays the summary dialog that you can see in Figure 5-4.
At this point, although the application has been created and enabled, it’s still
not ready to be used. Before it can be used, the application must be registered and
then started. Registering the application creates a Windows service, and starting the
application starts that service. To register the newly created Notification Services
application, open the SQL Server Management Studio and then, in Object Explorer,
expand the Notification Services node. Right-click the name of your Notification
Services application; in this example, the name is NSAppInstance. Select the Tasks
option and then select Register. Then select the Create Windows Service check box

and enter the account and password that will be used to start the Windows service.
If you use SQL Server Authentication, you’ll need to enter the SQL Server login
information as well. Otherwise, just use the default value of Windows Authentication
and then click OK. This will register the Notification Services instance, create the
Windows service, and create a set of performance counters for the application.
Figure 5-5 illustrates registering the Notification Services application.
After the Notification Services application has been registered, you can go ahead
and start the application. To do so, go to SQL Server Management Studio, open
Object Explorer, and navigate to the Notification Services node. Right-click your
application, in this example NSAppInstance, and then choose Start.
Figure 5-4 The Notification Services Creation Status dialog
Chapter 5: Developing with Notification Services 155
NOTE
If the Notification Services application doesn’t start, the most likely problem is the account used by
the Notification Services Windows service. Check to make sure you are using a valid account and it
has permissions to access the Notification Services databases. Otherwise, you will need to recheck
the values used in your ADF.
Building Notification Services Applications Using nscontrol
As an alternative to using the SQL Server Management Studio to create Notification
Services applications, you can use the nscontrol commands. A command-line tool
that’s used to create and administer Notification Services applications, nscontrol
Figure 5-5 Registering the Notification Services application
156 Microsoft SQL Server 2005 Developer’s Guide
understands a number of different action commands that you can use to work with
Notification Services applications. Table 5-1 lists the available nscontrol action
commands.
Creating a Notification Services application is a multistep process. First, the
application needs to be created using the nscontrol create command. This creates the
database used by the Notification Services application. Then the application needs
to be registered using the nscontrol register command. This creates the service that

is used to run the application. Finally, the application needs to be enabled using
the nscontrol enable command. The following batch file illustrates the command
sequence needed to create the example NSSample Notification Services application:
echo off
cls
set NSdir="C:\Program Files\Microsoft SQL Server\90\NotificationServices\9.0.242\bin"
echo ========================================
echo Beginning NSAppInstance Creation
echo ========================================
echo .
echo Create the application databases
%NSdir%\nscontrol create -in ICF.xml
echo Register the application
%NSdir%\nscontrol register -name NSAppInstance –service
nscontrol Command Description
nscontrol create Creates a Notification Services application and its databases.
nscontrol delete Deletes a Notification Services application and its databases.
nscontrol disable Disables a Notification Services application.
nscontrol displayargumentkey Displays the key used to encrypt event data.
nscontrol enable Enables a Notification Services application.
nscontrol listversions Displays the version of Notification Services and any registered applications.
nscontrol register Registers a Notification Services application.
nscontrol status Displays the status of a Notification Services application.
nscontrol unregister Unregisters a Notification Services application.
nscontrol update Updates a Notification Services application.
Table 5-1 Nscontrol Commands
Chapter 5: Developing with Notification Services 157
echo Enable the application
%NSdir%\nscontrol enable -name NSAppInstance
echo start the NS app as a service

net start NS$NSAppInstance
echo Display the status of the app
%NSdir%\nscontrol status -name NSAppInstance
The nscontrol create command’s –in argument specifies the name of the Notification
Services ICF. In this example, the ICF is named icf.xml. Running the nscontrol create
command creates two databases on the server, NSSampleInstanceMain and NSSamp
leInstanceNSSample, which store the Notification Services application definition and
data events.
The nscontrol register command uses the –name argument to identify the instance
name of the Notification Services application to register. The –service switch directs
it to register a service named NS$NSSampleInstance.
The nscontrol enable command uses the –name parameter to identify the instance
name of the application that will be enabled.
Once the application is enabled, its service can be started using the net start
command. For testing, you can also execute the NS$NSSampleInstance application
from the command prompt or the Run dialog.
Updating Notification Services Applications
Like all other applications, Notification Services applications need to be updated
and changed from time to time. To re-create the Notification Services application,
you could delete the entire application instance and then re-create, enable, and
register the application. However, in most cases there’s no need for that many steps.
Instead, to update a Notification Services application, you can make changes to your
application definition file and then save those changes. Next, open up SQL Server
Management Studio and then use Object Explorer to navigate to your Notification
Services application listed under the Notification Services node. First, disable the
application by right-clicking it and then selecting Disable. Next, right-click the
application again and then select Tasks | Update.
As you may have guessed, you can also update a Notification Services application
using the nscontrol commands.
158 Microsoft SQL Server 2005 Developer’s Guide

Building a .NET Subscription/Event Application
While the core logic of a Notification Services application is defined using the ICF
and the ADF files, subscribers, devices, and subscriptions are typically created by
client applications that use the Notification Services API. You can see an example
Notification Services client application in Figure 5-6.
The sample application shown in Figure 5-6 adds subscribers, devices, and
subscriptions to the Notification Services application using the Subscribers tab. The
Event tab is used to generate event data, and the Notification tab is used to display
the resulting notification.
Client applications connect to Notification Services using the managed code APIs
that Microsoft provides with SQL Server 2005 Notification Services. Microsoft’s
.NET Framework APIs enable you to add, update, and delete subscribers, as well
as subscriber devices and subscriptions. While the Notification Services API is
provided via managed code classes, you can also access the API from unmanaged
code by using Win32-based COM applications.
The Notification Services API is located in Microsoft.SqlServer.NotificationServices
.dll, which must be added to your .NET project as a reference. Then you can use the
Notification Services classes to manage subscriptions to your Notification Services
applications. To add a reference to the Notification Services API, select the Project |
Add Reference menu option to display the Add Reference dialog. Scroll through the
list until you see Microsoft.SqlServer.NotificationService, and then select the object,
as shown in Figure 5-7. Clicking OK adds the reference to your project.
Figure 5-6 The Subscription/Event application