Overview of the NMO API
| The NMO API provides programmatic access to the following SQL-NS functions:
This section provides an overview of the NMO API's class structure. The use of NMO for each of the specific functions in the preceding list is detailed in the subsequent major sections of this chapter. Defining and creating instances with NMO is covered in the section "Using NMO to Define and Create an Instance" (p. 537). The section "Using NMO to Administer an Instance" (p. 549) covers several of the other operations listed in the second bullet item: registering, enabling, disabling, updating, and deleting SQL-NS instances. Finally, the enumeration capabilities of the API are explained in the section "Using NMO to Reflect the Contents of an Instance" (p. 555). Note In learning NMO, you'll encounter very few new SQL-NS concepts. Rather, you'll learn new, programmatic mechanisms for doing familiar tasks. NMO is part of a larger API framework called SQL Server Management Objects (SMO). SMO provides programmatic management capabilities for the fundamental SQL Server entities, such as databases, indexes, security roles, and file groups. In the case of databases, for example, classes in the SMO API encapsulate such management operations as backup and restore. NMO is the subset of SMO that provides management capabilities specific to SQL-NS instances. For documentation on SMO in general, consult the SQL Server Books Online. The NMO API is distinct from the other parts of the SQL-NS API you've already seen (the classes and interfaces used to build subscription management interfaces, event providers, content formatters, and delivery protocols). Classes in the NMO API are defined in a different namespace than the other SQL-NS API classes, and their implementations are packaged in a separate assembly. The section "NMO API Assemblies and Namespaces" (p. 532) describes the assemblies and namespaces you'll reference during NMO development. Classes in the NMO APIThe classes in the NMO API represent the entities that make up a SQL-NS instance. For example, the API contains classes that encapsulate delivery channels, protocols, applications, event classes, and so on. These classes are arranged in a containment hierarchy that reflects the structure of the elements in the ICF and ADF schemas. This hierarchy is shown in Figure 16.1. In the figure, collections are represented by three stacked boxes. Singletons appear as single boxes. Figure 16.1. Classes in the NMO API. Note In Figure 16.1, some class names are split across multiple lines to make them fit within their containing boxes. Also, for the sake of space, some class names are abbreviated. Specifically, the box representing the class HostedEventProviderArgument is labeled "HostedEventProv...Argument" and the box representing the class SubscriptionConditionScheduledRule is labeled "SubscriptionConditionSched...Rule". The relationships depicted by the connecting lines in Figure 16.1 are containment relationships, not inheritance relationships. In other words, the line that connects the Instance class to the DeliveryChannel class indicates that DeliveryChannel objects are contained within Instance objects, not that DeliveryChannel inherits from Instance. The containment relationships between NMO classes are also characterized as parent-child relationships. When one object is contained within another, we call the containing object the parent and the contained object the child. This can sometimes be confusing because the terms "parent" and "child" are usually used to denote inheritance relationships. However, in the context of NMO, they always refer to containment relationships. Every NMO class has a Parent property that returns the parent object and various appropriately named properties that return child objects. As an example, consider a NotificationClass object that has a child ContentFormatter object. From the child ContentFormatter object, the parent NotificationClass object can be reached via the Parent property. From the parent NotificationClass object, the child ContentFormatter object can be reached via the ContentFormatter property. When an object may have more than one child object of the same type, the children are grouped in collections. For example, an Application object may have several EventClass child objects. The Parent property on each of these child objects refers to the same Application object. On this parent Application object, the EventClass child objects are contained in a collection property named EventClasses. The NMO class hierarchy is rooted at the Server class, which represents a SQL Server instance. Server is actually part of the broader SMO set of classes: it is not specific to NMO. The Server class has a NotificationServices property that contains a collection of NMO Instance objects. The Instance class represents a SQL-NS instance and its child classes represent the entities in an instance, such as delivery channels, protocol definitions, and applications. The Application class represents a SQL-NS application, with child classes for the application-level entities, such as event classes, subscription classes, and distributors. Each NMO class has properties that encapsulate the various attributes of the entity it represents. For example, the EventField class, which represents fields in event class schemas, has properties for the field name, type, and type modifiers. This chapter explores the programming patterns in which the NMO classes are commonly used. It is not a complete class reference. The code listings and text in this chapter cover many examples of NMO usage that illustrate the general functionality of the API. However, you won't see every class pictured in Figure 16.1 used or described in this chapter. Consult the SQL-NS Books Online for complete reference documentation on every NMO class, property, and method. NMO API Assemblies and NamespacesTo use the NMO API, applications must reference the assemblies that contain the needed classes. The following two assemblies are usually required:
The first assembly, Microsoft.SqlServer.Smo.dll, contains most of the classes in the SMO Framework, including the NMO classes (there isn't a separate NMO assembly). The Microsoft.SqlServer.ConnectionInfo.dll contains utility classes used to establish database connections. Classes from both assemblies are typically needed in programs that use the NMO API. Most of the classes you'll encounter while working with NMO are defined in one of the following three namespaces:
The first one is sometimes referred to as the NMO namespace. It contains all the NMO-specific classes. The second namespace contains many of the SMO classes, some of which are needed in NMO programming. The third namespace contains common utility classes, such as those used to establish database connections. Note An NMO-based application need not reference the main SQL-NS assembly (Microsoft.SqlServer.NotificationServices.dll) unless it uses classes in the main SQL-NS namespace, Microsoft.SqlServer.NotificationServices. (Many of the classes in the main SQL-NS namespace are covered in the earlier chapters of this book.) In the previous SQL-NS release, some of the capabilities now provided by the new NMO API were provided as part of the core SQL-NS API. As a result, some overlap exists between the classes in the Microsoft.SqlServer.Management.Nmo and the Microsoft.SqlServer.NotificationServices namespaces. For example, both namespaces contain a class called DeliveryChannel. In every case of overlap, the class in the Microsoft.SqlServer.NotificationServices namespace has been deprecated: the new NMO class should be used instead. Following the standard Microsoft procedure for API deprecation, the old classes that overlap with NMO are marked as deprecated in the SQL Server 2005 documentation. They will be removed from the documentation in the next release, and will be removed entirely in the release following that. Whenever both the Microsoft.SqlServer.Management.Nmo and Microsoft.SqlServer.NotificationServices namespaces are in scope (for example, when both namespaces have been declared in using directives in a source file), you must use fully qualified names to disambiguate some class references. For example, you'll need to refer to the NMO DeliveryChannel class as Microsoft.SqlServer.Management.Nmo.DeliveryChannel. Using class names that exist in both namespaces, without fully qualifying them, will result in compile errors. |
EAN: 2147483647
Pages: 166