Creating Important Aspects of Notification Services

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 named FileandSMTPare created in theCreateNotificationClass()method of Example 18-1. The code follows:

  private static void CreateNotificationClass() 
  {
     NotificationClass nc = new NotificationClass(a, "StockWatchNotifications");

     NotificationField nf;
     nf = new NotificationField(nc, "Symbol");

     nf.Type = "nvarchar(6)";
     nc.NotificationFields.Add(nf);
     nf = new NotificationField(nc, "Price");
     nf.Type = "float";
     nc.NotificationFields.Add(nf);

     ContentFormatter cf = new ContentFormatter(nc, "XsltFormatter");

     ContentFormatterArgument cfa;
     cfa = new ContentFormatterArgument(cf, "XsltBaseDirectoryPath");
     cfa.Value = a.BaseDirectoryPath + @"\AppDefinition";
     cf.ContentFormatterArguments.Add(cfa);
     cfa = new ContentFormatterArgument(cf, "XsltFileName");
     cfa.Value = "StockWatch.xslt";
     cf.ContentFormatterArguments.Add(cfa);

     nc.ContentFormatter = cf;
     nc.DigestDelivery = true;

     ProtocolField pf;

     // add file notification class protocol
     NotificationClassProtocol ncpFile =
         new NotificationClassProtocol(nc, "File");

     pf = new ProtocolField(ncpFile, "Symbol");
     pf.FieldReference = "Symbol";
     ncpFile.ProtocolFields.Add(pf);
     pf = new ProtocolField(ncpFile, "Price");
     pf.FieldReference = "Price";
     ncpFile.ProtocolFields.Add(pf);

     nc.NotificationClassProtocols.Add(ncpFile);

     // add email notification class protocol
     NotificationClassProtocol ncpEmail =
         new NotificationClassProtocol(nc, "SMTP");

     pf = new ProtocolField(ncpEmail, "Subject");
     pf.SqlExpression = "'Stock watch: ' + CONVERT(nvarchar(30), GETDATE())";
     ncpEmail.ProtocolFields.Add(pf);
     pf = new ProtocolField(ncpEmail, "BodyFormat");
     pf.SqlExpression = "'html'";
     ncpEmail.ProtocolFields.Add(pf);
     pf = new ProtocolField(ncpEmail, "From");
     pf.SqlExpression = 'notification@StockWatchService.com';
     ncpEmail.ProtocolFields.Add(pf);
     pf = new ProtocolField(ncpEmail, "Priority");
     pf.SqlExpression = "'Normal'";
     ncpEmail.ProtocolFields.Add(pf);
     pf = new ProtocolField(ncpEmail, "To");
     pf.SqlExpression = "DeviceAddress";
     ncpEmail.ProtocolFields.Add(pf);

     nc.NotificationClassProtocols.Add(ncpEmail);

     nc.ExpirationAge = new TimeSpan(1, 0, 0);

     a.NotificationClasses.Add(nc);

     Console.WriteLine("Added notification class: " + nc.Name);
  }

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.

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.

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

Creating an Event Provider

A hosted event provider is created in the CreateHostedEventProvider() method of Example 18-1. The code follows:

  private static void CreateHostedEventProvider()
  {
     HostedEventProvider hep =
       new HostedEventProvider(a, "StockWatchHEP");
     hep.ClassName = "FileSystemWatcherProvider";
     hep.SystemName = nsServer;

     HostedEventProviderArgument hepa;
     hepa =
   new HostedEventProviderArgument(hep, "WatchDirectory");
     hepa.Value = baseDirectoryPath + @"\Events";
     hep.HostedEventProviderArguments.Add(hepa);
     hepa = 
       new HostedEventProviderArgument(hep, "SchemaFile");
     hepa.Value = baseDirectoryPath + @"\AppDefinition\EventsSchema.xsd";
     hep.HostedEventProviderArguments.Add(hepa);
     hepa =
   new HostedEventProviderArgument(hep, "EventClassName");
     hepa.Value = "StockWatchEvents";
     hep.HostedEventProviderArguments.Add(hepa);

     a.HostedEventProviders.Add(hep);
  }

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.

Creating a Generator

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;

     Console.WriteLine("Created generator: " + g.Name);
  }

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);

      Console.WriteLine("Added distributor: " + d.Name);
  }

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.

Creating a Vacuum Schedule

A vacuum schedule named StockWatchVacuumSchedule is created in the CreateVacuumSchedule() method of Example 18-1. The code follows:

  private static void CreateVacuumSchedule()
  {
      VacuumSchedule vs = new VacuumSchedule(a, "StockWatchVacuumSchedule");
      vs.StartTime = new TimeSpan(0, 0, 0);
      a.VacuumSchedules.Add(vs);

      Console.WriteLine("Added vacuum schedule: " + vs.Name);
  }

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.

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);

     // create a file subscriber device
     sd = new ns.SubscriberDevice();
     sd.Initialize(swnsi);
     sd.DeviceName = "StockWatchSubscriberDevice";
     sd.SubscriberId = "KristinHamilton";
     sd.DeviceTypeName = "File";
     sd.DeviceAddress = KristinH@StockWatch.ns;
     sd.DeliveryChannelName = "StockWatchFileDeliveryChannel";
     sd.Add();
     Console.WriteLine("Added subscriber file device.");

     // create a subscriber
     s = new ns.Subscriber(swnsi);
     s.SubscriberId = @"TonyHamilton";
     s.Add();
     Console.WriteLine("Added subscriber: " + s.SubscriberId);

     // create an email subscriber device
     sd = new ns.SubscriberDevice();
     sd.Initialize(swnsi);
     sd.DeviceName = "StockWatchSubscriberDevice";
     sd.SubscriberId = "TonyHamilton";
     sd.DeviceTypeName = "Email";
     sd.DeviceAddress = TonyH@StockWatchNS.ns;
     sd.DeliveryChannelName = "StockWatchEmailDeliveryChannel";
     sd.Add();
     Console.WriteLine("Added subscriber
email device.");
  }

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.

Creating a Subscription

Two subscriptions are created in the CreateSubscription() method of Example 18-1. The code follows:

  private static void CreateSubscription()
  {
     ns.NSInstance swnsi = new ns.NSInstance("StockWatch");
     ns.NSApplication a = new ns.NSApplication(swnsi, "StockWatchApp");

     ns.Subscription s;

     // add subscriptions
     s = new ns.Subscription();
     s.Initialize(a, "StockWatchSubscriptions");
     s.SetFieldValue("DeviceName", "StockWatchSubscriberDevice");
     s.SetFieldValue("SubscriberLocale", "en-us");
     s.SubscriberId = "KristinHamilton";
     s.SetFieldValue("Symbol", "ABC");
     s.SetFieldValue("Price", "0.00");
     s.Add();
     Console.WriteLine("Added subscription: " + s.SubscriberId);

     s = new ns.Subscription();
     s.Initialize(a, "StockWatchSubscriptions");
     s.SetFieldValue("DeviceName", "StockWatchSubscriberDevice");
     s.SetFieldValue("SubscriberLocale", "en-us");
     s.SubscriberId = "TonyHamilton";
     s.SetFieldValue("Symbol", "DEF");
     s.SetFieldValue("Price", "0.00");
     s.Add();
     Console.WriteLine("Added subscription: " + s.SubscriberId);
  }

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.

Enumerating a Notification Services Instance Database

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"];

         InstanceDatabaseOptions ido = ins.InstanceDatabaseOptions;
         Console.WriteLine("INSTANCE DATABASE OPTIONS:");
         Console.WriteLine(" Name: " + ido.Name);
         Console.WriteLine(" DefaultFileGroup: " + ido.DefaultFileGroup);

         Console.WriteLine(Environment.NewLine + "FILE GROUPS:");
         foreach (InstanceDatabaseFileGroup idfg in ido.InstanceDatabaseFileGroups)
         {
            Console.WriteLine(" Name: " + idfg.Name);

            Console.WriteLine(Environment.NewLine + "DATABASE FILES");
            foreach (InstanceDatabaseFile idf in idfg.InstanceDatabaseFiles)
                Console.WriteLine(" Name: " + idf.Name);
         }

         Console.WriteLine(Environment.NewLine + "LOG FILES:");
         foreach (InstanceDatabaseLogFile idlf in ido.InstanceDatabaseLogFiles) 
             Console.WriteLine(" Name: " + idlf.Name);

         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.

Enumerating a Notification Services Application Database

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"];

        ApplicationDatabaseOptions ado = a.ApplicationDatabaseOptions;
        Console.WriteLine("APPLICATION DATABASE OPTIONS:");
        Console.WriteLine(" Name: " + ado.Name);
        Console.WriteLine(" DefaultFileGroup: " + ado.DefaultFileGroup);

        Console.WriteLine(Environment.NewLine + "FILE GROUPS:");
        foreach (ApplicationDatabaseFileGroup adfg in 
         ado.ApplicationDatabaseFileGroups)
        {
           Console.WriteLine(" Name: " + adfg.Name);

           Console.WriteLine(Environment.NewLine + "DATABASE FILES");
           foreach (ApplicationDatabaseFile adf in adfg.ApplicationDatabaseFiles)
              Console.WriteLine(" Name: " + adf.Name);
        }

        Console.WriteLine(Environment.NewLine + "LOG FILES:");
        foreach (ApplicationDatabaseLogFile adlf in
           ado.ApplicationDatabaseLogFiles)
           Console.WriteLine(" Name: " + adlf.Name);

        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.