Hosting the Notification Services Engine

For each Notification Services instance, Notification Services 2.0 required you to install a Windows service on each server that ran a hosted event provider, generator, or distributor. For developers who wanted to redistribute notification applications, this added one or more Windows services to their deployments, and created one more service to manage.

In SQL Server 2005, you can host the Notification Services engine from within your own applications or processes. If you host the engine, you do not install the NS$instanceName Windows service to run engine components. This simplifies embedding Notification Services solutions in your applications.

Hosting the Notification Services Engine

Notification Services provides a very simple API for hosting the Notification Services engine. Simply instantiate the NSInstance class, providing the name of the instance you want to host. Then call the StartInstance method to start the engine. To stop the engine, call the StopInstance method. The following example shows the code required to stop and start the engine:

try
{
    // Instantiate the Notification Services instance.
    NSInstance nsInstance = new NSInstance("FlightInstance");

    // Start the instance.
    Console.WriteLine("Starting instance...");
    nsInstance.StartInstance();

    // Check the IsRunning property to verify that 
    // this process is running the instance.
    if (nsInstance.IsRunning == true)
        Console.WriteLine("The instance is running.");
    else
        Console.WriteLine("The instance is NOT running!");

    // Stop instance.
    Console.WriteLine("Stopping instance...");
    nsInstance.StopInstance();

}
catch (Exception ex)
{
    // Write exception message to the console.
    Console.WriteLine(ex.Message);
}

Handling Errors

While the instance is running, it may encounter run-time errors. These errors are reported back to the hosting process through a ErrorEventHandler delegate that is invoked when the Error event is triggered. When the event is raised, the delegate is called to notify the host, and the instance is stopped.

The following example shows how to respond to this event:

// Define an error handler for the hosted execution engine.
private void InstanceErrorHandler(object sender, ErrorEventArgs e)
{
    Console.WriteLine (e.GetException ().ToString ());
}

// Start and stop the hosted execution engine.
public void ErrorHandlingStartStop()
{
    try
    {
        // Instantiate the Notification Services instance.
        NSInstance nsInstance = new NSInstance("FlightInstance");

        // Add an error handler to the instance.
        nsInstance.Error += 
            new NSInstance.ErrorEventHandler(InstanceErrorHandler);

        // Start the instance.
        Console.WriteLine("Starting instance...");
        nsInstance.StartInstance();

        // Check the IsRunning property to verify that 
        // this process is running the instance.
        if (nsInstance.IsRunning == true)
            Console.WriteLine("The instance is running.");
        else
            Console.WriteLine("The instance is NOT running!");


        // Stop the instance.
        Console.WriteLine("Stopping instance...");
        nsInstance.StopInstance();
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.Message);
    }
}

The sender is the NSInstance object.

Running an Instance of Notification Services

To run the engine that runs hosted event providers, generators, and distributors on the local computer, you must do the following:

• You must install the Notification Services engine components on each server that runs a hosted event provider, generator, or distributor.
• You must register the instance on each of these servers. When registering the instance, you do not need to create the Windows service. Your hosted engine can take the place of the Windows service.
• You must install your application on each of these servers.
• You must call your code that instantiates and starts the instance on each of these servers.

If you install the Windows service, note that you cannot start the Windows service and then start the instance in your application at the same time. Only one thread of one process can "own" the instance at any one time.

If you start the NS$instanceName Windows service, and then attempt to start the instance in your application, Notification Services will throw an exception and your application will not start the instance. The reverse is also true: If your application is running the instance, and then you attempt to start the Windows service, the Windows service will fail to start.

If the thread that owns the instance's engine on that server fails, other threads within that process can take ownership of the instance.

Security Requirements

Your application or process is controlling the operation of hosted event providers, generators, and distributors, and must have the appropriate Windows and database permissions for performing the related work. This includes membership in the SQLServer2005NotificationServicesUser$ComputerName Windows group and membership in the appropriate Notification Services database role or roles. For more information on the permissions required to run an instance of Notification Services, see Configuring Windows Accounts for an Instance of Notification Services and Configuring SQL Server Permissions for an Instance of Notification Services.

Embedding Notification Services Components

If you are embedding Notification Services in your application, make sure to include the following assemblies:

• Microsoft.SqlServer.NotificationServices.dll
• Microsoft.SqlServer.Smo.dll
• nscontrol.exe

Refer to your SQL Server 2005 licensing agreement on the redistribution of SQL Server 2005 components.

See Also

Concepts

Security Considerations for Notification Services
Configuring Windows Accounts for an Instance of Notification Services
Configuring SQL Server Permissions for an Instance of Notification Services

Other Resources

Deploying Notification Services

Help and Information

Getting SQL Server 2005 Assistance