Creating a Notification Class, Content Formatter, and Notification Class Protocol
A notification class named StockWatchNotifications, a content formatter named XsltFormatter, and two notification class protocols namedFileandSMTPare created in theCreateNotificationClass()method of Example 18-1. The code follows:
TheNotificationClass object represents a type of notification supported by a Notification Services application. ANotificationFieldobject represents a field in a notification class schema. The notification class in this example has two fields—Symbolof typenvarchar(6)andPriceof typefloat.
The NMO classes for managing notification classes and fields are described in Table 18-7.
Table 18-7. NMO classes for managing notification classes and fields
Class
Description
NotificationClass
Represents a notification class.
NotificationClassCollection
Represents a collection of notification classes as NotificationClassobjects. TheNotificationClasses property of theApplicationclass returns the notification classes for the Notification Services application.
NotificationComputedField
Represents a computed field in a notification class schema.
NotificationComputedFieldCollection
Represents a collection of computed fields as NotificationComputedFieldobjects. The NotificationComputedFieldsproperty of the NotificationClassclass returns the computed fields for the notification class.
NotificationField
Represents a noncomputed field in a notification class schema.
NotificationFieldCollection
Represents a collection of fields asNotificationFieldobjects. TheNotificationFieldsproperty of the NotificationClassclass returns the fields for the notification class.
A content formatter formats notifications for a notification class. Each notification class has one content formatter that can perform different formatting based on field values in the notification. The content formatter takes three arguments:
XsltBaseDirectoryPath The root directory for all XSLT files.
XsltFileName The name of the XSLT file used to transform raw notification data into formatted data for notification delivery.
DisableEscaping An optional Boolean argument indicating that the event data contains either HTML or XML data preventing further transformation. The default value isfalse.
The NMO classes for managing content formatters are described in Table 18-8.
Table 18-8. NMO classes for managing content formatters
Class
Description
ContentFormatter
Represents a content formatter. TheContentFormatterproperty of theNotificationClassclass returns the content formatter for the notification class.
ContentFormatterArgument
Represents a name-value pair for a content formatter initialization argument.
ContentFormatterArgumentCollection
Represents a collection of initialization arguments as ContentFormatterArgumentobjects. The ContentFormatterArgumentsproperty of the ContentFormatterclass returns the initialization arguments for the content formatter.
A notification class protocol represents a delivery protocol for a notification class. AProtocolFieldobject represents a protocol header field used by some delivery protocols. Protocol field headers are different for file and email notification—examine the code and examine the file and email notifications shown in Figure 18-7 and Figure 18-8 to see the result of setting the protocol fields. The value of theProtocolField object is set using either theSqlExpressionorFieldReferenceproperty. This lets you use either a T-SQL expression or a notification field to define a protocol field value.
The NMO classes for managing protocols are described in Table 18-9.
Table 18-9. NMO classes for managing protocols
Class
Description
NotificationClassProtocol
Represents a delivery protocol for a notification class.
NotificationClassProtocolCollection
Represents a collection of notification class protocols as NotificationClassProtocolobjects. The NotificationClassProtocolsproperty of the NotificationClassclass returns the delivery classes for the notification class.
ProtocolDefinition
Represents a custom delivery protocol.
ProtocolDefinitionCollection
Represents a collection of custom delivery protocols as ProtocolDefinitionobjects. TheProtocolDefinitions property of theInstanceclass returns the custom delivery protocols for the Notification Services instance.
ProtocolField
Represents a protocol header field.
ProtocolFieldCollection
Represents a collection of protocol header fields asProtocolField objects. TheProtocolFieldsproperty of the NotificationClassProtocolclass returns the protocol header fields for the delivery protocol.
ProtocolRetrySchedule
Represents a retry schedule interval.
ProtocolRetryScheduleCollection
Represents a collection of retry schedule intervals as ProtocolRetryScheduleobjects. The ProtocolRetrySchedulesproperty of the NotificationClassProtocolclass returns the retry schedules for notifications sent using the delivery protocol.
Event providers collect event data and submit it to an event class. Hosted event providers are run by the Notification Services engine. Nonhosted event providers, on the other hand, run outside of the engine, and have no interaction with Notification Services.
TheClassNameproperty of theHostedEventProviderclass specifies the class that implements the event provider. Notification Services has three built-in event providers, described in the “Architecture” section earlier in this chapter. You can also use a custom event provider. This example uses the File System Watcher event provider (with aClassNameofFileSystemWatcherProvider), which gathers events of the StockWatchEvents event class from a file in the C:\PSS2005\NotificationServices\ Events directory. The event file must conform to the schema defined in the C:\PSS2005\NotificationServices\AppDefinition\EventsSchema.xsd file.
The NMO classes for managing hosted and nonhosted event providers are described in Table 18-10.
Table 18-10. NMO classes for managing hosted and nonhosted event providers
Class
Description
HostedEventProvider
Represents a hosted event provider for a Notification Services application.
HostedEventProviderArgument
Represents a name-value pair specifying hosted event provider configuration.
HostedEventProviderArgumentCollection
Represents a collection of hosted event provider arguments as HostedEventProviderArgumentobjects. The HostedEventProviderArgumentsproperty of the HostedEventProviderclass returns the hosted event provider arguments for the hosted event provider.
HostedEventProviderCollection
Represents a collection of hosted event providers as HostedEventProviderobjects. The HostedEventProvidersproperty of theApplication class returns the hosted event providers for the Notification Services application.
NonHostedEventProvider
Represents a nonhosted event provider.
NonHostedEventProviderCollection
Represents a collection of nonhosted event providers as NonHostedEventProviderobjects. The NonHostedEventProvidersproperty of theApplication class returns the nonhosted event providers for the Notification Services application.
A generator named StockWatchGenerator is created in the CreateGenerator() method of Example 18-1. The code follows:
private static void CreateGenerator() { // create a new generator for the application Generator g = new Generator(a, "StockWatchGenerator"); g.SystemName = nsServer; a.Generator = g;
TheGeneratorobject represents the generator for a Notification Services application. TheGenerator property of theApplication class returns the generator for the application. You have to specify theGeneratorproperty of theApplicationobject before adding the application to the Notification Services instance. An application has only one generator, which handles rule processing for the application.
TheSystemNameproperty of theGenerator class must be specified, and cannot be any of the following:localhost,., an IP address, or any string containing a backslash (\).
Creating a Distributor
A distributor named StockWatchDistributor is created in the CreateDistributor() method of Example 18-1. The code follows:
private static void CreateDistributor() { Distributor d = new Distributor(a, "StockWatchDistributor"); d.SystemName = nsServer; d.QuantumDuration = new TimeSpan(0, 0, 15); a.Distributors.Add(d);
TheDistributor object represents a distributor for a Notification Services application. Each application must have one distributor that controls formatting and distribution of notifications. If an application has multiple distributors, each one must be installed on a different server. TheQuantumDurationproperty specifies the distributor work item polling interval, which is 15 seconds in this example.
The NMO classes for managing distributors are described in Table 18-11.
Table 18-11. NMO classes for managing distributors
Class
Description
Distributor
Represents a distributor for a Notification Services application.
DistributorCollection
Represents a collection of distributors asDistributorobjects. TheDistributors property of theApplicationclass returns the distributors used to distribute notifications to delivery channels for the Notification Services application.
Vacuuming removes old event and notification data from the application database on a daily schedule. TheStartTimeproperty specifies the daily time in Universal Coordinated Time (UTC) for the data removal process to start. Although specifying a vacuum schedule is optional, old data is not removed from the database if a vacuum schedule is not specified.
The NMO classes for managing vacuum schedules are described in Table 18-12.
Table 18-12. NMO classes for managing vacuum schedules
Class
Description
VacuumSchedule
Represents a data removal schedule.
VacuumScheduleCollection
Represents a collection of data removal schedules asVacuumScheduleobjects. The VacuumSchedulesproperty of theApplicationclass returns the data removal schedules for the application.
Creating a Subscriber and Subscriber Device
Two subscribers, each with a single subscriber device, are created in the CreateSubscriber() method of Example 18-1. The code follows:
private static void CreateSubscriber() { ns.NSInstance swnsi = new ns.NSInstance("StockWatch");
ns.Subscriber s; ns.SubscriberDevice sd;
// create a subscriber s = new ns.Subscriber(swnsi); s.SubscriberId = @"KristinHamilton"; s.Add(); Console.WriteLine("Added subscriber: " + s.SubscriberId);
TheNSInstanceclass represents a Notification Services instance that is registered in the Windows registry.
TheSubscriberclass represents a subscriber in a Notification Services instance. TheSubscriberEnumerationclass represents a collection of subscribers asSubscriberobjects in a Notification Services instance.
TheSubscriberEnumerationclass is used to retrieve aSubscriber object from the collection of subscribers to the Notification Services instance. TheDelete()method removes a subscriber, theAdd()method adds a subscriber, and theUpdate()method updates the information for an existing subscriber. The following code deletes the subscriberAnySubscriberfrom a Notification Service instance namedHelloWorld:
NSInstance nins = new NSInstance("HelloWorld"); SubscriberEnumeration se = new SubscriberEnumeration(nins); se["AnySubscriber"].Delete();
TheSubscriberDeviceclass represents a device that can receive notifications. A single subscriber device is added to each subscriber. Each subscriber device specifies the following properties:
DeviceName The name of the subscriber device.
SubscriberId The ID of the subscriber with which the subscriber device is associated.
DeviceTypeName The name of the device type for the subscriber device.
DeviceAddress The address used to contact the device.
DeliveryChannelName The name of the delivery channel that the device uses. This example assigns the StockWatchFileDeliveryChanneldelivery channel to one subscriber and the StockWatchEmailDeliveryChanneldelivery channel to the other—these delivery channels are created in the code described in the “Creating a Delivery Channel” section earlier in this chapter.
TheSubscriberDeviceEnumerationclass is used to retrieve aSubscriberDevice object from the collection of devices for a subscriber. TheDelete()method removes a device, theAdd()method adds a device, and theUpdate()method updates the information for an existing device.
TheNSApplication class represents a Notification Services application. TheSubscriptionclass represents a subscription in a Notification Services application. Both subscriptions use the subscriber device namedStockWatchSubscriberDevicecreated in the “Creating a Subscriber and Subscriber Device” section earlier in this chapter. The subscription forKristinHamilton is for events for ticker symbolABC, while the subscription for subscriberTonyHamilton is for events for ticker symbolDEF. The results can be seen in the notifications shown in Figures 18-7 and 18-8.
TheSubscriptionEnumeration class represents a collection of subscriptions asSubscription objects in a Notification Services application. Use the SubscriptionEnumerationclass to iterate over a collection of subscriptions for an application and manage the individual subscriptions in the collection. These two classes are implemented in the Microsoft.SqlServer.NotificationServices namespace.
This example enumerates the filegroup, database files, and logfiles for the StockWatch Notification Services instance created in Example 18-1:
using System;
using Microsoft.SqlServer.Management.Smo; using Microsoft.SqlServer.Management.Nmo;
class Program { static void Main(string[] args) { Server server = new Server("(local)"); NotificationServices ns = server.NotificationServices; Instance ins = ns.Instances["StockWatch"];
Console.WriteLine(Environment.NewLine + "Press any key to continue."); Console.ReadKey(); } }
Results are shown in Figure 18-9.
Each Notification Services instance has one database that can optionally contain one or more filegroups. If you define filegroups, one must be calledPRIMARY. Use SQL Server Management Studio if you need to alter the Notification Services instance database after creating the instance.
Figure 18-9. Results for enumerating a Notification Services instance database example
The NMO classes for managing the instance database, filegroups, files, and logfiles are described in Table 18-13.
Table 18-13. NMO classes for managing instance databases
Instance
Description
InstanceDatabaseFile
Represents an instance database file.
InstanceDatabaseFileCollection
Represents a collection of instance databases as InstanceDatabaseobjects. TheInstanceDatabaseFiles property of theInstanceDatabaseFileGroupclass returns the instance databases in the instance database filegroup.
InstanceDatabaseFileGroup
Represents an application database filegroup.
InstanceDatabaseFileGroupCollection
Represents a collection of instance database filegroups as InstanceDatabaseFileGroupobjects. TheInstance-DatabaseFileGroupsproperty of theInstanceDatabase-Optionsclass returns the instance database filegroups in the application.
InstanceDatabaseLogFile
Represents an instance database logfile.
InstanceDatabaseLogFileCollection
Represents a collection of instance database logfiles asInstance-DatabaseLogFileobjects. TheInstanceDatabase-LogFilesproperty of theInstanceDatabaseOptionsclass returns the instance database logfiles in the application.
InstanceDatabaseOptions
Represents database options for the instance database. The InstanceDatabaseOptionsproperty of theInstanceclass returns the database properties for the instance.
This example enumerates the filegroup, database files, and logfiles for the HelloWorldApp Notification Services application created in Example 18-1:
using System;
using Microsoft.SqlServer.Management.Smo; using Microsoft.SqlServer.Management.Nmo;
class Program { static void Main(string[] args) { Server server = new Server("(local)"); NotificationServices ns = server.NotificationServices; Instance ins = ns.Instances["StockWatch"]; Application a = ins.Applications["StockWatchApp"];
Console.WriteLine(Environment.NewLine + "Press any key to continue."); Console.ReadKey(); } }
Results are shown in Figure 18-10.
Figure 18-10. Results for enumerating a Notification Services application database example
Each Notification Services application has one database that can optionally contain one or more filegroups. If you define filegroups, one must be calledPRIMARY. Use SQL Server Management Studio if you need to alter the application database after creating the instance.
The NMO classes for managing the application database, filegroups, files, and logfiles are described in Table 18-14.
Table 18-14. NMO classes for managing application databases
Class
Database
ApplicationDatabaseFile
Represents an application database file.
ApplicationDatabaseFileCollection
Represents a collection of application databases as ApplicationDatabaseFileobjects. The ApplicationDatabaseFilesproperty of the ApplicationDatabaseFileGroupclass returns the application databases in the application database filegroup.
ApplicationDatabaseFileGroup
Represents an application database filegroup.
ApplicationDatabaseFileGroupCollection
Represents a collection of application database filegroups as ApplicationDatabaseFileGroupobjects. The ApplicationDatabaseFileGroupsproperty of the ApplicationDatabaseOptionsclass returns the application database filegroups in the application.
ApplicationDatabaseLogFile
Represents an application database logfile.
ApplicationDatabaseLogFileCollection
Represents a collection of application database logfiles as ApplicationDatabaseLogFileobjects. The ApplicationDatabaseLogFilesproperty of the ApplicationDatabaseOptionsclass returns the application database logfiles in the application.
ApplicationDatabaseOptions
Represents database options for the application database. The ApplicationDatabaseOptionsproperty of the Applicationclass returns the database properties for the application.