Using NMO to Administer an Instance

Most capabilities of nscontrol and the SQL-NS commands in Management Studio are available through NMO. In fact, the administration operations exposed in NMO share a common implementation with these standard SQL-NS tools. Invoking an operation via NMO is equivalent to invoking the corresponding nscontrol or Management Studio command. This means you can "mix and match" the use of NMO with the standard tools: an instance created via NMO can be managed with the standard tools, and vice versa.

Only two SQL-NS administration operations are not exposed in NMO:

• RepairThe operation that rebuilds instance metadata in the system tables (available only through nscontrol)

• UpgradeConverting a compiled instance from a previous version of SQL-NS to the current version (available in both nscontrol and Management Studio)

All other administration operations (for example, registering an instance and enabling its components) can be invoked via methods on NMO classes. This section explains these methods and shows examples of their use.

Note

This section does not cover the use of NMO to update instances, because the NMO update process is based on concepts that are not introduced until the later section "Using NMO to Reflect the Contents of an Instance" (p. 555). Performing updates with NMO is covered near the end of this chapter, in the sidebar "Updating an Instance with NMO" (p. 563).

Registering an Instance with NMO

Registering an instance creates its Registry keys and performance counters, and, optionally, installs its Windows service. Using the standard tools, instances are registered with nscontrol register or the Register Instance command in Management Studio.

Using NMO, an instance is registered by calling one of the RegisterLocal() methods on its Instance object. Listing 16.6 shows the implementation of the Register() method of the StockBrokerNMO class, which calls the RegisterLocal() method on the Instance object created by the code shown earlier in Listing 16.4.

Listing 16.6. The Register() Method of the StockBrokerNMO Class

 public class StockBrokerNMO {    ...    public void Register()    {        if (AuthenticationMode.WindowsAuthentication ==            serviceAuthenticationMode)        {            // Register with just the Windows username            // and password.            instance.RegisterLocal(                serviceUserName,                servicePassword);        }        else        {            // Register with both the Windows username            // and password, as well as the SQL username            // and password.            instance.RegisterLocal(                serviceUserName,                servicePassword,                serviceSqlUserName,                serviceSqlPassword);        }      }      ...   } 

One of two RegisterLocal() overloads is called, depending on the authentication mode the SQL-NS Windows service should be configured to use. The desired authentication mode is stored in the serviceAuthenticationMode private member variable by the StockBrokerNMO constructor. If this member variable specifies Windows Authentication, the code in Listing 16.6 calls the Instance object's RegisterLocal() method that takes a Windows username and password. This registers the instance and installs the service, configuring it to run with the specified Windows credentials. At runtime, the service will connect to the SQL Server using Windows Authentication.

If the service should use SQL Server Authentication, the code in Listing 16.6 calls an overload of RegisterLocal() that takes a SQL username and password, in addition to the Windows username and password. Again, the instance is registered and the service is configured to run under the given Windows credentials. But the supplied SQL username and password are also stored in the Registry (in an encrypted form). At runtime, the service uses this SQL username and password to connect via SQL Server Authentication.

Note

In addition to the two shown in Listing 16.6, the Instance class also provides other RegisterLocal() overloads, some of which don't install the SQL-NS service. When the service isn't needed (for example, when registering an instance on the machine that hosts only a subscription management interface), you can call one of these alternative overloads instead of the ones shown in Listing 16.6. See the reference for the Instance class in the SQL-NS Books Online for complete documentation on all variants of the RegisterLocal() method.

Besides installing the SQL-NS service and the performance counters, the main purpose of registering an instance is to record the name of the SQL Server that hosts the instance and application databases. At runtime, the SQL-NS engine (and parts of the SQL-NS API) locate the databases by looking up this SQL Server name in the Registry. We looked at how the SQL Server name is stored in the Registry when we first examined the registration process in Chapter 4, "Working with SQL-NS Instances," (see the "Registry Keys" section, p. 100).

When you register an instance with nscontrol register, you are required to specify the SQL Server name as one of the command-line arguments. But notice that the SQL Server name is not specified anywhere in the calls to the RegisterLocal() methods shown in Listing 16.6. This is because the SQL Server name is obtained from the Server object to which the Instance object is linked via its parent chain (recall that the parent of an Instance object is a NotificationServices object attached to a Server object).

Note

The Instance class also provides static overloads of the RegisterLocal() method that take the name of the SQL Server as an argument. You can use these static methods to register an instance created on any SQL Server, without creating an Instance object to represent it. This is possible because instance registration does not require a connection to the SQL Server. See the class reference for Instance in the SQL-NS Books Online for details on these static RegisterLocal() methods.

The name of the RegisterLocal() method was chosen to emphasize the fact that it registers the instance on the local machine, not the machine hosting the SQL Server to which the Instance object is linked. In other words, all Registry keys and performance counters are created only on the machine running the NMO code, regardless of where the SQL Server may be located.

Enabling an Instance with NMO

To enable a whole instance with NMO, you call its Instance object's Enable() method. This is shown in Listing 16.7, in the context of the StockBrokerNMO example.

Listing 16.7. The Enable() Method of the StockBrokerNMO Class

    public class StockBrokerNMO    {         ...         public void Enable()         {             instance.Enable();         }         ...    } 

In addition to enabling a whole instance, NMO also supports enabling components of an instance selectively. The Instance class has methods, EnableSubscribers() and EnableSubscriptions(), which you can use to enable just subscriber and subscription management, respectively. Other components can be enabled via methods on their corresponding NMO classes. Specifically, the Application, HostedEventProvider, Generator, and Distributor classes all provide Enable() methods.

Calling the Enable() method on an Application object enables all components in the application it represents. The Application class also defines an EnableSubscriptions() method to enable only subscription management in the application. Calling the Enable() method on an object that represents a component of an application (for example, a Distributor object) enables only that component.

For all methods that enable components, NMO provides corresponding methods that disable the same components. Specifically, all classes that have Enable() methods also have Disable() methods. These methods behave symmetrically: whatever a particular class's Enable() method enables, its Disable() method disables. Similarly, methods such as EnableSubscribers() and EnableSubscriptions() have corresponding DisableSubscribers() and DisableSubscriptions() counterparts.

Deleting and Unregistering an Instance with NMO

NMO provides methods on the Instance class for unregistering and deleting an existing SQL-NS instance. Listing 16.8 shows these methods used in the cleanup code that runs at the start of the sample application. This code unregisters and then removes any existing copy of the StockBrokerNMO instance that may have been created by a previous run of the program.

Listing 16.8. The Cleanup() Method of the StockBrokerNMO Class

 public class StockBrokerNMO {     ...     public void Cleanup()     {         // Get the collection of existing instances.         InstanceCollection existingInstances =             server.NotificationServices.Instances;        // Check if the StockBrokerNMO instance is contained        // within the collection of existing instances.        if (existingInstances.Contains(InstanceName))     {        // Get the instance object.        Instance existingInstance =            existingInstances[InstanceName];        // Unregister the instance.        existingInstance.UnregisterLocal();       // Drop the instance.       existingInstance.Drop();     }   }   ... } 

The cleanup method first checks whether the instance exists by examining the collection of instances on the server's NotificationServices property. If this instance collection contains an object with our instance's name, the instance already exists. The Instance object for this existing instance is obtained from the instances collection, using the instance name as an index into the collection.

After the instance object is obtained, the code then calls its UnregisterLocal() method to remove the instance's registration. It then calls the Drop() method to remove the instance completely.

The Drop() method performs the same operations as nscontrol delete and the Delete Instance command in Management Studio: it deletes all database objects the SQL-NS compiler created for the instance. As such, it may take several minutes to complete.

Tip

The technique for obtaining an existing Instance object, shown in Listing 16.8, is a common pattern in NMO programming. Unlike the Create(), Register(), and Enable() methods, which are usually invoked on new Instance objects created to define a new instance, the UnregisterLocal() and Drop() methods are usually called on Instance objects that represent existing instances. This is also true of the Disable() method (explained briefly in the "Enabling an Instance with NMO" section, p. 552) and the Update() method (described in the sidebar "Updating an Instance with NMO," p. 563, later in this chapter). Whenever you need to call these methods, you'll probably use the standard pattern shown in Listing 16.8 to first obtain the existing Instance object.