Microsoft SQL Server 2005 Developer’s Guide- P9 docx

Listing Subscriptions To list the subscriptions that have been created on a Notification Services instance, you can use the SubscriberEnumeration object as is shown in the following list

Next, add an import directive for the NotificationServices namespace to the

Declarations section of your project Using the import directive enables you to use

the classes in the NotificationServices namespace without requiring you to fully

qualify the names The import directive appears as follows:

Imports Microsoft.SqlServer.NotificationServices

After adding the reference to your project and its associated namespace, you can

create the code to add a subscriber to your Notification Services application

Listing Subscriptions

To list the subscriptions that have been created on a Notification Services instance,

you can use the SubscriberEnumeration object as is shown in the following listing:

' Create the Instance object

Dim myNSInstance As New NSInstance("NSAppInstance")

'Populate the list box

Dim oSubscribers As SubscriberEnumeration = New _

SubscriberEnumeration(myNSInstance)

ListBox1.Items.Clear()

Figure 5-7 Adding a reference to the Notification Services library

1 6 0 M i c r o s o f t S Q L S e r v e r 2 0 0 5 D e v e l o p e r ’s G u i d e

For Each oSub As Subscriber In oSubscribers

' Add each Subscriber Name to the List

ListBox1.Items.Add(oSub.SubscriberId)

Next

At the top of this listing you can see where the Notification Services instance called MyNSInstance is created The important thing to notice in this line is the fact that the value “MSAppInstance” must match the value defined in your ICF file This value can also been found by using SQL Server Management Studio to open the Notification Services node that lists the active instances

Next, a new instance of the SubscriberEnumeration object called oSubscribers is created and a For-Each loop is used to iterate through the collection of subscribers exposed by the SubscriberEnumeration object Within the For-Each loop the name of each subscriber is added to a ListBox that can be displayed to the end user

Adding Subscriptions

Of course, before you can list subscribers you must first add them The following code sample shows how you can add a subscription using the Notification Services managed code API:

' Create the Instance object

Dim myNSInstance As New NSInstance("NSAppInstance")

' Create the Application object

Dim myNSApp As New NSApplication(myNSInstance, "NSApp")

' Create the Subscriber

Dim oSubscriber As New Subscriber(myNSInstance)

oSubscriber.SubscriberId

= TextSub.Text

oSubscriber.Add()

' Add a device for the subscriber

' DeviceName must match subscription

Dim oDevice As New SubscriberDevice(myNSInstance)

oDevice.DeviceName = "myDevice"

oDevice.SubscriberId = TextSub.Text

oDevice.DeviceTypeName = "File"

oDevice.DeviceAddress = TextSub.Text & "@teca.com"

oDevice.DeliveryChannelName = "FileChannel"

oDevice.Add()

' Create the subscription

Dim oSubscription As New Subscription(myNSApp, "ShipStore")

oSubscription("SubscriberLocale") = "en-US"

oSubscription.SubscriberId = TextSub.Text

' Hard code the store ID for the example

oSubscription("StoreID") = 1

'Dim sSubId As String = oSubscription.Add()

oSubscription.Add()

'Display the new Subscriber ID

ListBox1.Items.Add(TextSub.Text)

TextSub.Text = ""

First a Notification Services instance object named myNSInstance is created,

followed by an Application object named myNSApp These must correspond to the

definitions that were previously defined in the XML-based Notification Services

configuration file For this example, the NSInstance object must be created using the

value of “NSAppInstance,” which must match the name of the Notifications Services

Instance as defined in the <InstanceName> element of the ICF file Likewise, the

Application object, NSApplication, must use the value of “NSApp” to match the value

used in the <ApplicationName> element of the ICF file You can also see these values

beneath the Notification Services node in the SQL Server Management Studio

Next, a Subscriber must be created and notification delivery devices must be

added to the subscriber A new subscriber is created by passing the Notification

Services Instance name to the Subscriber object’s constructor Once the Subscriber

object has been instantiated, the SubscriberID property is set with a string value that

identifies the subscriber Here that value comes from a Textbox named TextSub

Then the Add method is called to create the subscriber As you might expect, the

Delete and Update methods must be used if you subsequently want to modify or

delete the subscriber information

NOTE

Adding a subscriber updates the NSDataSubSubscriptions table along with a couple of other tables

in the NSAppInstanceNSApp database However, you should not directly update these tables

Instead, you should only add, update, and delete subscribers using the NotificationServices API or

the stored procedure generated with the Notification Services application.

Once the subscriber has been added, at least one device must be added to the

subscriber using the SubscriberDevice object The SubscriberId in combination with

the DeviceName property uniquely identifies the device in the system The value used

for the DeliveryChannel property specifies the method by which the notification will

1 6 2 M i c r o s o f t S Q L S e r v e r 2 0 0 5 D e v e l o p e r ’s G u i d e

be generated In this example, the notification will be created in the file system The actual output file was defined in the ICF file and will be named NSAppNotification htm You might notice that the device and the subscriber are defined separately This enables a subscriber to have multiple notification delivery mechanisms The Add method is then used to add the device Once the subscriber has been created and a device has been added for the subscriber, you can then create a subscription The subscription links the subscriber to a specific event When you create a new subscription object, you pass in the Application object followed by the name of the subscription class that was defined in your ADF file In this case, the subscription class was named “ShipStore.” Next, the Subscription object’s properties are assigned values You should note that the StoreID is assigned a hard-coded value of 1 This essentially creates a subscription for the subscriber to shipment data for StoreID 1 Then, the Add method is called to actually add the subscription to the database At the end of this code, the subscriber’s name is also added to a ListBox that will be displayed to the end user

NOTE

If you get an ArgumentOutOfRangeException while attempting to create a subscription, it typically means that the values you’ve passed to the subscription object do not match the values that were created in the subscribers section of the acf.xml file.

You can view the subscribers and the devices that have been added by querying the NSSubscriberDeviceView, as shown in the following listing For this sample application, the view is found in the NSAppInstanceNSMain database As mentioned earlier, the name of this database is based in the name of the Notification Services application

View subscribers and devices

USE NSAppInstanceNSMain

SELECT * FROM NSSubscriberDeviceView

The NSShipStore view in the NSAppInstanceNSApp database enables you to view the subscriptions that have been created In this case, the name of the view is based on the name of the event class that was created in the application definition file You can see the query to view the subscribers for the example application in the following listing:

View Subscriptions

USE NSAppInstanceNSApp

Deleting Subscriptions

The following code shows how you can delete subscriptions that have been previously

displayed in a ListBox Like the previous example, the Notification Services

Subscriber object provides the required method to work with the subscriber data

If ListBox1.SelectedIndex < 0 Then

MsgBox("No subscriber has been selected.")

Else

' Create the Instance object

Dim myNSInstance As New NSInstance("NSAppInstance")

' Delete the Subscriber

Dim oSubscriber As New Subscriber(myNSInstance)

oSubscriber.SubscriberId = ListBox1.SelectedItem

oSubscriber.Delete()

' Remove the entry from the list

ListBox1.Items.Remove(ListBox1.SelectedItem)

End If

Firing the Data Event Using NET

Events are data that your notification application uses to generate notifications The

notification generation queries you write join event data and subscription data to

produce notifications The queries that generate notifications are fired during each

generator quantum that has data to process Event rules run in any quantum in which

one or more event batches arrived Scheduled rules run in any quantum that has

scheduled subscriptions expected to be processed

You can see the screen that the example Notification Services client application

uses to create Notification Services events in Figure 5-8

On the Event tab, the user can enter the store ID, the product ID, the product name,

and the number of units shipped In the earlier listing that created a subscription,

you saw that a subscription was created for store ID 1 Therefore, if the user enters

a value for store ID 1, then a Notification Services event will be created Any other

store ID values will not cause an event to fire In the case of the sample application,

no data validation is performed, so you need to enter data values for all of the fields

1 6 4 M i c r o s o f t S Q L S e r v e r 2 0 0 5 D e v e l o p e r ’s G u i d e

Once all of the data has been entered, clicking the OK button will execute the code that you can see in the following listing:

' Create the Instance object

Dim myNSInstance As New NSInstance("NSAppInstance")

' Create the Application object

Dim myNSApp As New NSApplication(myNSInstance, "NSApp")

Dim oEvent As New _

Microsoft.SqlServer.NotificationServices.Event( _

myNSApp, "ShipData")

Dim oEventCollector As New EventCollector(myNSApp, "SQLData")

' Supply the event data

oEvent("StoreId") = TextStore.Text

oEvent("Date") = Now

oEvent("ProductId") = TextProdID.Text

oEvent("ProductName") = TextProdName.Text

oEvent("Units") = TextUnits.Text

oEventCollector.Write(oEvent)

Figure 5-8 The subscription application

At the top of this listing, you can see where the NSInstance and NSApplication

objects are created Next, a new Notification Services Event object named oEvent is

created by passing an instance of the NSApp NSApplication object along with the

value of “ShipData”, the name of the Notification Services event class, to the Event

object’s constructor

The next section of code supplies the required event data The values used for

these field names must match the field values that compose the event class that was

created in the application definition file The ShipData event class used five fields

The StoreId is assigned the value that codes from the TextStore TextBox The Date

field is assigned the current date and time The ProductID, ProductName, and Units

fields are all assigned values from the TextBoxes that you saw earlier in Figure 5-6

After all of the field values have been assigned, the EventCollector Write method

is used to write the events and the Commit method is used to send the events to the

Notification Services application

Figure 5-9 shows the notification that was generated using the values you saw

on Figure 5-8 The sample application used the WebBrowser object with the URL

property pointed to the NSApplication.htm file to display the notification

It should be noted that for this sample application, the notification does not appear

immediately Instead, it is generated according to the schedule that was defined in

the notification class section of the application definition file The example uses a

value of 60 seconds

Figure 5-9 Viewing the notification

1 6 6 M i c r o s o f t S Q L S e r v e r 2 0 0 5 D e v e l o p e r ’s G u i d e

If no notifications are generated, you can use the NSDiagnosticFailedNotifications stored procedure to begin troubleshooting the problem You can see an example of running the NSDiagnosticFailedNotifications stored procedure in the following listing:

View diagnostics

USE NSAppInstanceNSMain

EXEC NSDiagnosticFailedNotifications

Firing the Data Event Using T-SQL

The preceding example illustrated firing a Notification Services event using the NotificationServices API from a client application However, you can also use T-SQL to generate events for your Notification Services application The following listing illustrates calling the NSEventWriteShipData stored procedure to fire an event The NSEventWriteShipData stored procedure is automatically created with your Notification Services application Its actual name is based on the Event Class Name used in the ADF file

USE NSAppInstanceNSApp;

Start an event batch

DECLARE @BatchID bigint;

EXEC dbo.NSEventBeginBatchShipData N'SQLData', @BatchID OUTPUT;

EXEC dbo.NSEventWriteShipData

@EventBatchId=@BatchID,

@StoreID = 1,

@Date='October 1, 2005',

@ProductID = 31,

@ProductName = "Item ThirtyOne",

@Units=31

Flush event batch

EXEC dbo.NSEventFlushBatchShipData @BatchID;

The NSEventWriteShipData stored procedure is intended to be used for batch loading and requires a batch ID as its first parameter Next, you need to supply the data required by the event that you defined in the application’s event class In this example, you can see that a store ID of 1 is used to ensure that the event gets fired You call the NSEventWriteShipData stored procedure for each event that you want

to sent to the application When all of the events have been sent, the NSEventFlush BatchShipData stored procedure is called to send the event data to the Notification Services application

Notification Services is a powerful new subsystem you can use as a basis for building

your own notification applications In this chapter you learned how to define a sample

Notification Services application by creating the instance configuration file and

application definition file as well as how to use the Notification Services API to add

subscribers, subscriptions, and fire notification events

This page intentionally left blank

6

Developing Database Applications with ADO.NET

IN THIS CHAPTER The ADO.NET Architecture ADO.NET Namespaces NET Data Providers Core Classes in the ADO.NET System.Data Namespace Using the NET Framework Data Provider for SQL Server

Using the SqlConnection Object Using the SqlCommand Object Using the SqlDependency Object Using the SqlDataReader Object Using the SqlDataAdapter Object

Copyright © 2006 by The McGraw-Hill Companies Click here for terms of use

1 7 0 M i c r o s o f t S Q L S e r v e r 2 0 0 5 D e v e l o p e r ’s G u i d e

using Visual Basic and ADO.NET The first part of the chapter provides you with an overview of the ADO.NET data access technology The second part

of this chapter introduces you to the different ADO.NET namespaces and gives you

an overall understanding of the functions of the different classes that compose the ADO.NET architecture Finally, the last section of this chapter covers the classes that are used by the ADO.NET DataSet object In this part of the chapter, you’ll get

an understanding of DataTable, DataColumn, DataRow, and other classes used by the new ADO.NET DataSets

The ADO.NET Architecture

At its essence, ADO.NET is data access middleware that enables the development

of database applications ADO.NET builds on the platform provided by the NET Framework ADO.NET is built using managed code from the Microsoft NET Framework, which means that it enjoys the benefits of the robust NET execution time environment Designed primarily to address the issues of Web and distributed applications, ADO.NET consists of a set of classes or namespaces within the .NET Framework that provide data access and management capabilities to NET applications

As a data access framework, ADO.NET has been primarily designed to allow it to

work in the disconnected data access model that is required by n-tiered Web-based

applications ADO, the direct predecessor of ADO.NET, was primarily designed to accommodate a two-tiered client/server style of applications, which typically open

a database connection when the application first starts and then hold that connection open until the application ends This technique works fine for most intranet-style applications where the total number of client connections is a known quantity, and where the state of the application is typically controlled by the application and therefore is also a known quantity Although this approach worked well for single-tier desktop applications and two-single-tiered client/server-style applications, it ran into

serious limitations for n-tiered Web-style applications Because the Web is a public

environment, the total number of open connections required by Web applications isn’t a known quantity It could vary greatly and quickly: At one minute, an application may need only a handful of connections, but the need can jump to thousands of connections just a few minutes later Keeping open connections in this type of environment hurts scalability because each connection must go through the overhead

of initializing the connection with the back-end database, plus each open connection requires system resources to be held open—reducing the resources available for