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="http://www.w3.org/1999/XSL/Transform"> <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 . <FieldName>Date</FieldName> <FieldType>datetime</FieldType> </Field> 150 Microsoft SQL Server 2005 Developer’s Guide <Field> <FieldName>ProductID</FieldName> <FieldType>int</FieldType> . 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. 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